> 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/api-v1/endpoints/deposit-addresses.md).

# 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](https://docs.swapper.finance/guides/deposit-with-qr.md) 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](https://docs.swapper.finance/api-v1/authentication.md) 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`](#track-deposits) and get a [webhook](#webhooks) 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`](https://docs.swapper.finance/api-v1/endpoints/quote.md).

| 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](#which-tokens-can-be-deposited).               |
| `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`](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md#list-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](#refunds). An address of `fromChain`'s ecosystem.                                 |

The address belongs to the integrator of the API key. Requests count against the **quote** [rate limit](https://docs.swapper.finance/api-v1/rate-limits.md).

### Example

USDC on Base, delivered as USDC on Arbitrum:

```bash
curl -X POST "https://swapper.finance/api/v1/deposit-address" \
  -H "x-swapper-api-key: $SWAPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromChain": 8453,
    "fromToken": "USDC",
    "toChain": 42161,
    "toToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "toAddress": "0x1111111111111111111111111111111111111111",
    "refundAddress": "0x2222222222222222222222222222222222222222"
  }'
```

### Response

```json
{
  "address": "0x5e3a1b0c9d8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a",
  "fromChainId": "8453",
  "fromToken": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "chainId": "8453",
    "symbol": "USDC",
    "decimals": 6,
    "name": "USD Coin",
    "logoURI": "https://deposit.swapper.finance/assets/tokens/usdc.webp",
    "priceUSD": "1"
  },
  "toChainId": "42161",
  "toToken": {
    "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "chainId": "42161",
    "symbol": "USDC",
    "decimals": 6,
    "name": "USD Coin",
    "logoURI": "https://deposit.swapper.finance/assets/tokens/usdc.webp",
    "priceUSD": "0.9999"
  },
  "toAddress": "0x1111111111111111111111111111111111111111",
  "refundAddress": "0x2222222222222222222222222222222222222222",
  "integrator": "acme"
}
```

| 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](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md#the-token-object) | Token to deposit.                                                       |
| `toChainId`     | string                                                                                       | Destination chain (Swapper chain id).                                   |
| `toToken`       | [Token](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md#the-token-object) | 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.

{% hint style="warning" %}
**Only send `fromToken` on `fromChain`.** Tokens other than the one the address was issued for, or the right token on another chain, may not be recoverable. Make this clear wherever you show the address — name both the token and the network next to it.
{% endhint %}

### 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`](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md#list-tokens) and `depositAddress=true`:

```bash
curl "https://swapper.finance/api/v1/tokens?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`](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md#list-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](#refunds); amounts of a few cents aren't processed at all. Show your users the `minAmountUSD` of a [quote](#price-a-deposit).

### 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](https://discord.gg/y8eevERxBz) with the deposit address and the user's transfer hash, and Swapper returns it.

## Price a deposit

```
POST /v1/deposit-address/quote
```

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`](#get-a-deposit-address) plus `fromAmount`, makes the same checks, and creates no address. An API key is required; requests count against the **quote** [rate limit](https://docs.swapper.finance/api-v1/rate-limits.md).

| Name         | Required | Description                                                                         |
| ------------ | -------- | ----------------------------------------------------------------------------------- |
| `fromAmount` | yes      | Amount the user would send, in `fromToken`'s base units (`"100000000"` = 100 USDC). |

### Example

```bash
curl -X POST "https://swapper.finance/api/v1/deposit-address/quote" \
  -H "x-swapper-api-key: $SWAPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromChain": 8453,
    "fromToken": "USDC",
    "toChain": 42161,
    "toToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "toAddress": "0x1111111111111111111111111111111111111111",
    "fromAmount": "100000000"
  }'
```

### Response

```json
{
  "fromChainId": "8453",
  "fromToken": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "symbol": "USDC", "decimals": 6 /* … */ },
  "toChainId": "42161",
  "toToken": { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "symbol": "USDC", "decimals": 6 /* … */ },
  "toAddress": "0x1111111111111111111111111111111111111111",
  "fromAmount": "100000000",
  "fromAmountUSD": "100.00",
  "toAmount": "99850000",
  "toAmountMin": "99600000",
  "toAmountUSD": "99.85",
  "feeCosts": [
    {
      "name": "Swapper fee",
      "description": "Swapper's fee for routing the transfer",
      "token": { "symbol": "USDC" /* … */ },
      "amount": "100000",
      "amountUSD": "0.10",
      "percentage": "0.001",
      "included": true
    },
    {
      "name": "Relayer fee",
      "description": "Paid to the relayer that fills the transfer on the destination chain",
      "token": { "symbol": "USDC" /* … */ },
      "amount": "50000",
      "amountUSD": "0.05",
      "percentage": "0.0005",
      "included": true
    }
  ],
  "minAmountUSD": "2.00",
  "integrator": "acme"
}
```

| 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`     | [FeeCost](https://docs.swapper.finance/api-v1/endpoints/quote.md#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](#response) and [`/v1/quote`](https://docs.swapper.finance/api-v1/endpoints/quote.md).

* **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

```
GET /v1/deposit-address/status
```

Checks the address for new deposits and returns its **10 most recent transfers**, newest first, each in the same shape as [`GET /v1/status`](https://docs.swapper.finance/api-v1/endpoints/status.md).

| 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`](https://docs.swapper.finance/api-v1/endpoints/status.md#your-own-transfers). Status checks count against the **quote** [rate limit](https://docs.swapper.finance/api-v1/rate-limits.md).

### Example

```bash
curl -G "https://swapper.finance/api/v1/deposit-address/status" \
  -H "x-swapper-api-key: $SWAPPER_API_KEY" \
  --data-urlencode "address=0x5e3a1b0c9d8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a"
```

### Response

```json
{
  "address": "0x5e3a1b0c9d8f7e6a5b4c3d2e1f0a9b8c7d6e5f4a",
  "transfers": [
    {
      "transactionId": "0x0b5c1f7e2d4a9c3e8f6a1b2d4c7e9f0a3b5d7c9e1f2a4b6c8d0e2f4a6b8c0d2e",
      "sending": {
        "txHash": "0xefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
        "txLink": "https://basescan.org/tx/0xefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefefef",
        "amount": "25000000",
        "amountUSD": "25.00",
        "token": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": "8453", "symbol": "USDC", "decimals": 6 /* … */ },
        "chainId": "8453",
        "timestamp": 1791054717
      },
      "receiving": {
        "txHash": "0x9999999999999999999999999999999999999999999999999999999999999999",
        "txLink": "https://arbiscan.io/tx/0x9999999999999999999999999999999999999999999999999999999999999999",
        "amount": "24910000",
        "amountUSD": "24.91",
        "token": { "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", "chainId": "42161", "symbol": "USDC", "decimals": 6 /* … */ },
        "chainId": "42161",
        "timestamp": 1791054741
      },
      "status": "DONE",
      "substatus": "COMPLETED",
      "substatusMessage": "The transfer is complete.",
      "tool": "swapper",
      "fromAddress": "0x3333333333333333333333333333333333333333",
      "toAddress": "0x1111111111111111111111111111111111111111"
    }
  ]
}
```

| Field       | Type                                                                          | Description                                                                               |
| ----------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `address`   | string                                                                        | The deposit address.                                                                      |
| `transfers` | [Status](https://docs.swapper.finance/api-v1/endpoints/status.md#response)\[] | Up to 10 transfers into the address, newest first. Empty until the first deposit arrives. |

Each transfer follows [`/v1/status`](https://docs.swapper.finance/api-v1/endpoints/status.md#statuses): `PENDING` while it's on its way, then `DONE` (`COMPLETED`, or `REFUNDED` — see [Refunds](#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](#webhooks) 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`](https://docs.swapper.finance/api-v1/endpoints/status.md), 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](https://docs.swapper.finance/tracking-deposits/webhooks.md) to the endpoints configured in your [dashboard](https://docs.swapper.finance/integrator-dashboard/overview.md#webhooks), with `flow: "transfer_crypto"` — the same flow as the widget's [QR deposits](https://docs.swapper.finance/deposit-methods/transfer-crypto.md). `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.

{% hint style="warning" %}
The webhook fires once Swapper has recorded the deposit, which happens when the address is checked — keep [polling](#polling) while you expect a deposit; don't rely on the webhook alone.
{% endhint %}

## 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](#which-tokens-can-be-deposited).                       |
| `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`      | See [Rate Limits](https://docs.swapper.finance/api-v1/rate-limits.md).                                                                  |
| `500`  | `INTERNAL_ERROR`    | Unexpected error. Safe to retry.                                                                                                        |
| `502`  | `UPSTREAM_ERROR`    | Temporarily unavailable. Retry shortly.                                                                                                 |

See [Errors](https://docs.swapper.finance/api-v1/errors.md) for the envelope and all codes.

## Not available yet

* An [integrator fee](https://docs.swapper.finance/api-v1/integrator-fees.md) on deposit addresses.
* [Custom contract calls](https://docs.swapper.finance/widget-integration/custom-contract-calls.md) on delivery.
* Bitcoin and Tron as deposit chains — they're available in the widget's [QR flow](https://docs.swapper.finance/deposit-methods/transfer-crypto.md), not yet on v1.

Talk to us in [Discord](https://discord.gg/y8eevERxBz) if you need one of these.
