Deposit Addresses
POST /v1/deposit-address
POST /v1/deposit-address/quote
GET /v1/deposit-address/statusA 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
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.You show the address. The user sends
fromTokenonfromChainto it — any amount, any number of times, now or next month.Swapper picks up each deposit, converts it at the rate when it arrives (minus fees), and delivers
toTokentotoAddressontoChain.You track it with
GET /v1/deposit-address/statusand get a webhook when a deposit completes.
Get a deposit address
POST /v1/deposit-addressTakes a JSON body, with the same field names as POST /v1/quote.
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.
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
address
string
Show this to the user. They send fromToken on fromChainId here.
fromChainId
string
Chain to deposit on (Swapper chain id).
toChainId
string
Destination chain (Swapper chain id).
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,toAddressorrefundAddressgives 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.
fromAmount
yes
Amount the user would send, in fromToken's base units ("100000000" = 100 USDC).
Example
Response
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
FeeCost[]
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.
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
address
string
The deposit address.
transfers
Status[]
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:
sendingis the source side. ItstxHashis 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.receivingis the delivery totoAddress.
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
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.
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.
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
An integrator fee on deposit addresses.
Custom contract calls on delivery.
Bitcoin and Tron as deposit chains — they're available in the widget's QR flow, not yet on v1.
Talk to us in Discord if you need one of these.
Last updated