Across is now live on BNB Smart Chain!
Bridge Now!
Across Documentation
V3 Developer Docs
V3 Developer Docs
  • 👋Introduction
    • Welcome to Across
    • What is Across?
    • Technical FAQ
    • Migration Guides
      • Migration from V2 to V3
      • Migration to CCTP
        • Migration Guide for Relayers
        • Migration Guide for API Users
      • Migration Guide for Non-EVM and Prefills
        • Breaking Changes for Indexers
        • Breaking Changes for API Users
        • Breaking Changes for Relayers
        • Testnet Environment for Migration
      • Solana Migration Guide
      • BNB Smart Chain Migration Guide
  • 🚀DEVELOPER QUICKSTART
    • Instant Bridging in your Application
      • Bridge Integration Guide
      • Multichain Bridge UI Guide
      • Single Chain Bridge UI Guide
    • Embedded Crosschain Actions
      • Crosschain Actions Integration Guide
        • Using the Generic Multicaller Handler Contract
        • Using a Custom Handler Contract
      • Crosschain Actions UI Guide
    • Settle Crosschain Intents
    • ERC-7683 in Production
  • 🧠Concepts
    • What are Crosschain Intents?
    • Intents Architecture in Across
    • Intent Lifecycle in Across
    • Canonical Asset Maximalism
  • 🛠️Reference
    • API Reference
    • App SDK Reference
    • Contracts
      • Aleph Zero
      • Arbitrum
      • Base
      • Blast
      • BNB Smart Chain
      • Ethereum
      • Linea
      • Lens Chain
      • Ink
      • Lisk
      • Mode
      • Optimism
      • Polygon
      • Redstone
      • Scroll
      • Soneium
      • Unichain
      • World Chain
      • zkSync
      • Zora
    • Selected Contract Functions
    • Supported Chains
    • Fees in the System
    • Actors in the System
    • Security Model and Verification
      • Disputing Root Bundles
      • Validating Root Bundles
    • Tracking Events
  • 🔁Relayers
    • Running a Relayer
    • Relayer Nomination
  • 📚Resources
    • Release Notes
    • Developer Support
    • Bug Bounty
    • Audits
Powered by GitBook
LogoLogo

Products

  • Across Bridge
  • Across+
  • Across Settlement

Socials

  • Discord
  • Twitter
  • Medium
  • Forum

Resources

  • Blog
  • Across Brand Assets
  • Github

Routes

  • Bridge to Unichain
  • Bridge to Arbitrum
  • Bridge to Optimism
  • Bridge to Linea
  • Bridge to Polygon
  • Bridge to Base
  • Bridge to World Chain
  • Bridge to zkSync
On this page
  1. Reference

API Reference

PreviousCanonical Asset MaximalismNextApp SDK Reference

Last updated 5 days ago

Source Code

The API is designed to be run serverlessly (without storing state) and is a wrapper on top of the . See full implementation .

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

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

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

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.

🛠️
SDK
here
this stateful repository
Across Testnet Bridge
supported chains.

Get all deposits for a given depositor

get

Returns all deposits for a given depositor.

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
limitintegerOptional

Maximum number of deposits to return in a single request; used for pagination.

Example: 50
skipintegerOptional

Number of deposits to skip from the beginning of the result set; used for pagination.

Example: 100
depositorstringOptional

Wallet address of the depositor; filters results to deposits made by this address.

Example: 0x89f423567c2648BB828c3997f60c47b54f57Fa6e
Responses
200
List of deposits for a given depositor
application/json
get
GET /api/deposits HTTP/1.1
Host: app.across.to
Accept: */*
200

List of deposits for a given depositor

{
  "[\n  {\n      \"id\": 12108048,\n      \"relayHash\": \"0x1496b885808d5c0c03db1287841408be6d9968b70ebba8ef9f771d8f5ab82c3f\",\n      \"depositId\": \"3346250\",\n      \"originChainId\": 42161,\n      \"destinationChainId\": 232,\n      \"depositor\": \"0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB\",\n      \"recipient\": \"0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB\",\n      \"inputToken\": \"0x82aF49447D8a07e3bd95BD0d56f35241523fBab1\",\n      \"inputAmount\": \"10000000000000000\",\n      \"outputToken\": \"0xE5ecd226b3032910CEaa43ba92EE8232f8237553\",\n      \"outputAmount\": \"9997963572235392\",\n      \"message\": \"0x\",\n      \"messageHash\": \"0x0000000000000000000000000000000000000000000000000000000000000000\",\n      \"exclusiveRelayer\": \"0x0000000000000000000000000000000000000000\",\n      \"exclusivityDeadline\": null,\n      \"fillDeadline\": \"2025-05-06T19:19:35.000Z\",\n      \"quoteTimestamp\": \"2025-05-06T16:00:59.000Z\",\n      \"depositTxHash\": \"0xfa8e7ff5ba8d31ea16fd5b21a0b59874fde02f5a6cb0c3b4f5e6487c4c146a3f\",\n      \"depositBlockNumber\": 333897296,\n      \"depositBlockTimestamp\": \"2025-05-06T16:06:58.000Z\",\n      \"status\": \"filled\",\n      \"depositRefundTxHash\": null,\n      \"swapTokenPriceUsd\": null,\n      \"swapFeeUsd\": null,\n      \"bridgeFeeUsd\": \"0.003682179272249265\",\n      \"inputPriceUsd\": \"1808.156093844096\",\n      \"outputPriceUsd\": \"1808.156093844096\",\n      \"fillGasFee\": \"292908896918512\",\n      \"fillGasFeeUsd\": \"0.000292749850110516\",\n      \"fillGasTokenPriceUsd\": \"0.9994570092965116\",\n      \"swapTransactionHash\": null,\n      \"swapToken\": null,\n      \"swapTokenAmount\": null,\n      \"relayer\": \"0x41ee28EE05341E7fdDdc8d433BA66054Cd302cA1\",\n      \"fillBlockTimestamp\": \"2025-05-06T16:06:58.000Z\",\n      \"fillTx\": \"0x11463a294431144fcbf1cfbc2faeaddfbdcf5e7248460cee10ff934bb6b8c32b\",\n      \"speedups\": []\n    }\n]": null
}

Retrieve suggested fee quote for a deposit.

get

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
400
Invalid input
500
Unexpected error within the API
get
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

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
400
Invalid input
500
Unexpected error within the API
get
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

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
400
Invalid input
500
Unexpected error within the API
get
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

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
get
GET /api/deposit/status HTTP/1.1
Host: app.across.to
Accept: */*
200

Lifecycle of a transaction

{
  "fillStatus": "filled",
  "fillTxHash": "0x123abc<...>",
  "destinationChainId": 42161
}
  • Source Code
  • Caching & Liveness
  • Testnet Across API
  • API Endpoints
  • GETRetrieve suggested fee quote for a deposit.
  • GETRetrieve current transfer limits of the system
  • GETRetrieve available routes for transfers
  • GETTrack the lifecycle of a deposit
  • GETGet all deposits for a given depositor