API Reference

This is a comprehensive walkthrough for developers looking to implement crosschain token swaps using the Across /swap/approval , /swap/chains and /swap/tokens API.

The ideal Across Crosschain Swap API approach involves setting an allowance and executing the transaction directly via the signer. This is a gasful flow.

Let's get started!

---

Get swap approval data

get

https://app.across.to/apihttps://testnet.across.to/api

/swap/approval

Returns data required to execute a crosschain swap. If the input token requires approval, approvalTxns will be included in the response.

Query parameters

tradeTypestring · enumRequired

Type of trade. Use minOutput, exactInput or exactOutput.

Default: exactInputPossible values:

amountstringRequired

Required amount of output token in smallest unit.

Example: 1000000

inputTokenstringRequired

Address of the input token on the origin chain.

Example: 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85

outputTokenstringRequired

Address of the output token on the destination chain.

Example: 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1

originChainIdintegerRequired

Chain ID of the origin chain.

Example: 10

destinationChainIdintegerRequired

Chain ID of the destination chain.

Example: 42161

depositorstringRequired

Address of the depositor initiating the swap.

Example: 0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB

recipientstringRequired

Address of the account receiving the output token.

Example: 0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB

integratorIdstringOptional

2-byte hex-string that identifies the integrator. E.g., "0xdead".

Example: 0xdead

refundAddressstringOptional

Address to receive refunds. Defaults to depositor if not provided.

Default: 0xDEPOSITOR_ADDRESS

refundOnOriginbooleanOptional

Specifies whether refund should be sent on the origin chain. Defaults to true.

Default: true

slippageTolerancenumber · floatOptional

Slippage tolerance percentage (e.g., 1 for 1%, 0.5 for 0.5%).

Default: 1

Responses

200

Swap approval data returned successfully.

application/json

400

Bad request due to invalid input parameter.

application/json

get

/swap/approval

HTTPcURLJavaScriptPython

GET /api/swap/approval?tradeType=exactInput&amount=1000000&inputToken=0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85&outputToken=0x82aF49447D8a07e3bd95BD0d56f35241523fBab1&originChainId=10&destinationChainId=42161&depositor=0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB&recipient=0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB HTTP/1.1
Host: app.across.to
Accept: */*

{
  "crossSwapType": "bridgeableToAny",
  "amountType": "exactInput",
  "checks": {
    "allowance": {
      "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
      "spender": "0x6f26Bf09B1C792e3228e5467807a900A503c0281",
      "actual": "115792089237316195423570985008687907853269984665640564039457584007913099639935",
      "expected": "1000000"
    },
    "balance": {
      "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
      "actual": "7169942",
      "expected": "1000000"
    }
  },
  "steps": {
    "bridge": {
      "inputAmount": "1000000",
      "outputAmount": "980662",
      "tokenIn": {
        "decimals": 6,
        "symbol": "USDC",
        "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
        "name": "USD Coin",
        "chainId": 10
      },
      "tokenOut": {
        "decimals": 6,
        "symbol": "USDC",
        "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "chainId": 42161
      },
      "fees": {
        "totalRelay": {
          "pct": "19338767572622738",
          "total": "19338"
        },
        "relayerCapital": {
          "pct": "100000000000000",
          "total": "100"
        },
        "relayerGas": {
          "pct": "19227000000000000",
          "total": "19227"
        },
        "lp": {
          "pct": "11767572622738",
          "total": "11"
        }
      }
    },
    "destinationSwap": {
      "tokenIn": {
        "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "decimals": 6,
        "symbol": "USDC",
        "chainId": 42161
      },
      "tokenOut": {
        "decimals": 18,
        "symbol": "ETH",
        "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
        "name": "Ether",
        "chainId": 42161
      },
      "inputAmount": "980662",
      "maxInputAmount": "980662",
      "outputAmount": "263466241499732",
      "minOutputAmount": "260831579075100",
      "swapProvider": {
        "name": "0x",
        "sources": [
          "uniswap_v3"
        ]
      }
    }
  },
  "inputToken": {
    "decimals": 6,
    "symbol": "USDC",
    "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
    "name": "USD Coin",
    "chainId": 10
  },
  "outputToken": {
    "decimals": 18,
    "symbol": "ETH",
    "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
    "name": "Ether",
    "chainId": 42161
  },
  "refundToken": {
    "decimals": 6,
    "symbol": "USDC",
    "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
    "name": "USD Coin",
    "chainId": 10
  },
  "fees": {
    "total": {
      "amount": "47651",
      "amountUsd": "0.047642182071510164",
      "pct": "47651283466652296",
      "token": {
        "decimals": 6,
        "symbol": "USDC",
        "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
        "name": "USD Coin",
        "chainId": 10
      }
    },
    "originGas": {
      "amount": "134879133226",
      "amountUsd": "0.000502067341563801",
      "token": {
        "chainId": 10,
        "address": "0x0000000000000000000000000000000000000000",
        "decimals": 18,
        "symbol": "ETH"
      }
    },
    "destinationGas": {
      "amount": "5161137520505",
      "amountUsd": "0.019223327642999999",
      "pct": "19227000000000001",
      "token": {
        "chainId": 42161,
        "address": "0x0000000000000000000000000000000000000000",
        "decimals": 18,
        "symbol": "ETH"
      }
    },
    "relayerCapital": {
      "amount": "100",
      "amountUsd": "0.0000999809",
      "pct": "100000000000000",
      "token": {
        "decimals": 6,
        "symbol": "USDC",
        "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
        "name": "USD Coin",
        "chainId": 10
      }
    },
    "lpFee": {
      "amount": "11",
      "amountUsd": "0.000010997899",
      "pct": "11000000000000",
      "token": {
        "decimals": 6,
        "symbol": "USDC",
        "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
        "name": "USD Coin",
        "chainId": 10
      }
    },
    "relayerTotal": {
      "amount": "19338",
      "amountUsd": "0.019334306442000002",
      "pct": "19338000000000001",
      "token": {
        "decimals": 6,
        "symbol": "USDC",
        "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
        "name": "USD Coin",
        "chainId": 10
      }
    },
    "app": {
      "amount": "0",
      "amountUsd": "0.0",
      "pct": "0",
      "token": {
        "decimals": 18,
        "symbol": "ETH",
        "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
        "name": "Ether",
        "chainId": 42161
      }
    }
  },
  "inputAmount": "1000000",
  "expectedOutputAmount": "263466241499732",
  "minOutputAmount": "260831579075100",
  "expectedFillTime": 3,
  "swapTx": {
    "simulationSuccess": true,
    "chainId": 10,
    "to": "0x6f26Bf09B1C792e3228e5467807a900A503c0281",
    "data": "0xad5425c6000000000000000000000000a4d353bbc130cbef1811f27ac70989f9d568ceab...",
    "gas": "122554",
    "maxFeePerGas": "1100569",
    "maxPriorityFeePerGas": "1100000"
  },
  "id": "6pl4c-1754347045980-2353645c0fb7"
}

---

Get supported chains for swap operations

get

https://app.across.to/apihttps://testnet.across.to/api

/swap/chains

Returns a list of all supported blockchains that support crosschain swaps on Across Protocol.

Responses

200

List of supported chains

application/json

400

Bad request

application/json

500

Internal server error

application/json

get

/swap/chains

HTTPcURLJavaScriptPython

GET /api/swap/chains HTTP/1.1
Host: app.across.to
Accept: */*

[
  {
    "chainId": 1,
    "name": "Ethereum",
    "publicRpcUrl": "https://mainnet.gateway.tenderly.co",
    "explorerUrl": "https://etherscan.io",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/mainnet/assets/logo.svg"
  },
  {
    "chainId": 10,
    "name": "Optimism",
    "publicRpcUrl": "https://mainnet.optimism.io",
    "explorerUrl": "https://optimistic.etherscan.io",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/optimism/assets/logo.svg"
  },
  {
    "chainId": 137,
    "name": "Polygon",
    "publicRpcUrl": "https://polygon.drpc.org",
    "explorerUrl": "https://polygonscan.com",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/polygon/assets/logo.svg"
  },
  {
    "chainId": 42161,
    "name": "Arbitrum",
    "publicRpcUrl": "https://arb1.arbitrum.io/rpc",
    "explorerUrl": "https://arbiscan.io",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/arbitrum/assets/logo.svg"
  },
  {
    "chainId": 324,
    "name": "zkSync",
    "publicRpcUrl": "https://mainnet.era.zksync.io",
    "explorerUrl": "https://era.zksync.network",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/zk-sync/assets/logo.svg"
  },
  {
    "chainId": 8453,
    "name": "Base",
    "publicRpcUrl": "https://mainnet.base.org",
    "explorerUrl": "https://basescan.org",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/base/assets/logo.svg"
  },
  {
    "chainId": 59144,
    "name": "Linea",
    "publicRpcUrl": "https://rpc.linea.build",
    "explorerUrl": "https://lineascan.build",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/linea/assets/logo.svg"
  },
  {
    "chainId": 34443,
    "name": "Mode",
    "publicRpcUrl": "https://mainnet.mode.network",
    "explorerUrl": "https://explorer.mode.network",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/mode/assets/logo.svg"
  },
  {
    "chainId": 81457,
    "name": "Blast",
    "publicRpcUrl": "https://rpc.blast.io",
    "explorerUrl": "https://blastscan.io",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/blast/assets/logo.svg"
  },
  {
    "chainId": 1135,
    "name": "Lisk",
    "publicRpcUrl": "https://rpc.api.lisk.com",
    "explorerUrl": "https://blockscout.lisk.com",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/lisk/assets/logo.svg"
  },
  {
    "chainId": 534352,
    "name": "Scroll",
    "publicRpcUrl": "https://rpc.scroll.io",
    "explorerUrl": "https://scrollscan.com",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/scroll/assets/logo.svg"
  },
  {
    "chainId": 690,
    "name": "Redstone",
    "publicRpcUrl": "https://rpc.redstonechain.com",
    "explorerUrl": "https://explorer.redstone.xyz",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/redstone/assets/logo.svg"
  },
  {
    "chainId": 7777777,
    "name": "Zora",
    "publicRpcUrl": "https://rpc.zora.energy",
    "explorerUrl": "https://explorer.zora.energy",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/zora/assets/logo.svg"
  },
  {
    "chainId": 480,
    "name": "World Chain",
    "publicRpcUrl": "https://worldchain-mainnet.g.alchemy.com/public",
    "explorerUrl": "https://worldchain-mainnet-explorer.alchemy.com",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/world-chain/assets/logo.svg"
  },
  {
    "chainId": 41455,
    "name": "Aleph Zero",
    "publicRpcUrl": "https://rpc.alephzero.raas.gelato.cloud",
    "explorerUrl": "https://evm-explorer.alephzero.org",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/aleph-zero/assets/logo.svg"
  },
  {
    "chainId": 57073,
    "name": "Ink",
    "publicRpcUrl": "https://rpc-gel.inkonchain.com",
    "explorerUrl": "https://explorer.inkonchain.com",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/ink/assets/logo.svg"
  },
  {
    "chainId": 1868,
    "name": "Soneium",
    "publicRpcUrl": "https://rpc.soneium.org",
    "explorerUrl": "https://soneium.blockscout.com",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/soneium/assets/logo.svg"
  },
  {
    "chainId": 130,
    "name": "Unichain",
    "publicRpcUrl": "https://mainnet.unichain.org",
    "explorerUrl": "https://uniscan.xyz",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/unichain/assets/logo.svg"
  },
  {
    "chainId": 232,
    "name": "Lens",
    "publicRpcUrl": "https://api.lens.matterhosted.dev",
    "explorerUrl": "https://explorer.lens.xyz",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/lens/assets/logo.svg"
  },
  {
    "chainId": 56,
    "name": "BNB Smart Chain",
    "publicRpcUrl": "https://bsc-dataseed1.binance.org",
    "explorerUrl": "https://bscscan.com",
    "logoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/bsc/assets/logo.svg"
  }
]

Get supported tokens for swap operations

get

https://app.across.to/apihttps://testnet.across.to/api

/swap/tokens

Returns a list of all supported tokens that support crosschain swaps on Across Protocol.

Responses

200

List of supported tokens

application/json

400

Bad request

application/json

500

Internal server error

application/json

get

/swap/tokens

HTTPcURLJavaScriptPython

GET /api/swap/tokens HTTP/1.1
Host: app.across.to
Accept: */*

[
  {
    "chainId": 1,
    "tokenAddress": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "tokenSymbol": "WETH",
    "tokenDecimals": 18,
    "tokenChainId": 1,
    "tokenLogoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/mainnet/assets/logo.svg"
  },
  {
    "chainId": 10,
    "tokenAddress": "0x4200000000000000000000000000000000000006",
    "tokenSymbol": "ETH",
    "tokenDecimals": 18,
    "tokenChainId": 10,
    "tokenLogoUrl": "https://raw.githubusercontent.com/across-protocol/frontend/master/scripts/chain-configs/mainnet/assets/logo.svg"
  }
]

---

With this, you have now completely understood the core principles of using the /swap endpoint. If you have any doubts, please feel free to reach out to us here.