For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

Deposit Addresses

POST /v1/deposit-address
POST /v1/deposit-address/quote
GET  /v1/deposit-address/status

A deposit address is an address you show your user — as text or a QR code — that they fund with a plain transfer from any wallet or exchange. There's no wallet to connect and nothing to sign: Swapper detects each deposit, swaps and bridges it, and delivers your destination token to the recipient you chose.

Use it where the user can't or won't sign a transaction for you: exchange withdrawals, "deposit" screens in custodial apps, top-ups from a hardware wallet, or any flow that only has an address field to offer.

For a complete example — server, QR screen, polling and webhook — see the Deposit with QR guide.

How it works

  1. Your server asks for an address for a route: what the user sends (fromChain, fromToken) and what is delivered where (toChain, toToken, toAddress). An API key is required.

  2. You show the address. The user sends fromToken on fromChain to it — any amount, any number of times, now or next month.

  3. Swapper picks up each deposit, converts it at the rate when it arrives (minus fees), and delivers toToken to toAddress on toChain.

  4. You track it with GET /v1/deposit-address/status and get a webhook when a deposit completes.

Get a deposit address

POST /v1/deposit-address

Takes a JSON body, with the same field names as POST /v1/quote.

Name
Required
Description

fromChain

yes

Chain the user deposits on — id ("8453"; EVM ids can also be numbers, 8453) or key (base).

fromToken

yes

Token the user deposits — address or symbol. Must be a token the chain accepts for deposit addresses.

toChain

yes

Destination chain id or key. Can be the same as fromChain.

toToken

yes

Token delivered — address or symbol, as listed by GET /v1/tokens.

toAddress

yes

Recipient of every deposit. Must be an address of toChain's ecosystem.

refundAddress

no

Where a deposit that can't be delivered is refunded — see Refunds. An address of fromChain's ecosystem.

The address belongs to the integrator of the API key. Requests count against the quote rate limit.

Example

USDC on Base, delivered as USDC on Arbitrum:

Response

Field
Type
Description

address

string

Show this to the user. They send fromToken on fromChainId here.

fromChainId

string

Chain to deposit on (Swapper chain id).

fromToken

Token to deposit.

toChainId

string

Destination chain (Swapper chain id).

toToken

Token delivered.

toAddress

string

Recipient of every deposit.

refundAddress

string?

Only when you sent one.

integrator

string

Your integrator id.

The address

  • Reusable and permanent. It doesn't expire and accepts any number of deposits. Give each user their own address for as long as you like.

  • Idempotent. Asking again with the same parameters returns the same address, so you can fetch it instead of storing it. Should it ever change, the earlier address keeps working.

  • No fixed rate. Each deposit is converted at the rate when it arrives, and Swapper's fee and the network and bridge costs are deducted from it.

  • One address per destination. A different toChain, toToken, toAddress or refundAddress gives a different address.

Which tokens can be deposited

Each chain accepts a set of tokens for deposit addresses (typically its stablecoins and native token). List them with GET /v1/tokens and depositAddress=true:

The response has the usual shape, but holds only the accepted tokens, on the chains that accept any — including Starknet (fromChain: starknet, USDC), which GET /v1/chains doesn't list. Ask for any other token and you get UNSUPPORTED_TOKEN.

Native tokens use the same addresses as everywhere in v1: the zero address on EVM chains, So11111111111111111111111111111111111111111 on Solana.

Minimums

There's no hard minimum, but every deposit pays network and bridge costs. A deposit too small to cover them can't be delivered and is refunded; amounts of a few cents aren't processed at all. Show your users the minAmountUSD of a quote.

Refunds

A deposit that can't be delivered is refunded on the source chain:

  • With refundAddress — to that address. Use a plain wallet address (an EOA) you control. Don't use an exchange deposit address (a refund from an unknown sender may never be credited there) or a smart contract.

  • Without it — to Swapper. Open a ticket in Discord with the deposit address and the user's transfer hash, and Swapper returns it.

Price a deposit

What a deposit of a given amount delivers, what it costs, and the smallest deposit worth sending — before the user sends anything. Takes the body of POST /v1/deposit-address plus fromAmount, makes the same checks, and creates no address. An API key is required; requests count against the quote rate limit.

Name
Required
Description

fromAmount

yes

Amount the user would send, in fromToken's base units ("100000000" = 100 USDC).

Example

Response

Field
Type
Description

toAmount

string

Estimated delivery to toAddress, after every fee, in toToken's base units.

toAmountMin

string

Delivery at the worst price the route accepts.

feeCosts

Swapper's fee and the relayer fee (network and bridge costs). All are deducted from the deposit.

minAmountUSD

string

Smallest deposit worth sending on this route, in USD.

The other fields are as in the deposit address and /v1/quote.

  • An estimate, not a fixed rate. The deposit is converted at the rate when it arrives.

  • The minimum barely depends on the amount. It's the relayer fee, rounded up and doubled, and at least 10 USD on Ethereum and Bitcoin. To show it before the user picks an amount, quote any plausible one — e.g. 100 USDC.

  • Not available from Starknet yet: you get UNSUPPORTED_CHAIN.

Track deposits

Checks the address for new deposits and returns its 10 most recent transfers, newest first, each in the same shape as GET /v1/status.

Name
Required
Description

address

yes

The deposit address. EVM addresses in any letter case.

No API key is needed. With the key of the integrator the address belongs to, each transfer also carries integrator and feeCosts, as on /v1/status. Status checks count against the quote rate limit.

Example

Response

Field
Type
Description

address

string

The deposit address.

transfers

Up to 10 transfers into the address, newest first. Empty until the first deposit arrives.

Each transfer follows /v1/status: PENDING while it's on its way, then DONE (COMPLETED, or REFUNDED — see Refunds) or FAILED. Use transactionId to tell transfers apart. In a transfer:

  • sending is the source side. Its txHash is the source-chain transaction that moved the deposit out of the address — not necessarily the user's own transfer into it.

  • fromAddress, when present, is who sent the deposit. For an exchange withdrawal that's the exchange's hot wallet, not the user.

  • receiving is the delivery to toAddress.

Polling

A deposit is recorded — and your webhook sent — once Swapper has seen it, and checking this endpoint is what makes it look. Poll it while you expect a deposit:

  • every 10–15 seconds while the user is on your deposit screen;

  • less often (every few minutes) for a while after they leave it, until the deposit has completed;

  • stop when you don't expect anything more.

A transfer can also be followed on its own with GET /v1/status, by any of its hashes — including the user's own transfer into the address, when they give it to you.

Webhooks

When a deposit completes, Swapper sends a transaction.completed webhook to the endpoints configured in your dashboard, with flow: "transfer_crypto" — the same flow as the widget's QR deposits. providerData carries the depositAddress.

Identify deposit-address transfers by flow, not by method: the settlement method can change as Swapper adds settlement paths for an address's chain.

Errors

Status
Code
When

400

VALIDATION_ERROR

A parameter is missing or malformed, or toAddress / refundAddress isn't a valid address for its chain's ecosystem.

400

UNSUPPORTED_CHAIN

fromChain or toChain isn't served by v1, or deposit addresses can't deliver to toChain yet.

400

UNSUPPORTED_TOKEN

A token isn't listed on its chain, or fromToken can't fund a deposit address.

401

UNAUTHORIZED

POST /v1/deposit-address or /quote without an API key.

401

INVALID_API_KEY

An unknown or revoked API key was sent.

404

NOT_FOUND

/status: not a Swapper deposit address.

404

NO_ROUTE_FOUND

No deposit address can serve this route right now, or /quote: the amount is too small to fill. Another token pair or amount may work.

429

RATE_LIMITED

500

INTERNAL_ERROR

Unexpected error. Safe to retry.

502

UPSTREAM_ERROR

Temporarily unavailable. Retry shortly.

See Errors for the envelope and all codes.

Not available yet

Talk to us in Discord if you need one of these.

Last updated