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.
The crossSwapType determines how swaps are processed within the system.
It controls:
- Which swap strategy to use (bridgeable tokens vs. any tokens)
- How to handle the swap flow (input/output token logic)
- Which quote-fetching functions to call
- How responses and errors are formatted
anyToBridgeablePossible values: Type of amount specification.
exactInputRequired input amount in the smallest unit of the input token.
1000000Maximum amount of input token that may be used.
1000000Expected amount of output token.
467917612181896Minimum guaranteed amount of output token.
464434354522974Expected time in seconds to complete the swap.
2Timestamp when the quote will expire.
1770679043Unique identifier for the swap request.
vqhfb-1770675636494-01dc8983f2fcBad 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.
The crossSwapType determines how swaps are processed within the system.
It controls:
- Which swap strategy to use (bridgeable tokens vs. any tokens)
- How to handle the swap flow (input/output token logic)
- Which quote-fetching functions to call
- How responses and errors are formatted
bridgeableToAnyPossible values: Type of amount specification.
exactInputRequired input amount in the smallest unit of the input token.
1000000Expected amount of output token.
263466241499732Minimum guaranteed amount of output token.
260831579075100Expected time in seconds to complete the swap.
3Timestamp when the quote will expire.
1764640283Unique identifier for the swap request.
6pl4c-1754347045980-2353645c0fb7Bad 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
The status of the deposit.
- filled: Deposits with this status have been filled on the destination chain and the recipient should have received funds. A FilledRelay event was emitted on the destination chain SpokePool.
- pending: Deposit has not been filled yet.
- expired: Deposit has expired and will not be filled. Expired deposits will be refunded to the
depositoron theoriginChainIdin the next batch of repayments. - refunded: Deposit has expired and the depositor has been successfully refunded on the originChain.
The transaction hash of the fill transaction on the destination chain. This field is only present when status is filled.
The chain id where the fill transaction took place.
The chain id where the deposit transaction originally took place.
The deposit Id for the deposit transaction.
The deposit transaction hash.
The deposit refund transaction hash.
Defines if the actions succeeded.
The pagination object defines the currentIndex and maxIndex of the returned deposits.
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
Internal unique identifier for the deposit record.
Hash of the relay data used to verify and track fill events.
Unique identifier assigned to the deposit event on the origin chain.
The chain ID where the deposit was originally made.
The target chain ID where the fill is expected to complete.
Wallet address of the user who initiated the deposit.
Wallet address intended to receive funds on the destination chain.
Address of the token deposited on the origin chain.
Amount of inputToken sent in the deposit (in wei).
Address of the token expected to be received on the destination chain.
Amount of outputToken expected to be received (in wei).
Optional arbitrary bytes message encoded with the deposit intent.
Hash of the message payload.
Address of the relayer granted exclusivity to fill the deposit, if any.
Timestamp indicating when relayer exclusivity expires.
Deadline by which the deposit must be filled before expiring.
Time at which the quote for the deposit was generated.
Transaction hash of the deposit on the origin chain.
Block number where the deposit transaction was confirmed.
Timestamp of the block containing the deposit transaction.
The status of the deposit fill lifecycle.
Transaction hash for refund if deposit expired and funds were returned to the depositor.
USD price of the token used in any optional swap.
Fee paid in USD for the optional swap (if performed).
Fee paid in USD for bridging the funds across chains.
USD price of the input token at the time of deposit.
USD price of the output token at the time of quote.
Gas cost incurred in native token units during fill.
USD value of the gas fee for filling the deposit.
USD price of the gas token on the destination chain at the time of fill.
Transaction hash for any token swap conducted on the destination chain.
Token address used in a swap on the destination chain, if any.
Amount of the swapToken exchanged, if a swap occurred.
Address of the relayer that submitted the fill on the destination chain.
Timestamp when the fill was confirmed on the destination chain.
Transaction hash of the actual fill transaction.
List of transaction hashes representing optional speedup fills.
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
The quote timestamp that was used to compute the lpFeePct. To pay the quoted LP fee, the user would need to pass this quote timestamp to the protocol when sending their bridge transaction.
1708047000Is the input amount below the minimum transfer amount.
falseThe block used associated with this quote, used to compute lpFeePct.
19237525The contract address of the origin SpokePool.
0xe35e9842fceaCA96570B734083f4a58e8F7C5f2AThe relayer that is suggested to be set as the exclusive relayer for in the depositV3 call for the fastest fill. Note: when set to "0x0000000000000000000000000000000000000000", relayer exclusivity will be disabled. This value is returned in cases where using an exclusive relayer is not recommended.
0x428AB2BA90Eba0a4Be7aF34C9Ac451ab061AC010The suggested exclusivity period (in seconds) the exclusive relayer should be given to fill before other relayers are allowed to take the fill. Note: when set to "0", relayer exclusivity will be disabled. This value is returned in cases where using an exclusive relayer is not reccomended.
10The expected time (in seconds) for a fill to be made. Represents 75th percentile of the 7-day rolling average of times (updated daily). Times are dynamic by origin/destination token/chain for a given amount.
4The recommended deadline (UNIX timestamp in seconds) for the relayer to fill the deposit. After this destination chain timestamp, the fill will revert on the destination chain.
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
The minimum deposit size in the tokens' units. Note: USDC has 6 decimals, so this value would be the number of USDC multiplied by 1e6. For WETH, that would be 1e18.
7799819The maximum deposit size in the tokens' units. Note: The formatting of this number is the same as minDeposit.
22287428516241The max deposit size that can be relayed "instantly" on the destination chain. Instantly means that there is relayer capital readily available and that a relayer is expected to relay within seconds to 5 minutes of the deposit.
201958902363The max deposit size that can be relayed with a "short delay" on the destination chain. This means that there is relayer capital available on mainnet and that a relayer will immediately begin moving that capital over the canonical bridge to relay the deposit. Depending on the chain, the time for this can vary. Polygon is the worst case where it can take between 20 and 35 minutes for the relayer to receive the funds and relay. Arbitrum is much faster, with a range between 5 and 15 minutes. Note: if the transfer size is greater than this, the estimate should be between 2-4 hours for a slow relay to be processed from the mainnet pool.
2045367713809The recommended deposit size that can be relayed "instantly" on the destination chain. Instantly means that there is relayer capital readily available and that a relayer is expected to relay within seconds to 5 minutes of the deposit. Value is in the smallest unit of the respective token.
2045367713809Invalid 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
Chain ID of the originating chain.
1Chain ID of the destination chain.
10Origin chain address of token contract to transfer.
0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2Destination chain address of token contract to receive.
0x4200000000000000000000000000000000000006The symbol of the origin token to transfer.
WETHThe symbol of the destination token to receive.
WETHInvalid input
Unexpected error within the API
Last updated