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.

GEThttps://app.across.to/api/suggested-fees

Query parameters

Response

Suggested fees for the transaction and supporting data

Body

totalRelayFeeobject

relayerCapitalFeeobject

relayerGasFeeobject

lpFeeobject

timestampstring

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"

isAmountTooLowboolean

Is the input amount below the minimum transfer amount.

Example: false

quoteBlockstring

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

Example: "19237525"

spokePoolAddressstring

The contract address of the origin SpokePool.

Example: "0xe35e9842fceaCA96570B734083f4a58e8F7C5f2A"

exclusiveRelayerstring

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"

exclusivityDeadlinestring

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"

expectedFillTimeSecstring

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"

limitsTransferLimits (object)

Request

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

Response

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

Retrieve current transfer limits of the system

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

GEThttps://app.across.to/api/limits

Query parameters

Response

Transfer limits

Body

minDepositstring

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

maxDepositstring

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

Example: 22287428516241

maxDepositInstantstring

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

maxDepositShortDelaystring

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

recommendedDepositInstantstring

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

Request

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

Response

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

Retrieve available routes for transfers

Returns available routes based on specified parameters.

GEThttps://app.across.to/api/available-routes

Query parameters

Response

List of available routes

Body

originChainIdstring

Chain ID of the originating chain.

Example: 1

destinationChainIdstring

Chain ID of the destination chain.

Example: 10

originTokenstring

Origin chain address of token contract to transfer.

Example: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"

destinationTokenstring

Destination chain address of token contract to receive.

Example: "0x4200000000000000000000000000000000000006"

originTokenSymbolstring

The symbol of the origin token to transfer.

Example: "WETH"

destinationTokenSymbolstring

The symbol of the destination token to receive.

Example: "WETH"

Request

const response = await fetch('https://app.across.to/api/available-routes', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

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

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.

GEThttps://app.across.to/api/deposit/status

Query parameters

Response

Lifecycle of a transaction

Body

fillStatusenum

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.

filledpendingexpired

fillTxHashstring

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

destinationChainIdinteger

The chain id where the fill transaction will take place.

Request

const response = await fetch('https://app.across.to/api/deposit/status?originChainId=%5Bobject+Object%5D', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

{
  "fillStatus": "filled",
  "fillTxHash": "text"
}

PreviousCanonical Asset Maximalism NextApp SDK Reference

Last updated 2 months ago

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": "4552495218411721" }, "timestamp": "1708047000", "isAmountTooLow": false, "quoteBlock": "19237525", "spokePoolAddress": "0xe35e9842fceaCA96570B734083f4a58e8F7C5f2A", "exclusiveRelayer": "0x428AB2BA90Eba0a4Be7aF34C9Ac451ab061AC010", "exclusivityDeadline": "10", "expectedFillTimeSec": "4", "limits": { "minDeposit": 7799819, "maxDeposit": 22287428516241, "maxDepositInstant": 201958902363, "maxDepositShortDelay": 2045367713809, "recommendedDepositInstant": 2045367713809 } }