API Reference
Source Code
Pick the Correct API for your Use Case
Caching & Liveness
Testnet Across API
API Endpoints
Bridge and Swap with Swap API
Defines the type of trade execution strategy used in a swap or bridge request. Each trade type specifies how input and output token amounts are determined and how associated fees are handled. Here are the tradeTypes:
- exactInput: Use this when you want to bridge or swap a fixed amount of your inputToken. You define the exact quantity of tokens to send, and the system calculates the amount of outputToken you'll receive after all fees are deducted. If your input isn't sufficient to cover the transaction fees, the request will fail.
- minOutput: Use this when you need to receive at least a certain amount of the outputToken. You set the minimum output you're willing to accept, and the system calculates the necessary input amount, including fees and slippage. Due to price slippage, the final amount you receive will be at least your specified minimum but could be slightly more. This is especially useful for simple swaps without subsequent crosschain actions.
- exactOutput: Use this when you need to receive a precise amount of the destination token. You specify the exact output you require, and the system calculates the total input needed to guarantee that amount. If market conditions prevent the system from delivering that exact amount, the entire transaction is cancelled, and your funds are refunded. This is recommended for multi-step transactions, like providing an exact amount of an ERC20 token to a minting contract.
exactInputPossible values: Required amount is in inputToken if tradeType=exactInput otherwise amount is in outputToken.
1000000Address of the input token on the origin chain.
0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85Address of the output token on the destination chain.
0x82aF49447D8a07e3bd95BD0d56f35241523fBab1Chain ID of the origin chain.
10Chain ID of the destination chain.
42161Address of the depositor initiating the swap.
0xA4d353BBc130cbeF1811f27ac70989F9d568CeABAddress of the account receiving the output token. Defaults to depositor if not provided.
0xA4d353BBc130cbeF1811f27ac70989F9d568CeABEnables integrators to collect a customizable fee in the output token, sent to a designated address on the destination chain. appFee is expressed in percentage with value ranging between 0 and 1.
0.01Address of the account receiving the app fees. Must be defined if you are also defining appFee.
0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB2-byte hex-string that identifies the integrator. E.g., "0xdead".
0xdeadAddress to receive refunds. Defaults to depositor if not provided.
0xDEPOSITOR_ADDRESSFor routes that include a destination swap (bridgeableToAny or anyToAny), destination refunds are the default behavior unless refundOnOrigin=true is explicitly set when calling the Swap API. Across determines refund behavior based on the route type (when refundOnOrigin is NOT explicitly set):
- B2B or A2B routes:
- refundOnOrigin defaults to true
- Refunds occur on the origin chain
- Destination refunds do not apply here
- B2A or A2A routes
- refundOnOrigin defaults to false
- Refunds occur on the destination chain
If an explicit refundOnOrigin value is provided, that value is always respected. If a refund occurs, the address that receives the refunded funds is determined using the following priority order: 1. refundAddress (if explicitly specified) 2. recipient (if specified) 3. depositor (fallback) This applies to both origin and destination refunds.
trueSlippage tolerance percentage can be set to auto (default) or a numerical value. Numerical value must be between 0 and 1 representing corresponding percentage. So if you want slippage to be 0.5% , you need to pass 0.005 as the value here). If slippage is auto, the Swap API will select the best slippage intelligently and move ahead with the crosschain swap. If slippage is set to a numerical value, for example 0.01 (1% slippage), it divides this value equally for each leg. This means 0.5% slippage for origin and 0.5% slippage for destination.
autoUsed to define whether you want to calculate the transaction details (swap) on origin chain. Defaults to false.
trueUsed to define whether you want to strictly follow the defined tradeType. Defaults to true.
trueUsed to define the sources you want to exclude from the crosschain swap action. Defaults to an empty array. Available sources can be retrieved via /swap/sources endpoint
[]Used to define the sources you want to include from the crosschain swap action. Defaults to an empty array. Available sources can be retrieved via /swap/sources endpoint
[]Swap approval data returned successfully.
Bad request due to invalid input parameter.
Insufficient liquidity for same-asset bridging.
Defines the type of trade execution strategy used in a swap or bridge request. Each trade type specifies how input and output token amounts are determined and how associated fees are handled. Here are the tradeTypes:
- exactInput: Use this when you want to bridge or swap a fixed amount of your inputToken. You define the exact quantity of tokens to send, and the system calculates the amount of outputToken you'll receive after all fees are deducted. If your input isn't sufficient to cover the transaction fees, the request will fail.
- minOutput: Use this when you need to receive at least a certain amount of the outputToken. You set the minimum output you're willing to accept, and the system calculates the necessary input amount, including fees and slippage. Due to price slippage, the final amount you receive will be at least your specified minimum but could be slightly more. This is especially useful for simple swaps without subsequent crosschain actions.
- exactOutput: Use this when you need to receive a precise amount of the destination token. You specify the exact output you require, and the system calculates the total input needed to guarantee that amount. If market conditions prevent the system from delivering that exact amount, the entire transaction is cancelled, and your funds are refunded. This is recommended for multi-step transactions, like providing an exact amount of an ERC20 token to a minting contract.
exactInputPossible values: Required amount of output token in smallest unit.
1000000Address of the input token on the origin chain.
0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85Address of the output token on the destination chain.
0x82aF49447D8a07e3bd95BD0d56f35241523fBab1Chain ID of the origin chain.
10Chain ID of the destination chain.
42161Address of the depositor initiating the swap.
0xA4d353BBc130cbeF1811f27ac70989F9d568CeABAddress of the account receiving the output token. Defaults to depositor if not provided.
0xA4d353BBc130cbeF1811f27ac70989F9d568CeABEnables integrators to collect a customizable fee in the output token, sent to a designated address on the destination chain. appFee is expressed in percentage with value ranging between 0 and 1.
0.01Address of the account receiving the app fees. Must be defined if you are also defining appFee.
0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB2-byte hex-string that identifies the integrator. E.g., "0xdead".
0xdeadAddress to receive refunds. Defaults to depositor if not provided.
0xDEPOSITOR_ADDRESSFor routes that include a destination swap (bridgeableToAny or anyToAny), destination refunds are the default behavior unless refundOnOrigin=true is explicitly set when calling the Swap API. Across determines refund behavior based on the route type (when refundOnOrigin is NOT explicitly set):
- B2B or A2B routes:
- refundOnOrigin defaults to true
- Refunds occur on the origin chain
- Destination refunds do not apply here
- B2A or A2A routes
- refundOnOrigin defaults to false
- Refunds occur on the destination chain
If an explicit refundOnOrigin value is provided, that value is always respected. If a refund occurs, the address that receives the refunded funds is determined using the following priority order: 1. refundAddress (if explicitly specified) 2. recipient (if specified) 3. depositor (fallback) This applies to both origin and destination refunds.
trueSlippage tolerance percentage can be set to auto (default) or a numerical value. Numerical value must be between 0 and 1 representing corresponding percentage. So if you want slippage to be 0.5% , you need to pass 0.005 as the value here). If slippage is auto, the Swap API will select the best slippage intelligently and move ahead with the crosschain swap. If slippage is set to a numerical value, for example 0.01 (1% slippage), it divides this value equally for each leg. This means 0.5% slippage for origin and 0.5% slippage for destination.
autoUsed to define whether you want to calculate the transaction details (swap) on origin chain. Defaults to false.
trueUsed to define whether you want to strictly follow the defined tradeType.Defaults to true.
trueUsed to define the sources you want to exclude from the crosschain swap action. Defaults to an empty array.
trueUsed to define the sources you want to include from the crosschain swap action. Defaults to an empty array.
trueSwap approval data returned successfully.
Bad request due to invalid input parameter.
Insufficient liquidity for same-asset bridging.
Chain ID of the chain to get supported sources for.
11List of supported sources for crosschain swaps for a given chain
Bad request
Internal server error
Tracking Deposits
Chain Id where the deposit originated from. This must be used in conjunction with depositId. depositTxHash is not required when using this parameter.
{"value":137}The deposit id that is emitted from the FundsDeposited event. This must be used in conjunction with originChainId. depositTxnRef is not required when using this parameter.
{"value":1349975}The deposit transaction hash that is emitted from the FundsDeposited event. If you are using this, you donot need the other parameters (i.e. originChainId and depositId).
{"value":"0x56a86610aad2a653161c9dd4b4972f948198fd02ae9589cfac1d57bd86a156c1"}Lifecycle of a Transaction
Invalid input
Unexpected error within the API
Maximum number of deposits to return in a single request; used for pagination.
{"value":50}Number of deposits to skip from the beginning of the result set; used for pagination.
{"value":100}Wallet address of the depositor; filters results to deposits made by this address.
{"value":"0x89f423567c2648BB828c3997f60c47b54f57Fa6e"}List of deposits for a given depositor
List of deposits for a given depositor
Bridge with Suggested Fees API
Address of token to bridge on the origin chain. Must be used together with parameter outputToken. For ETH, use the wrapped address, like WETH.
Note that the address provided must exist on the specified originChainId below.
{"value":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"}Address of token to bridge on the destination chain. Must be used together with parameter inputToken. For ETH, use the wrapped address, like WETH.
Note that the address provided must exist on the specified destinationChainId below.
{"value":"0x4200000000000000000000000000000000000006"}Chain ID where the specified token or inputToken exists.
{"value":1}The desired destination chain ID of the bridge transfer.
{"value":10}Amount of the token to transfer.
Note that this amount is in the native decimals of the token. So, for WETH, this would be the amount of human-readable WETH multiplied by 1e18. For USDC, you would multiply the number of human-readable USDC by 1e6.
{"value":"1000000000000000000"}Recipient of the deposit. Can be an EOA or a contract. If this is an EOA and message is defined, then the API will throw a 4xx error.
Example: 0xc186fA914353c44b2E33eBE05f21846F1048bEda
Calldata passed to the recipient if recipient is a contract address. This calldata is passed to the recipient via the recipient's handleAcrossMessage() public function.
Example: 0xABC123
Optionally override the relayer address used to simulate the fillRelay() call that estimates the gas costs needed to fill a deposit. This simulation result impacts the returned suggested-fees. The reason to customize the EOA would be primarily if the recipientAddress is a contract and requires a certain relayer to submit the fill, or if one specific relayer has the necessary token balance to make the fill.
Example: 0x428AB2BA90Eba0a4Be7aF34C9Ac451ab061AC010
The quote timestamp used to compute the LP fees. When bridging with across, the user only specifies the quote timestamp in their transaction. The relayer then determines the utilization at that timestamp to determine the user's fee. This timestamp must be close (within 10 minutes or so) to the current time on the chain where the user is depositing funds and it should be <= the current block timestamp on mainnet. This allows the user to know exactly what LP fee they will pay before sending the transaction.
If this value isn't provided in the request, the API will assume the latest block timestamp on mainnet.
Example: 1653547649
Suggested fees for the transaction and supporting data
Bad request due to invalid input parameter.
Unexpected error within the API
Address of token to bridge on the origin chain. Must be used together with parameter outputToken. For ETH, use the wrapped address, like WETH.
Note that the address provided must exist on the specified originChainId.
{"value":"0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"}Address of token to bridge on the destination chain. Must be used together with parameter inputToken. For ETH, use the wrapped address, like WETH.
Note that the address provided must match the token address on the specified destinationChainId below.
{"value":"0x4200000000000000000000000000000000000006"}Chain ID where the specified token or inputToken exists.
{"value":1}The intended destination chain ID of the bridge transfer.
{"value":10}Transfer limits
Invalid input
Unexpected error within the API
Chain ID of the originating chain.
11Chain ID of the destination chain.
1010Origin chain address of token contract to transfer.
Example: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2Destination chain address of token contract to receive.
Example: 0x4200000000000000000000000000000000000006
0x4200000000000000000000000000000000000006List of available routes
Invalid input
Unexpected error within the API
Last updated