Integrating cross-chain swaps without custody: a deposit-address API walkthrough

#api #web3 #cryptocurrency #tutorial

Most swap integrations force a custody decision on you before you write a line of code. Aggregator routers need your users to connect a wallet and sign contract calls. Custodial APIs need you to hold balances. There is a third shape, and it is the one exchanges have quietly used for years: the deposit-address flow. Your app shows the user a one-time deposit address, watches for the incoming transfer, and the service delivers the swapped asset to an address your user controls. No wallet connection, no contract approvals, no pooled funds in your name.

This walkthrough shows how that flow works against a live service — AllSwap, a non-custodial cross-chain swap service — using its public API. Everything below is based on the production endpoints; the full reference is in the API docs.

Step 0: Read the asset universe (no auth needed)

Before quoting anything, you need to know which assets exist on which chains — and under which contract address. The asset list is served publicly:

curl https://allswap.io/api/v1/assets

Each entry is a CAIP-style record:

{
  "assetId": "eip155:1/erc20:0xdac17f958d2ee523a2206206994597c13d831ec7",
  "symbol": "USDT",
  "blockchain": "eth",
  "decimals": 6,
  "contractAddress": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "isNative": false
}

At the time of writing the list covers 317 assets across 46 chains — Ethereum (61), NEAR (47), Base (40), BNB Chain (38) and Solana (21) are the deepest. Pin your integration to assetId, not to the symbol: USDT exists on a dozen chains, and the single most common cross-chain support ticket in this industry is a user sending the right token on the wrong chain. The assetId makes that class of bug unrepresentable in your code.

If you want the same data as a file for analysis, the full snapshot is also published as a public dataset on Kaggle.

Step 1: Get a quote with the number that matters

The trading endpoints live on https://api.allswap.io and use signed requests (an X-Timestamp header is part of the scheme; see the docs for the exact signing recipe). The flow starts with POST /v1/quote for a pair and amount.

The field to design your UI around is minimum received. A quote that shows an expected amount but not a guaranteed floor is hiding slippage from your user. In a deposit-address flow the rate is locked by competing market makers per route, and the quote states the minimum the recipient will get, all-in, before any funds move. Render that number prominently; it is the only number your user can hold the service to.

Step 2: Create the order, show one address

POST /v1/order turns a quote into an order and returns the single-use deposit address for the source chain. Two integration details matter here:

The address is single-use. Never cache or reuse it across orders. Treat it like a payment intent: one order, one address, one expected amount and asset.
Your UI's job is clarity, not custody. Show the address, the exact asset and chain, and the amount. The user sends from whatever wallet or exchange they already use — that is the point of the design: your app never touches keys.

Step 3: Track the order to completion

Poll POST /v1/order/{id}/deposit / GET /v1/order/{id} for state transitions: awaiting deposit → confirming → exchanging → sending → done. Failed swaps (wrong asset, underpayment below the route minimum) are refunded automatically to the sender, which is the correct failure mode for a non-custodial design — but your UI should still surface the state honestly instead of spinning forever. A five-state tracker with a support path beats a progress bar that lies.

When this shape is the wrong tool

Deposit-address swaps are asynchronous by nature: a swap settles in minutes, not in the same block. If your product needs atomic composability inside a single transaction — flash-loan strategies, in-protocol rebalancing — you want a router contract, not this. And if your users are already inside a wallet and swapping on one chain, a DEX aggregator is fewer moving parts.

But for moving value between chains from an app that should never hold keys or funds — payout tools, portfolio dashboards, checkout and off-ramp flows — the deposit-address model is the integration with the smallest trust surface: one public asset list, one quote with a stated floor, one address per order, one status endpoint.

The docs, endpoint reference and signing details are at allswap.io/docs.

DEV Community