> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/guides/deposit-with-qr.md).

# Deposit Address Integration

A **"Deposit with QR"** screen on your own UI, built on [deposit addresses](https://docs.swapper.finance/api-v1/endpoints/deposit-addresses.md): the user picks a token and network, sends funds from any wallet or exchange, and receives your destination token.

| Step                               | Runs on                   | API                                                          |
| ---------------------------------- | ------------------------- | ------------------------------------------------------------ |
| 1. Choose what users can send      | Your server, once         | `GET /v1/tokens?depositAddress=true`                         |
| 2. Get the address and its minimum | Your server (API key)     | `POST /v1/deposit-address`, `POST /v1/deposit-address/quote` |
| 3. Show the address                | Browser                   | —                                                            |
| 4. Track the deposit               | Browser, then your server | `GET /v1/deposit-address/status`                             |
| 5. Credit the user                 | Your server               | `transaction.completed` webhook                              |

From TypeScript, [`SwapperApiClient`](https://docs.swapper.finance/api-v1/sdk.md) creates and tracks the address.

## 1. Choose what users can send

Offer a few token + network pairs from [`GET /v1/tokens?depositAddress=true`](https://docs.swapper.finance/api-v1/endpoints/deposit-addresses.md#which-tokens-can-be-deposited). Other tokens can't fund a deposit address.

## 2. Get the address and its minimum

On your server:

* [`POST /v1/deposit-address`](https://docs.swapper.finance/api-v1/endpoints/deposit-addresses.md#get-a-deposit-address) returns the address. The same parameters always return the same address, so you can fetch it each time the screen opens — but store **whose** it is: the webhook only names the address.
* [`POST /v1/deposit-address/quote`](https://docs.swapper.finance/api-v1/endpoints/deposit-addresses.md#price-a-deposit), with the same body and any plausible amount, returns `minAmountUSD` — the minimum to show. Quote the user's own amount to show what it delivers and what it costs.

{% hint style="warning" %}
**Give every user their own `toAddress`** — their wallet, or a per-user address you control. With one shared `toAddress`, every user gets the same deposit address and you can't tell whose deposit is whose.
{% endhint %}

Set `refundAddress` to a wallet you control; see [Refunds](https://docs.swapper.finance/api-v1/endpoints/deposit-addresses.md#refunds).

## 3. Show the address

* The address as a QR code (the bare address) and as text with a Copy button.
* The token, the network and the minimum next to it: the right token on the wrong network may be lost.
* No exact amount: each deposit is converted at the rate when it arrives, minus fees.
* A new option means a new address.

## 4. Track the deposit

Swapper records a deposit when its address is checked, so keep [polling the status](https://docs.swapper.finance/api-v1/endpoints/deposit-addresses.md#polling): every 10–15 seconds from the browser while the screen is open (no API key needed), then every few minutes from your server for a while after the user leaves — exchange withdrawals often arrive later.

## 5. Credit the user

Credit the deposit from the [`transaction.completed` webhook](https://docs.swapper.finance/tracking-deposits/webhooks.md), not from the screen — the user may close it first. Match `flow: "transfer_crypto"`, find the owner of `providerData.depositAddress`, and credit once per `eventId`.

A deposit that can't be delivered is [refunded](https://docs.swapper.finance/api-v1/endpoints/deposit-addresses.md#refunds). Ask users to keep the hash of their transfer for support.
