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.

API Endpoints

Get swap approval data

get

Returns data required to execute a crosschain swap. If the input token requires approval, approvalTxns will be included in the response.

Query parameters

tradeTypestring · enumRequired

Type of trade. Use minOutput, exactInput or exactOutput.

Default: exactInputPossible values:

amountstringRequired

Required amount of output token in smallest unit.

Example: 1000000

inputTokenstringRequired

Address of the input token on the origin chain.

Example: 0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85

outputTokenstringRequired

Address of the output token on the destination chain.

Example: 0x82aF49447D8a07e3bd95BD0d56f35241523fBab1

originChainIdintegerRequired

Chain ID of the origin chain.

Example: 10

destinationChainIdintegerRequired

Chain ID of the destination chain.

Example: 42161

depositorstringRequired

Address of the depositor initiating the swap.

Example: 0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB

recipientstringRequired

Address of the account receiving the output token.

Example: 0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB

integratorIdstringOptional

2-byte hex-string that identifies the integrator. E.g., "0xdead".

Example: 0xdead

refundAddressstringOptional

Address to receive refunds. Defaults to depositor if not provided.

Default: 0xDEPOSITOR_ADDRESS

refundOnOriginbooleanOptional

Specifies whether refund should be sent on the origin chain. Defaults to true.

Default: true

slippageTolerancenumber · floatOptional

Slippage tolerance percentage (e.g., 1 for 1%, 0.5 for 0.5%).

Default: 1

Responses

200

Swap approval data returned successfully.

application/json

inputAmountstringOptional

Required input amount in the smallest unit of the input token.

Example: 1065159719994

expectedOutputAmountstringOptional

Expected amount of output token.

Example: 940201830

minOutputAmountstringOptional

Minimum guaranteed amount of output token.

Example: 940201830

expectedFillTimeintegerOptional

Expected time in seconds to complete the swap.

Example: 8

400

Bad request due to invalid input parameter.

application/json

get

/swap/approval

HTTPcURLJavaScriptPython

GET /api/swap/approval?tradeType=exactInput&amount=1000000&inputToken=0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85&outputToken=0x82aF49447D8a07e3bd95BD0d56f35241523fBab1&originChainId=10&destinationChainId=42161&depositor=0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB&recipient=0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB HTTP/1.1
Host: app.across.to
Accept: */*

{
  "checks": {
    "allowance": {
      "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "spender": "0x5c7BCd6E7De5423a257D81B442095A1a6ced35C5",
      "actual": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
      "expected": "1065159719994"
    },
    "balance": {
      "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "actual": "0",
      "expected": "1065159719994"
    }
  },
  "steps": {
    "bridge": {
      "inputAmount": "1065159719994",
      "outputAmount": "940201830",
      "tokenIn": {
        "decimals": 18,
        "symbol": "ETH",
        "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "name": "Ether",
        "chainId": 1
      },
      "tokenOut": {
        "decimals": 18,
        "symbol": "ETH",
        "address": "0xE5ecd226b3032910CEaa43ba92EE8232f8237553",
        "name": "Ether",
        "chainId": 232
      },
      "fees": {
        "totalRelay": {
          "pct": "999117313760226216",
          "total": "1064219518164"
        },
        "relayerCapital": {
          "pct": "99999954936899",
          "total": "106515923"
        },
        "relayerGas": {
          "pct": "999017313805289317",
          "total": "1064113002241"
        },
        "lp": {
          "pct": "0",
          "total": "0"
        }
      }
    }
  },
  "refundToken": {
    "decimals": 18,
    "symbol": "WETH",
    "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "name": "Ether",
    "chainId": 1
  },
  "inputAmount": "1065159719994",
  "expectedOutputAmount": "940201830",
  "minOutputAmount": "940201830",
  "expectedFillTime": 8,
  "swapTx": {
    "simulationSuccess": false,
    "chainId": 1,
    "to": "0x5c7BCd6E7De5423a257D81B442095A1a6ced35C5",
    "data": "0x7b939232000000000000000000000000a4d353bbc130cbef1811f27ac70989f9d568ceab...",
    "maxFeePerGas": "1213349849",
    "maxPriorityFeePerGas": "500000000"
  }
}

The crosschain swap API is currently in beta. We are still adding changes and improving the developer experience here. In this period, we request you to provide valuable feedback on how we can improve the overall experience and ensure that we can make the API as seamless as possible.

We appreciate your participation and kindly request you to report any unexpected behaviors or API response anomalies.

Please note that getting routes using /available-routes API is not available on the crosschain swap endpoint. In addition to this, you donot need /suggested-fees API to build the intent.

Learn how to integrate the /swap/approval Endpoint

Let us now focus on conducting a crosschain swap with the following parameters:

1. tradeType : Defines the type of trade for eg - minOutput.

2. amount : Specifies amount of inputToken in the smallest unit (wei for ETH or 6 decimals for USDC).

3. inputToken : Address of the token being swapped.

4. originChainId : Chain ID of the source/origin chain (232 for Lens Chain mainnet).

5. outputToken : Address of the token to be received after the swap.

6. destinationChainId : Chain ID of the destination chain where the output token will be delivered.

7. depositor : The address of the sender (usually the wallet initiating the swap).

In this specific example, we will be swapping 1 USDC on Optimism with a related amount of ETH on Arbitrum.

Run the following script to conduct the crosschain swap:

Viem

import { createWalletClient, http, parseUnits } from 'viem'
import { privateKeyToAccount } from 'viem/accounts';
import { optimism, arbitrum } from 'viem/chains'
import axios from 'axios'
import dotenv from 'dotenv'

dotenv.config()

async function acrossSwapApproval() {
  const PRIVATE_KEY = process.env.PRIVATE_KEY


  const account = privateKeyToAccount(PRIVATE_KEY)
  const client = createWalletClient({
    account,
    chain: optimism,
    transport: http()
  })

  const { data } = await axios.get('https://app.across.to/api/swap/approval', {
    params: {
      tradeType: 'minOutput',
      amount: parseUnits('1',6).toString(),
      inputToken: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85', // USDC on Optimism
      originChainId: 10,
      outputToken: '0x82aF49447D8a07e3bd95BD0d56f35241523fBab1', // ETH on Arbitrum
      destinationChainId: 42161,
      depositor: account.address,
    }
  })

  // Handle token approvals if required
  if (data.approvalTxns) {
    for (const approvalTxn of data.approvalTxns) {
      const tx = await client.sendTransaction({
        to: approvalTxn.to,
        data: approvalTxn.data,
      })
      console.log('Approval tx hash:', tx)
    }
  }

  // Execute swap transaction
  const tx = await client.sendTransaction({
    to: data.swapTx.to,
    data: data.swapTx.data,
    value: data.swapTx.value ? BigInt(data.swapTx.value) : undefined,
  })

  console.log('Crosschain swap tx hash:', tx)
}

acrossSwapApproval()

Ethers

Upon successful execution of the /swap/approval endpoint, the return data should be something like this:

{
  "checks": {
    "allowance": {
      "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "spender": "0x5c7BCd6E7De5423a257D81B442095A1a6ced35C5",
      "actual": "115792089237316195423570985008687907853269984665640564039457584007913129639935",
      "expected": "1065159719994"
    },
    "balance": {
      "token": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
      "actual": "0",
      "expected": "1065159719994"
    }
  },
  "steps": {
    "bridge": {
      "inputAmount": "1065159719994",
      "outputAmount": "940201830",
      "tokenIn": {
        "decimals": 18,
        "symbol": "ETH",
        "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
        "name": "Ether",
        "chainId": 1
      },
      "tokenOut": {
        "decimals": 18,
        "symbol": "ETH",
        "address": "0xE5ecd226b3032910CEaa43ba92EE8232f8237553",
        "name": "Ether",
        "chainId": 232
      },
      "fees": {
        "totalRelay": {
          "pct": "999117313760226216",
          "total": "1064219518164"
        },
        "relayerCapital": {
          "pct": "99999954936899",
          "total": "106515923"
        },
        "relayerGas": {
          "pct": "999017313805289317",
          "total": "1064113002241"
        },
        "lp": {
          "pct": "0",
          "total": "0"
        }
      }
    }
  },
  "refundToken": {
    "decimals": 18,
    "symbol": "WETH",
    "address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
    "name": "Ether",
    "chainId": 1
  },
  "inputAmount": "1065159719994",
  "expectedOutputAmount": "940201830",
  "minOutputAmount": "940201830",
  "expectedFillTime": 8,
  "swapTx": {
    "simulationSuccess": false,
    "chainId": 1,
    "to": "0x5c7BCd6E7De5423a257D81B442095A1a6ced35C5",
    "data": "0x7b939232000000000000000000000000a4d353bbc130cbef1811f27ac70989f9d568ceab000000000000000000000000c5939f59b3c9662377dda53a08d5085b2d52b719000000000000000000000000c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2000000000000000000000000e5ecd226b3032910ceaa43ba92ee8232f8237553000000000000000000000000000000000000000000000000000000f800777c3a00000000000000000000000000000000000000000000000000000000380a576600000000000000000000000000000000000000000000000000000000000000e800000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000067f4f4530000000000000000000000000000000000000000000000000000000067f5494300000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000180000000000000000000000000000000000000000000000000000000000000018000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000020000000000000000000000000c5939f59b3c9662377dda53a08d5085b2d52b719000000000000000000000000000000000000000000000000000000000000006000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000044ef8738d3000000000000000000000000e5ecd226b3032910ceaa43ba92ee8232f8237553000000000000000000000000a4d353bbc130cbef1811f27ac70989f9d568ceab00000000000000000000000000000000000000000000000000000000",
    "maxFeePerGas": "1213349849",
    "maxPriorityFeePerGas": "500000000"
  }
}

With the above response from the /swap/approval endpoint, you can proceed to sign transaction on the wallet client.

Planned Advancements

We're continuously enhancing the /swap endpoint to provide a more robust and flexible swapping experience. Here's a glimpse into upcoming improvements:

• Advanced DEX Aggregation: Expect smarter routing across multiple DEXes, including 0x and LiFi, for optimal execution.

• Customizable Application Fees: Integrate the ability to specify and manage application-specific fees directly within the swap.

• Permit2 Integration: Streamlined token approvals through Permit2 for a smoother user experience.

• Destination Chain Embedded Actions: Enable post-swap actions directly on the destination chain for more complex workflows.

• Comprehensive Native Token Support: Seamlessly swap to and from native chain tokens (e.g., ETH).

• Detailed API Documentation: Comprehensive API docs for all /swap related endpoints, including clear error responses and usage guides.

---

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

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.

Get all deposits for a given depositor

get

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

/deposits

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

idintegerOptional

Internal unique identifier for the deposit record.

relayHashstringOptional

Hash of the relay data used to verify and track fill events.

depositIdstringOptional

Unique identifier assigned to the deposit event on the origin chain.

originChainIdintegerOptional

The chain ID where the deposit was originally made.

destinationChainIdintegerOptional

The target chain ID where the fill is expected to complete.

depositorstringOptional

Wallet address of the user who initiated the deposit.

recipientstringOptional

Wallet address intended to receive funds on the destination chain.

inputTokenstringOptional

Address of the token deposited on the origin chain.

inputAmountstringOptional

Amount of inputToken sent in the deposit (in wei).

outputTokenstringOptional

Address of the token expected to be received on the destination chain.

outputAmountstringOptional

Amount of outputToken expected to be received (in wei).

messagestringOptional

Optional arbitrary bytes message encoded with the deposit intent.

messageHashstringOptional

Hash of the message payload.

exclusiveRelayerstringOptional

Address of the relayer granted exclusivity to fill the deposit, if any.

exclusivityDeadlinestring · date-time · nullableOptional

Timestamp indicating when relayer exclusivity expires.

fillDeadlinestring · date-timeOptional

Deadline by which the deposit must be filled before expiring.

quoteTimestampstring · date-timeOptional

Time at which the quote for the deposit was generated.

depositTxHashstringOptional

Transaction hash of the deposit on the origin chain.

depositBlockNumberintegerOptional

Block number where the deposit transaction was confirmed.

depositBlockTimestampstring · date-timeOptional

Timestamp of the block containing the deposit transaction.

statusstring · enumOptional

The status of the deposit fill lifecycle.

Possible values:

depositRefundTxHashstring · nullableOptional

Transaction hash for refund if deposit expired and funds were returned to the depositor.

swapTokenPriceUsdstring · nullableOptional

USD price of the token used in any optional swap.

swapFeeUsdstring · nullableOptional

Fee paid in USD for the optional swap (if performed).

bridgeFeeUsdstringOptional

Fee paid in USD for bridging the funds across chains.

inputPriceUsdstringOptional

USD price of the input token at the time of deposit.

outputPriceUsdstringOptional

USD price of the output token at the time of quote.

fillGasFeestringOptional

Gas cost incurred in native token units during fill.

fillGasFeeUsdstringOptional

USD value of the gas fee for filling the deposit.

fillGasTokenPriceUsdstringOptional

USD price of the gas token on the destination chain at the time of fill.

swapTransactionHashstring · nullableOptional

Transaction hash for any token swap conducted on the destination chain.

swapTokenstring · nullableOptional

Token address used in a swap on the destination chain, if any.

swapTokenAmountstring · nullableOptional

Amount of the swapToken exchanged, if a swap occurred.

relayerstringOptional

Address of the relayer that submitted the fill on the destination chain.

fillBlockTimestampstring · date-timeOptional

Timestamp when the fill was confirmed on the destination chain.

fillTxstringOptional

Transaction hash of the actual fill transaction.

speedupsstring[]Optional

List of transaction hashes representing optional speedup fills.

get

/deposits

HTTPcURLJavaScriptPython

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
}