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.

API Endpoints

Retrieve suggested fee quote for a deposit.

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

get

/suggested-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.

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.

originChainIdall ofrequired

Chain ID where the specified token or inputToken exists.

destinationChainIdall ofrequired

The desired destination chain ID of the bridge transfer.

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.

recipientstring

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

messagestring

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

relayerstring

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

timestampinteger

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

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

Suggested fees for the transaction and supporting data

Retrieve current transfer limits of the system

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

get

/limits

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.

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.

originChainIdall ofrequired

Chain ID where the specified token or inputToken exists.

destinationChainIdall ofrequired

The intended destination chain ID of the bridge transfer.

Responses
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"
}

Transfer limits

Retrieve available routes for transfers

Returns available routes based on specified parameters.

get

/available-routes

Query parameters
originChainIdall of

Chain ID of the originating chain.

destinationChainIdall of

Chain ID of the destination chain.

originTokenstring

Origin chain address of token contract to transfer.

Example: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2

Example: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
destinationTokenstring

Destination chain address of token contract to receive.

Example: 0x4200000000000000000000000000000000000006

Example: 0x4200000000000000000000000000000000000006
Responses
curl -L \
  --url 'https://app.across.to/api/available-routes'
[
  {
    "originChainId": "1",
    "destinationChainId": "10",
    "originToken": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "destinationToken": "0x4200000000000000000000000000000000000006",
    "originTokenSymbol": "WETH",
    "destinationTokenSymbol": "WETH"
  }
]

List of available routes

Track the lifecycle of a deposit

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.

get

/deposit/status

Query parameters
originChainIdall ofrequired

Chain Id where the deposit originated from.

depositIdintegerrequired

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

Responses
curl -L \
  --url 'https://app.across.to/api/deposit/status?originChainId=137&depositId=1349975'
{
  "fillStatus": "filled",
  "fillTxHash": "0x123abc<...>",
  "destinationChainId": 42161
}

Lifecycle of a transaction

PreviousCanonical Asset MaximalismNextApp SDK Reference

Last updated