Cross-Chain Swap

This example demonstrates how to swap tokens across different blockchain networks using the Pods API with JavaScript/TypeScript.

Overview

This example covers:

Getting an executable cross-chain quote in one call (GET /v2/swap/quote with wallet addresses)
Executing the origin-chain legs as one atomic EIP-7702 batch
Monitoring status across chains (quoteId vs the Action id)

Prerequisites

Node.js 18+
Pods API key
Wallet with tokens on the origin chain
Basic understanding of async/await

Choose Your Library

ethers.js
viem

Using ethers.js v6 for blockchain interactions - the most popular Ethereum library.

Installation

ethers.js
viem

npm install axios ethers

npm install axios viem

Environment Variables

Create a .env file:

PODS_API_KEY=your-api-key
WALLET_ADDRESS=0x...
PRIVATE_KEY=0x...
ORIGIN_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-key
DESTINATION_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/your-key

Never commit your .env file to version control. Add it to .gitignore.

Step-by-Step Walkthrough

1. Initialize API Client

import axios from 'axios'

const pods = axios.create({
  baseURL: 'https://api.pods.finance',
  headers: {
    'x-api-key': process.env.PODS_API_KEY,
    'Content-Type': 'application/json'
  }
})

2. Get an Executable Cross-Chain Quote (one call)

Pass originAddress, destinationAddress, and refundAddress so the response already includes executable transactionData for the origin chain. New integrations should not call the legacy POST /v2/swap/bytecode.

const { data } = await pods.get('/v2/swap/quote', {
  params: {
    originChain: 'ethereum',
    destinationChain: 'polygon',
    tokenIn: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', // USDC on Ethereum
    tokenOut: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // USDC on Polygon
    amountIn: '1000000000', // 1000 USDC (6 decimals)
    originAddress: walletAddress,
    destinationAddress: walletAddress,
    refundAddress: walletAddress
  }
})

const { quote, transactionData, id: actionId } = data

console.log('Quote ID:', quote.quoteId)   // → GET /v2/swap/status/{quoteId}
console.log('Action ID:', actionId)       // → GET /actions/{id}
console.log('Expected output:', quote.tokenOut.amount)
console.log('Legs to batch on origin:', transactionData.length)

quote.quoteId and the top-level id are different identifiers. Use quote.quoteId with GET /v2/swap/status/{quoteId} for quote settlement, and the top-level id with GET /actions/{id} for the on-chain Action execution record. Cross-chain swaps use bridge providers like TeleSwap or Mayan and may take several minutes to complete.

3. Execute Origin Transactions (atomic batch)

All origin-chain legs must go in one atomic transaction. See Executing Bytecode and cross-chain-swap.js.

import { http, createWalletClient, publicActions } from 'viem'
import { mainnet } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'
import { executeLegsViaEip7702 } from './eip7702-batch.js'

const account = privateKeyToAccount(process.env.PRIVATE_KEY)
const walletClient = createWalletClient({
  account,
  chain: mainnet,
  transport: http(process.env.ORIGIN_RPC_URL)
}).extend(publicActions)

const receipt = await executeLegsViaEip7702(walletClient, transactionData)
console.log('✅ Origin batch confirmed in block', receipt.blockNumber)
console.log('⏳ Waiting for bridge to process...')

4. Monitor Status

Poll quote settlement with quote.quoteId. When you need the on-chain Action execution record instead, poll GET /actions/${actionId} with the top-level id from the quote response.

// Poll for status updates
const swapId = quote.quoteId

let status = 'pending'
while (!['fulfilled', 'failed', 'refunded', 'expired'].includes(status)) {
  await new Promise(resolve => setTimeout(resolve, 10000)) // Wait 10s

  const { data: statusData } = await pods.get(`/v2/swap/status/${swapId}`)

  status = statusData.status
  console.log('Status:', status)

  if (statusData.originTxHash) {
    console.log('Origin TX:', statusData.originTxHash)
  }
  if (statusData.destinationTxHash) {
    console.log('Destination TX:', statusData.destinationTxHash)
  }
}

if (status === 'fulfilled') {
  console.log('Cross-chain swap completed successfully!')
} else {
  console.error('Swap did not complete:', status)
}

Webhook alternative

Pods can POST ACTION_UPDATE events to your server instead of waiting for the next poll. The body is { messageType, data }, and data matches GET /actions/{id}. Registration and signature verification are in Webhooks. Pass webhookURL on the quote to override the customer default for this swap.

Error Handling

try {
  // Your code here
} catch (error) {
  if (error.response?.data?.error) {
    const apiError = error.response.data.error
    console.error('API Error:', apiError.code)
    console.error('Message:', apiError.message)

    if (apiError.code === 'QUOTE_EXPIRED') {
      console.log('Quote expired, please request a new one')
    } else if (apiError.code === 'NO_ROUTE_FOUND') {
      console.log('No cross-chain route available')
    }
  } else {
    console.error('Unexpected error:', error.message)
  }
}

Running the Example

Download both files into the same folder to run this example: cross-chain-swap.js and the shared EIP-7702 batch helper eip7702-batch.js that it imports.

# Install dependencies
npm install

# Set environment variables
cp .env.example .env
# Edit .env with your values

# Run the example
node cross-chain-swap.js

Expected Output

1️⃣  Requesting cross-chain swap quote (one-call — returns executable transactionData)...
   Provider: TeleSwap
   Legs to batch on origin: 2
   quoteId: 550e8400-e29b-41d4-a716-446655440000  |  actionId: 65f1a2b3c4d5e6f789012345

2️⃣  Executing atomic EIP-7702 batch on origin chain...
   ✅ Origin batch confirmed in block 12345678

3️⃣  Monitoring bridge status via quoteId...
   Status: confirmed
   Status: processing
   Status: fulfilled

🎉 Cross-chain swap fulfilled

Next Steps

Same-Chain Swap

Execute same-chain token swaps

Strategy Deposit

Deposit into yield strategies

Swap Guide

Learn more about swaps

API Reference

View complete API documentation

Overview

Guides

Integrations

Agents

Overview

Prerequisites

Choose Your Library

Installation

Environment Variables

Step-by-Step Walkthrough

1. Initialize API Client

2. Get an Executable Cross-Chain Quote (one call)

3. Execute Origin Transactions (atomic batch)

4. Monitor Status

Webhook alternative

Error Handling

Running the Example

Expected Output

Next Steps

Same-Chain Swap

Strategy Deposit

Swap Guide

API Reference