Across API

Source code:

The API is designed to be run serverlessly (without storing state) and is a wrapper on top of the SDK. Implementation here.

Caching & Liveness

Users of the Across API are requested to cache results for no longer than 300 seconds.

The Across API serves data that is derived from the on-chain state of the Across contracts and relayer bots. The on-chain state is subject to change each block, and cached data can quickly become invalid as a result.

Calculating Suggested Fees

The API uses the Across SDK under the hood, but offers a convenient way to get suggested fees when placing a Deposit transaction.

Example:

You can visit this example in your browser: Link.

Or curl it on the CLI:

curl "https://across.to/api/suggested-fees?token=0x7f5c764cbc14f9669b88837ca1490cca17c31607&destinationChainId=42161&amount=100000000000"

Note: When filling relays, it is strongly recommended to use the Across SDK relayFeeCalculator. Using the suggested-fees API endpoint is done at the relayer's own risk.

API Definition

All API calls use https://across.to/apias the host.

suggested-fees

Path: /suggested-fees

Method: GET

Query Params

Parameter Name Description Example

Parameter Name	Description	Example
token	Address of token contract to transfer. For ETH (or other native tokens, like matic) use, use the wrapped address, like WETH. Note: the address provided can be the token address on any chain. In the unlikely event where two different tokens have the same address on different chains, you can use the optional chainId parameter defined below to indicate which chain should be used.	0x7f5c764cbc14f9669b88837ca1490cca17c31607
destinationChainId	The intended destination of the transfer.	42161
amount	Amount of the token to transfer. Note: 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`.	100000000000
originChainId (optional)	Used to specify which chain where the specified token address exists. Note: this is only needed to disambiguate when there are matching addresses on different chains. Otherwise, this can be inferred by the API.	10
recipient (optional)	The recipient of the deposit. This can be an EOA or a contract. If this is an EOA and `message` is defined, then the API will throw a 4xx error.	0xc186fa914353c44b2e33ebe05f21846f1048beda
message (optional)	Specifies calldata that is passed to the `recipient` if recipient is a contract address. This calldata is passed to the recipient via the recipient's `handleAcrossMessage()` public function here. The length of this value is constrained by the API to ~4096 chars minus the length of the full URL.	0xABC123
relayer (optional)	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.	0x428ab2ba90eba0a4be7af34c9ac451ab061ac010
timestamp (optional)	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.	1653547649

token

Address of token contract to transfer. For ETH (or other native tokens, like matic) use, use the wrapped address, like WETH. Note: the address provided can be the token address on any chain. In the unlikely event where two different tokens have the same address on different chains, you can use the optional chainId parameter defined below to indicate which chain should be used.

0x7f5c764cbc14f9669b88837ca1490cca17c31607

destinationChainId

The intended destination of the transfer.

42161

amount

Amount of the token to transfer. Note: 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.

100000000000

originChainId (optional)

Used to specify which chain where the specified token address exists. Note: this is only needed to disambiguate when there are matching addresses on different chains. Otherwise, this can be inferred by the API.

recipient (optional)

The recipient of the deposit. This can be an EOA or a contract. If this is an EOA and message is defined, then the API will throw a 4xx error.

0xc186fa914353c44b2e33ebe05f21846f1048beda

message (optional)

Specifies calldata that is passed to the recipient if recipient is a contract address. This calldata is passed to the recipient via the recipient's handleAcrossMessage() public function here. The length of this value is constrained by the API to ~4096 chars minus the length of the full URL.

0xABC123

relayer (optional)

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.

0x428ab2ba90eba0a4be7af34c9ac451ab061ac010

timestamp (optional)

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.

1653547649

Returns a JSON object with the following properties:

Property Name Description Example

Property Name	Description	Example
relayFeePct	The percentage of the transfer amount that should go to the relayer as a fee. This is the strongly recommended minimum value to ensure a relayer will perform the transfer under the current network conditions. The value returned in this field is guaranteed to be at least 0.03% in order to meet minimum relayer fee requirements. Note: 1% is represented as `1e16`, 100% is `1e18`, 50% is `5e17`, etc. These values are in the same format that the contract understands.	61762946000000000
lpFeePct	The percent of the amount that will go to the LPs as a fee for borrowing their funds. The formatting of the percentage is the same as `relayFeePct` .	1252191895805000
timestamp	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.	1646925270

relayFeePct

The percentage of the transfer amount that should go to the relayer as a fee. This is the strongly recommended minimum value to ensure a relayer will perform the transfer under the current network conditions.

The value returned in this field is guaranteed to be at least 0.03% in order to meet minimum relayer fee requirements.

Note: 1% is represented as 1e16, 100% is 1e18, 50% is 5e17, etc. These values are in the same format that the contract understands.

61762946000000000

lpFeePct

The percent of the amount that will go to the LPs as a fee for borrowing their funds. The formatting of the percentage is the same as relayFeePct .

1252191895805000

timestamp

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.

1646925270

Errors:

400: invalid input.
500: an unexpected error within the API.

Querying Limits

The API uses the UMA SDK under the hood, but offers a convenient way to get transfer limits.

Example: Finding limits for bridging USDC from Optimism to Arbitrum.

You can visit this example in your browser: Link

Or curl it on the CLI:

curl "https://across.to/api/limits?token=0x7f5c764cbc14f9669b88837ca1490cca17c31607&destinationChainId=42161"

API Definition

All API calls use https://across.to/apias the host.

limits

Path: /limits

Method: GET

Query Params

Parameter Name	Description	Example
token	Address of token contract to transfer. For ETH (or other native tokens, like matic) use, use the wrapped address, like WETH. Note: the address provided can be the token address on any chain. In the unlikely event where two different tokens have the same address on different chains, you can use the optional chainId parameter defined below to indicate which chain should be used.	0x7f5c764cbc14f9669b88837ca1490cca17c31607
destinationChainId	The intended destination of the transfer.	42161
originChainId (optional)	Used to specify which chain where the specified token address exists. Note: this is only needed to disambiguate when there are matching addresses on different chains. In that case, an arbitrary one will be chosen, so it is recommended that this is always provided.	10

Parameter Name

Description

Example

token

0x7f5c764cbc14f9669b88837ca1490cca17c31607

destinationChainId

The intended destination of the transfer.

42161

originChainId (optional)

Used to specify which chain where the specified token address exists. Note: this is only needed to disambiguate when there are matching addresses on different chains. In that case, an arbitrary one will be chosen, so it is recommended that this is always provided.

Returns a JSON object with the following properties:

Property Name Description Example

Property Name	Description	Example
minDeposit	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`.	7799819
maxDeposit	The maximum deposit size in the tokens' units. Note: The formatting of this number is the same as minDeposit.	22287428516241
maxDepositInstant	The 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 1-4 minutes of the deposit.	201958902363
maxDepositShortDelay	The 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.	2045367713809

minDeposit

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.

7799819

maxDeposit

The maximum deposit size in the tokens' units.

Note: The formatting of this number is the same as minDeposit.

22287428516241

maxDepositInstant

The 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 1-4 minutes of the deposit.

201958902363

maxDepositShortDelay

The 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.

2045367713809

Errors:

400: invalid input.
500: an unexpected error within the API.

Finding Available Routes

Example:

You can visit this example in your browser: Link

Or curl it on the CLI:

curl "https://across.to/api/available-routes"

API Definition

All API calls use https://across.to/apias the host.

`available-routes`

Path: /available-routes

Method: GET

Query Params

Property Name	Description	Example
originChainId	The chain ID of the originating chain to a bridge transfer. Note: This is an optional query parameter. This parameter will filter the response JSON based. This filter can be used in addition to additional parameters to create a custom filter.	1
destinationChainId	The chain ID of the destination chain to a bridge transfer. Note: This is an optional query parameter. This parameter will filter the response JSON based. This filter can be used in addition to additional parameters to create a custom filter.	10
originToken	The token address of the originating bridge transfer. Must be a valid ERC-20 token address. Note: This is an optional query parameter. This parameter will filter the response JSON based. This filter can be used in addition to additional parameters to create a custom filter.	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
destinationToken	The token address that funds will be transferred to at the destination chain. Must be a valid ERC-20 token address. Note: This is an optional query parameter. This parameter will filter the response JSON based. This filter can be used in addition to additional parameters to create a custom filter.	0x4200000000000000000000000000000000000006

Property Name

Description

Example

originChainId

The chain ID of the originating chain to a bridge transfer.

Note: This is an optional query parameter. This parameter will filter the response JSON based. This filter can be used in addition to additional parameters to create a custom filter.

destinationChainId

The chain ID of the destination chain to a bridge transfer.

Note: This is an optional query parameter. This parameter will filter the response JSON based. This filter can be used in addition to additional parameters to create a custom filter.

originToken

The token address of the originating bridge transfer.

Must be a valid ERC-20 token address.

Note: This is an optional query parameter. This parameter will filter the response JSON based. This filter can be used in addition to additional parameters to create a custom filter.

0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

destinationToken

The token address that funds will be transferred to at the destination chain. Must be a valid ERC-20 token address.

Note: This is an optional query parameter. This parameter will filter the response JSON based. This filter can be used in addition to additional parameters to create a custom filter.

0x4200000000000000000000000000000000000006

Returns a JSON array of Objects with the following properties:

Property Name	Description	Example
originChainId	The chain ID of the originating chain to a bridge transfer.	1
destinationChainId	The chain ID of the destination chain to a bridge transfer.	10
originToken	The token address of the originating bridge transfer. Note: this will be a valid ERC-20 token address.	0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
destinationToken	The token address that funds will be transferred to at the destination chain. Note: this will be a valid ERC-20 token address.	0x4200000000000000000000000000000000000006

Property Name

Description

Example

originChainId

The chain ID of the originating chain to a bridge transfer.

destinationChainId

The chain ID of the destination chain to a bridge transfer.

originToken

The token address of the originating bridge transfer.

Note: this will be a valid ERC-20 token address.

0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

destinationToken

The token address that funds will be transferred to at the destination chain. Note: this will be a valid ERC-20 token address.

0x4200000000000000000000000000000000000006

Errors:

400: invalid input.
500: an unexpected error within the API.

PreviousDisputing Root Bundles NextAcross SDK

Last updated 1 year ago