API Reference

Source Code

The API is designed to be run serverlessly (without storing state) and is a wrapper on top of the SDK. See full 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.

The exception is the /deposit/status endpoint which is implemented in this stateful repository because it relies on an indexing solution.

Note: Relayer settlement only happens on mainnet. Relayers on the testnet are funded manually by Risk Labs. Therefore we request developers to test with smaller amounts while bridging using the testnet. You can retrieve current limits of the protocol on testnet using the /limits API on the testnet. A complete testnet experience can be found at the Across Testnet Bridge.

Testnet Across API

Please ensure that you use https://testnet.across.to/api as the URL to access the endpoints given below on the testnet. You can use the API on testnet for these supported chains.

Testnet fills typically take around 1 minute, significantly slower than mainnet's 2 second fills. This is because testnet lacks the economic incentives and relayer competition that drive mainnet's performance and reliability. We also recommend users to perform relatively smaller deposits (~$10) as relayer settlement does not occur on the testnet and unfilled deposits are not automatically refunded.

Therefore we only recommend you to use testnet API to ensure your implementation of the API is correct and then switch to mainnet API and experience Across in it's true form.

API Endpoints

Retrieve suggested fee quote for a deposit.

get

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

/suggested-fees

Returns suggested fees based inputToken+outputToken, originChainId, destinationChainId, and amount. Also includes data used to compute the fees.

Query parameters

inputTokenstringRequired

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.

Example: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

outputTokenstringRequired

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.

Example: 0x4200000000000000000000000000000000000006

originChainIdall ofRequired

Chain ID where the specified token or inputToken exists.

Example: 1

integer · enum · min: 1OptionalPossible values:

destinationChainIdall ofRequired

The desired destination chain ID of the bridge transfer.

Example: 10

integer · enum · min: 1OptionalPossible values:

amountinteger · min: 1Required

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.

Example: 1000000000000000000

recipientstringOptional

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

messagestringOptional

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

relayerstringOptional

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

timestampintegerOptional

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

Responses

200

Suggested fees for the transaction and supporting data

application/json

timestampstringOptional

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.

Example: 1708047000

isAmountTooLowbooleanOptional

Is the input amount below the minimum transfer amount.

Example: false

quoteBlockstringOptional

The block used associated with this quote, used to compute lpFeePct.

Example: 19237525

spokePoolAddressstringOptional

The contract address of the origin SpokePool.

Example: 0xe35e9842fceaCA96570B734083f4a58e8F7C5f2A

exclusiveRelayerstringOptional

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

Example: 0x428AB2BA90Eba0a4Be7aF34C9Ac451ab061AC010

exclusivityDeadlinestringOptional

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

Example: 10

expectedFillTimeSecstringOptional

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

Example: 4

fillDeadlinestringOptional

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

400

Invalid input

500

Unexpected error within the API

get

/suggested-fees

Curl

curl -L \
  'https://app.across.to/api/suggested-fees?inputToken=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2&outputToken=0x4200000000000000000000000000000000000006&originChainId=1&destinationChainId=10&amount=1000000000000000000'

{
  "totalRelayFee": {
    "pct": "376607094864283",
    "total": "376607094864283"
  },
  "relayerCapitalFee": {
    "pct": "100200000000000",
    "total": "100200000000000"
  },
  "relayerGasFee": {
    "pct": "276407094864283",
    "total": "276407094864283"
  },
  "lpFee": {
    "pct": "4552495218411721",
    "total": "1708047000"
  },
  "timestamp": "1708047000",
  "isAmountTooLow": false,
  "quoteBlock": "19237525",
  "spokePoolAddress": "0xe35e9842fceaCA96570B734083f4a58e8F7C5f2A",
  "expectedFillTimeSec": "4",
  "fillDeadline": "1737033609",
  "limits": {
    "minDeposit": "7799819",
    "maxDeposit": "22287428516241",
    "maxDepositInstant": "201958902363",
    "maxDepositShortDelay": "2045367713809",
    "recommendedDepositInstant": "201958902363"
  }
}

Retrieve current transfer limits of the system

get

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

/limits

Returns transfer limits for inputToken+outputToken, originChainId, and destinationChainId.

Query parameters

inputTokenstringRequired

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.

Example: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

outputTokenstringRequired

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.

Example: 0x4200000000000000000000000000000000000006

originChainIdall ofRequired

Chain ID where the specified token or inputToken exists.

Example: 1

integer · enum · min: 1OptionalPossible values:

destinationChainIdall ofRequired

The intended destination chain ID of the bridge transfer.

Example: 10

integer · enum · min: 1OptionalPossible values:

Responses

200

Transfer limits

application/json

minDepositstringOptional

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.

Example: 7799819

maxDepositstringOptional

The maximum deposit size in the tokens' units. Note: The formatting of this number is the same as minDeposit.

Example: 22287428516241

maxDepositInstantstringOptional

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 seconds to 5 minutes of the deposit.

Example: 201958902363

maxDepositShortDelaystringOptional

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.

Example: 2045367713809

recommendedDepositInstantstringOptional

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

Example: 2045367713809

400

Invalid input

500

Unexpected error within the API

get

/limits

Curl

curl -L \
  'https://app.across.to/api/limits?inputToken=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2&outputToken=0x4200000000000000000000000000000000000006&originChainId=1&destinationChainId=10'

{
  "minDeposit": "7799819",
  "maxDeposit": "22287428516241",
  "maxDepositInstant": "201958902363",
  "maxDepositShortDelay": "2045367713809",
  "recommendedDepositInstant": "201958902363"
}

Retrieve available routes for transfers

get

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

/available-routes

Returns available routes based on specified parameters.

Query parameters

originChainIdall ofOptional

Chain ID of the originating chain.

anyOptionalExample: 1

and

integer · enum · min: 1OptionalPossible values:

destinationChainIdall ofOptional

Chain ID of the destination chain.

anyOptionalExample: 10

and

integer · enum · min: 1OptionalPossible values:

originTokenstringOptional

Origin chain address of token contract to transfer.

Example: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

Example: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

destinationTokenstringOptional

Destination chain address of token contract to receive.

Example: 0x4200000000000000000000000000000000000006

Example: 0x4200000000000000000000000000000000000006

Responses

200

List of available routes

application/json

originChainIdstringOptional

Chain ID of the originating chain.

Example: 1

destinationChainIdstringOptional

Chain ID of the destination chain.

Example: 10

originTokenstringOptional

Origin chain address of token contract to transfer.

Example: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

destinationTokenstringOptional

Destination chain address of token contract to receive.

Example: 0x4200000000000000000000000000000000000006

originTokenSymbolstringOptional

The symbol of the origin token to transfer.

Example: WETH

destinationTokenSymbolstringOptional

The symbol of the destination token to receive.

Example: WETH

400

Invalid input

500

Unexpected error within the API

get

/available-routes

HTTPcURLJavaScriptPython

GET /api/available-routes HTTP/1.1
Host: app.across.to
Accept: */*

[
  {
    "originChainId": "1",
    "destinationChainId": "10",
    "originToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "destinationToken": "0x4200000000000000000000000000000000000006",
    "originTokenSymbol": "WETH",
    "destinationTokenSymbol": "WETH"
  }
]

Track the lifecycle of a deposit

get

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

/deposit/status

Returns the fill status of a deposit along with a corresponding fill transaction hash if filled.

This endpoint loads data queried by an indexing service that polls relevant events on a 10-second cadence. Users should therefore expect an average latency of 1 to 15 seconds after submitting a deposit to see the status changed in this endpoint. This delay comes from the time it takes for the internal indexing to include the deposit transaction.

Query parameters

originChainIdall ofRequired

Chain Id where the deposit originated from.

Example: 137

integer · enum · min: 1OptionalPossible values:

depositIdintegerRequired

The deposit id that is emitted from the DepositV3 function call as a V3FundsDeposited event.

Example: 1349975

Responses

200

Lifecycle of a transaction

application/json

fillStatusstring · enumOptional

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 FilledV3Relay 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 depositor on the originChainId in the next batch of repayments.
• refunded: Deposit has expired and the depositor has been successfully refunded on the originChain.
• slowFillRequested: Deposit has been made but no relayer has filled the intent, therefore Across' relayer fills the user’s intent without requiring another relayer to front the capital. It's important that the input token and output token are the same asset here.

Possible values:

fillTxHashstringOptional

The transaction hash of the fill transaction on the destination chain. This field is only present when fillStatus is filled.

destinationChainIdintegerOptional

The chain id where the fill transaction will take place.

get

/deposit/status

HTTPcURLJavaScriptPython

GET /api/deposit/status?originChainId=137&depositId=1349975 HTTP/1.1
Host: app.across.to
Accept: */*

200

Lifecycle of a transaction

{
  "fillStatus": "filled",
  "fillTxHash": "0x123abc<...>",
  "destinationChainId": 42161
}

For best results, we recommend using the deposit/status endpoint on mainnet only. Our event indexing currently focuses on mainnet, so testnet queries may return incomplete data.