Migration guide
Moving from the legacy APIs to the Across API. What you called before, and what you call now.
The legacy APIs, including the Swap API, suggested fees and deposit status, are deprecated. This page maps each legacy call to its replacement in the Across API.
The basics
| Legacy APIs | Now | |
|---|---|---|
| Host | https://across.to/api | https://api.across.to. Every path starts with /v1 |
| Credentials | API key plus integratorId | API key only, created in the integrator portal |
| Testnet | Available | None. Test on mainnet with small amounts |
Endpoints
| What you were doing | Legacy APIs | Now |
|---|---|---|
| Find chains, tokens and routes | GET /swap/chains, GET /swap/tokens, GET /available-routes | GET /v1/capabilities |
| Check transfer limits | GET /limits | GET /v1/capabilities for one route, in capabilities.limits |
| Get a quote and its fees | GET /swap/approval, GET /suggested-fees | POST /v1/quotes |
| Send the transfer | Send approvalTxns and swapTx from the user's wallet | Follow the quote's nextActions. If they end with submit_execution, call POST /v1/quotes/{orderId}/executions |
| Gasless transfers | GET /swap/gasless, then POST /gasless/submit | The same quote and execution calls. When the token supports it, the quote asks for a signature instead of a transaction |
| Track a transfer | GET /deposit/status, GET /deposit | GET /v1/transfers/{orderId} |
| List transfers | GET /deposits | GET /v1/transfers |
| Get notified of updates | POST /v1/webhooks/subscriptions | Webhooks, set up in the integrator portal |
| Run calls on the destination chain | POST /swap/approval with an actions body | Coming soon |
To get limits, set all four of originChainId, originToken,
destinationChainId and destinationToken. The legacy inputToken and
outputToken are now originToken and destinationToken. Without all
four, the response has no capabilities block and no limits.
Destination chain actions are coming soon. If you use embedded actions
with POST /swap/approval today, keep that flow until they are available
in the Across API.
Request fields
| Legacy APIs | Now |
|---|---|
inputToken and originChainId | origin.token: { chainId, address } |
outputToken and destinationChainId | destination.token: { chainId, address } |
amount | origin.amount, or destination.amount for exact_output and min_output |
depositor, recipient | origin.depositor, destination.recipient |
tradeType: exactInput, minOutput, exactOutput | amountType: exact_input, min_output, exact_output |
appFee (a decimal, 0.01 = 1%) and appFeeRecipient | appFeeBps (basis points, 100 = 1%). No recipient: Across pays out your share monthly. See App fees |
slippage (0.005 = 0.5%, or auto) | maxFee: { bps, fixedUsd }, the most USD value the user can lose to fees, the app fee and slippage combined. It is not a slippage value, so don't copy yours across. Omit it, as you would auto, to use the default. See Fees |
integratorId | Not needed. Your API key identifies you |
The request body is strict: an unknown field returns 400 instead of being
ignored.
Response fields
| Legacy APIs | Now |
|---|---|
expectedOutputAmount, minOutputAmount | destination.amount, destination.minAmount |
fees | fee: totalFee, transferFee, appFee. See Fees |
approvalTxns, swapTx | nextActions: an ordered list of what to approve, sign or send |
| Deposit transaction hash, to track the transfer | orderId, returned by the quote. Track the transfer with it |
status: pending, filled, expired, refunded, … | status.state: pending, completed, refunded or failed, with status.reason for detail. Wait for status.finalized before acting on the outcome |
Migrate in four steps
- Get an API key from the integrator portal.
- Replace route, token and limit lookups with
GET /v1/capabilities. - Replace
/swap/approvalwithPOST /v1/quotesand work throughnextActions. If they end withsubmit_execution, submit the result to the executions endpoint. - Track transfers by
orderIdwithGET /v1/transfers/{orderId}, or with webhooks.
The Quickstart shows steps 2 to 4 as working code.