TransactionUrl

ERC-681 compliant transaction URL format for QR codes and deep links

Overview

TransactionUrl is a branded string type implementing the ERC-681 standard for representing Ethereum transactions as URLs. This enables QR code generation, deep linking, and wallet integrations.

import * as TransactionUrl from '@tevm/primitives/TransactionUrl'

// Parse URL
const parsed = TransactionUrl.parse('ethereum:0x1234...@1?value=1000000000000000000')

// Format URL
const url = TransactionUrl.format({
  target: address,
  chainId: 1n,
  value: 1000000000000000000n,
})

URL Format

ERC-681 defines the format: ethereum:<address>[@<chainId>][/<function>][?<params>]

Examples:

• ethereum:0x1234... - Simple transfer to address
• ethereum:0x1234@1 - Transfer on mainnet (chainId 1)
• ethereum:0x1234@1?value=1000000000000000000 - Transfer 1 ETH
• ethereum:0x1234/transfer?address=0x5678&uint256=100 - ERC-20 transfer call

Type Definitions

// Branded URL string
type TransactionUrl = string & { readonly [brand]: "TransactionUrl" }

// Parsed URL components
type ParsedTransactionUrl = {
  readonly target: AddressType
  readonly chainId?: bigint
  readonly value?: bigint
  readonly gas?: bigint
  readonly gasPrice?: bigint
  readonly data?: BytesType
  readonly functionName?: string
  readonly functionParams?: Record<string, string>
}

Creating TransactionUrls

from

Create a branded TransactionUrl from a string. Validates the URL format.

const url = TransactionUrl.from('ethereum:0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e@1')

Throws InvalidTransactionUrlError if the URL is malformed.

format

Build a URL from transaction parameters.

import * as TransactionUrl from '@tevm/primitives/TransactionUrl'
import * as Address from '@tevm/primitives/Address'

const target = Address.from('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')

// Simple transfer
const url1 = TransactionUrl.format({
  target,
  chainId: 1n,
  value: 1000000000000000000n, // 1 ETH in wei
})
// 'ethereum:0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e@1?value=1000000000000000000'

// With gas parameters
const url2 = TransactionUrl.format({
  target,
  chainId: 1n,
  value: 1000000000000000000n,
  gas: 21000n,
  gasPrice: 20000000000n,
})

// Contract function call
const url3 = TransactionUrl.format({
  target,
  chainId: 1n,
  functionName: 'transfer',
  functionParams: {
    address: '0x5678...',
    uint256: '100',
  },
})
// 'ethereum:0x742d35...@1/transfer?address=0x5678...&uint256=100'

Parsing TransactionUrls

parse

Parse a URL string into its components.

const parsed = TransactionUrl.parse('ethereum:0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e@1?value=1000000000000000000')

// parsed.target    - AddressType
// parsed.chainId   - 1n
// parsed.value     - 1000000000000000000n

Supported query parameters:

• value - Wei amount (decimal or hex with 0x)
• gas - Gas limit
• gasPrice - Gas price in wei
• data - Hex-encoded calldata (0x…)
• Other parameters are stored in functionParams

Throws InvalidTransactionUrlError for:

• Missing ethereum: scheme
• Invalid address
• Invalid chain ID
• Malformed numeric parameters
• Invalid hex data

// Parsing errors
try {
  TransactionUrl.parse('http://example.com')
} catch (e) {
  // InvalidTransactionUrlError: Invalid URL scheme, expected 'ethereum:'
}

try {
  TransactionUrl.parse('ethereum:invalid')
} catch (e) {
  // InvalidTransactionUrlError: Invalid Ethereum address
}

Error Handling

InvalidTransactionUrlError

Thrown when URL operations fail. Extends InvalidFormatError from the error hierarchy.

import { InvalidTransactionUrlError } from '@tevm/primitives/TransactionUrl'

class InvalidTransactionUrlError extends InvalidFormatError {
  name: "InvalidTransactionUrlError"
  code: "INVALID_TRANSACTION_URL"
  value: unknown
  expected: string
  details?: Record<string, unknown>
  docsPath?: string
}

Properties:

Property	Type	Description
name	string	Always "InvalidTransactionUrlError"
code	string	Always "INVALID_TRANSACTION_URL"
value	unknown	The invalid value that caused the error
expected	string	Description of what was expected
details	Record<string, unknown>	Additional contextual information
docsPath	string	Link to documentation

Error details include contextual information:

• url - The malformed URL
• scheme - For scheme errors
• address - For address errors
• chainId - For chain ID errors

Example:

import * as TransactionUrl from '@tevm/primitives/TransactionUrl'
import { InvalidTransactionUrlError } from '@tevm/primitives/TransactionUrl'

try {
  TransactionUrl.parse('http://example.com')
} catch (error) {
  if (error instanceof InvalidTransactionUrlError) {
    console.log(error.name)    // "InvalidTransactionUrlError"
    console.log(error.code)    // "INVALID_TRANSACTION_URL"
    console.log(error.details) // { url: "http://example.com", scheme: "http" }
  }
}

Use Cases

QR Code Generation

import * as TransactionUrl from '@tevm/primitives/TransactionUrl'
import * as Address from '@tevm/primitives/Address'
import QRCode from 'qrcode'

const target = Address.from('0x742d35Cc6634C0532925a3b844Bc9e7595f51e3e')

const url = TransactionUrl.format({
  target,
  chainId: 1n,
  value: 1000000000000000000n, // 1 ETH
})

// Generate QR code for wallet scanning
const qr = await QRCode.toDataURL(url)

Payment Links

// Create payment request link
const paymentUrl = TransactionUrl.format({
  target: merchantAddress,
  chainId: 1n,
  value: priceInWei,
})

// Use in anchor tag or button
const link = `<a href="${paymentUrl}">Pay with Ethereum</a>`

ERC-20 Token Transfers

// Token transfer via function call
const tokenTransferUrl = TransactionUrl.format({
  target: tokenContractAddress,
  chainId: 1n,
  functionName: 'transfer',
  functionParams: {
    address: recipientAddress,
    uint256: tokenAmount.toString(),
  },
})

Parsing Deep Links

// Handle incoming deep link in dApp
function handleDeepLink(urlString: string) {
  try {
    const tx = TransactionUrl.parse(urlString)

    // Build transaction from parsed data
    return {
      to: tx.target,
      chainId: tx.chainId,
      value: tx.value,
      gas: tx.gas,
      gasPrice: tx.gasPrice,
      data: tx.data,
    }
  } catch (e) {
    console.error('Invalid transaction URL:', e)
  }
}

See Also

• Address - Ethereum address type
• Transaction - Transaction encoding/decoding
• EIP-681 - Transaction URL specification