Skip to main content

​
Overview

Pay mode implements exact-output trade flows where you specify the precise amount the recipient receives. The widget calculates the required input amount from the user’s available tokens across all chains. Trade Type: EXACT_OUTPUT - Fixed destination amount, variable input amount.

​
Configuration

​
Required Props

PropTypeDescription
mode"pay"Sets the widget to pay mode
toAddressstringRecipient address
toAmountstringExact amount recipient receives
toChainIdnumberDestination chain ID
toTokenstringDestination token symbol or address

​
Optional Props

PropTypeDescription
toCalldatastringCalldata to execute on destination
slippageTolerancestring | numberSlippage tolerance (e.g., "0.005" for 0.5%)
quoteProviderQuoteProviderSpecific quote provider: "auto" | "lifi" | "relay" | "cctp"

​
Implementation

​
Basic Payment

Simple payment to a recipient address: 
import { TrailsWidget } from '0xtrails/widget'

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="pay"
  toAddress="0x97c4A952b46bEcaD0663f76357d3776ba11566E1"
  toAmount="10"
  toChainId={8453} // Base
  toToken="USDC"
  onCheckoutComplete={({ sessionId }) => {
    console.log('Payment completed:', sessionId)
  }}
>
  <button>Pay 10 USDC</button>
</TrailsWidget>

​
Payment with Contract Call

Execute a function call on the destination chain with the payment: 
import { TrailsWidget } from '0xtrails/widget'
import { encodeFunctionData } from 'viem'

const nftMintCalldata = encodeFunctionData({
  abi: [{
    name: 'mint',
    type: 'function',
    stateMutability: 'payable',
    inputs: [{ name: 'to', type: 'address' }],
    outputs: [],
  }],
  functionName: 'mint',
  args: ['0x97c4A952b46bEcaD0663f76357d3776ba11566E1'],
})

<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="pay"
  toAddress="0xNFT_CONTRACT_ADDRESS"
  toAmount="0.00002"
  toChainId={42161} // Arbitrum
  toToken="ETH"
  toCalldata={nftMintCalldata}
  onCheckoutComplete={({ sessionId }) => {
    console.log('NFT minted:', sessionId)
  }}
>
  <button>Mint NFT (0.00002 ETH)</button>
</TrailsWidget>

​
Payment with Custom Quote Provider

Specify a particular quote provider for routing: 
<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="pay"
  toAddress="0x..."
  toAmount="100"
  toChainId={8453}
  toToken="USDC"
  quoteProvider="cctp" // Use Circle's CCTP
  slippageTolerance="0.01" // 1% slippage
/>

​
Event Handlers

Handle payment lifecycle events: 
<TrailsWidget
  apiKey="YOUR_API_KEY"
  mode="pay"
  toAddress="0x..."
  toAmount="10"
  toChainId={8453}
  toToken="USDC"
  onCheckoutStart={({ sessionId }) => {
    console.log('Payment started:', sessionId)
  }}
  onCheckoutComplete={({ sessionId }) => {
    console.log('Payment completed:', sessionId)
    // Update order status, trigger UI update, etc.
  }}
  onCheckoutError={({ sessionId, error }) => {
    console.error('Payment failed:', error)
    // Handle error state
  }}
/>

​
Use Cases

  • NFT Purchases: Mint or purchase NFTs with payment in one transaction
  • eCommerce Payments: Accept crypto payments for products/services
  • Fixed-price Swaps: Cross-chain token purchases with exact output amounts
  • Contract Execution: Call smart contract functions with attached payment
  • x402 Payments: HTTP 402 payment flows with any token from any chain

​
See Also