> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://doc.cheddar.biz/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://doc.cheddar.biz/_mcp/server.

# Deposit swaps

Ordinary [deposits](/guides/deposits) require your customer to send an asset
Cheddar custodies. **Deposit swaps remove that limit**: your customer can send
almost any token on almost any chain, and Cheddar credits their balance in USDC.

You request a swap, Cheddar returns a deposit address. Your customer sends the
origin token there. It is swapped and credited, and your existing
`CUSTOMER_DEPOSIT` [webhook](/webhooks/events) fires exactly as it does for a
normal deposit.

> **Note**
>
> Deposit swaps must be enabled for your organization. Until then every call
> returns `403`. Contact the Cheddar team to switch it on.

> **Warning**
>
> Three swap-ish features exist — do not conflate them. **Deposit swaps** (this
> page) fund a **customer** balance from outside. [Swap](/guides/swap) converts
> an asset **you** hold and pays out to a whitelisted address.
> [Customer swaps](/guides/customer-swaps) convert one **customer** balance into
> another — no outside token involved.

## How it works

|   | Step                             | Call                                              |
| - | -------------------------------- | ------------------------------------------------- |
| 1 | List what your customer can send | `GET /swap/tokens`                                |
| 2 | Create the swap                  | `POST /swap` → `depositAddress` + `deadline`      |
| 3 | Your customer sends the token    | *(your UI)*                                       |
| 4 | Cheddar credits the balance      | your deposit webhook, plus `GET /swap/{intentId}` |

## List accepted assets

```bash
curl https://api.cheddar.biz/v1/swap/tokens \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "tokens": [
    { "assetId": "nep141:eth.omft.near", "blockchain": "eth", "symbol": "ETH", "decimals": 18, "contractAddress": null }
  ]
}
```

Always pass `assetId` back verbatim. Never build one yourself — the format
belongs to the upstream provider and can change.

## Create a swap

```bash
curl -X POST https://api.cheddar.biz/v1/swap \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "originAssetId": "nep141:eth.omft.near",
    "amount": "5000000000000000",
    "customerId": "your-customer-id",
    "refundTo": "0x7725124cae885D822320Fc5fd8CD83635650D5fe",
    "idempotencyKey": "unique-per-swap"
  }'
```

`amount` is **atomic units** — 0.005 ETH is `0.005 × 10^18`. Decimals like
`"0.005"` are rejected.

```json
{
  "intentId": "b9b3c845-045f-4974-a410-df79bc30528a",
  "depositAddress": "0x62d4bb081Cff68aba63da5Be434C2794BFBE2418",
  "depositMemo": null,
  "amountIn": "5000000000000000",
  "minAmountIn": "4950000000000000",
  "minAmountOut": "9464909",
  "deadline": "2026-08-10T20:00:00.000Z",
  "status": "PENDING_DEPOSIT",
  "existing": false
}
```

### What to show your customer

**The deposit address** — where they send. Single use; do not reuse it across
swaps.

**`minAmountIn`, not `amountIn`** — this is the real floor. Anything at or above
it swaps; below it is refunded. Your slippage tolerance is applied to the input
side precisely so a customer sending from their own wallet does not fail for
being a fraction short.

**The deadline** — the deposit must arrive before this. Measured in days, not
minutes, but read it from the response rather than assuming.

> **Warning**
>
> **`depositMemo`, if it is not null, is REQUIRED.** Some chains need a memo
> alongside the address, and omitting it loses the funds permanently. Display it
> as prominently as the address itself.

### Refund address

`refundTo` must be valid on the **origin** chain. Cheddar validates the format
before anything is spent, so a malformed address fails immediately.

> **Warning**
>
> Cheddar cannot verify your customer actually **controls** that address — format
> validity is not ownership. Prefer an address from a connected wallet over free
> text. A valid address they do not own is an unrecoverable loss.

### Idempotency

Use one `idempotencyKey` per swap you actually intend, not per HTTP attempt.
Retrying with the same key returns the same swap with `existing: true` and
spends no new quote.

Requesting a second swap for the same customer and origin asset also returns
the existing one rather than issuing a new quote. If it is close to expiry it
is replaced automatically, so you never receive an address about to stop
working.

## Track the outcome

```bash
curl https://api.cheddar.biz/v1/swap/b9b3c845-045f-4974-a410-df79bc30528a \
  -H "x-api-key: YOUR_API_KEY"
```

| Status               | Terminal | Meaning                                   |
| -------------------- | -------- | ----------------------------------------- |
| `PENDING_DEPOSIT`    | No       | Waiting for your customer to send         |
| `PROCESSING`         | No       | Deposit seen, swap running                |
| `SUCCESS`            | Yes      | Credited — your deposit webhook fires     |
| `INCOMPLETE_DEPOSIT` | Yes      | Deposit arrived below the minimum         |
| `REFUNDED`           | Yes      | Returned to `refundTo`                    |
| `FAILED`             | Yes      | See `failureReason`                       |
| `EXPIRED`            | Yes      | No deposit arrived in time; nothing moved |

> **Warning**
>
> **Success is pushed, failure is pulled.** A successful swap fires your existing
> `CUSTOMER_DEPOSIT` webhook. A failed, refunded, or expired one fires nothing.
> If you rely on webhooks alone, a refund is invisible to you and your customer
> is left guessing — poll this endpoint until the status is terminal.

Poll every 30–60 seconds while non-terminal. Terminal statuses never change.

## Amounts, slippage and fees

Three different "amount out" appear, and only one is a promise:

| Field             | Trust it?                      |
| ----------------- | ------------------------------ |
| `quotedAmountOut` | No — an estimate at quote time |
| `minAmountOut`    | **Yes** — the guaranteed floor |
| `actualAmountOut` | Yes, once the swap has run     |

Show `minAmountOut` to customers. Promising the quote and delivering less is a
support ticket you created for yourself. Realized slippage is
`(quotedAmountOut - actualAmountOut) / quotedAmountOut` — typically a fraction
of the tolerance you requested.

Two fees are reported, and both are easy to misread:

* **`withdrawFee`** — in the destination asset, and **already deducted inside
  the quote**. Do not subtract it a second time.
* **`refundFee`** — in the **origin** asset, charged only on a refund.

They are denominated in different assets, so never add them together.

Swaps below **\$10** of input are rejected: cross-chain costs would exceed what
the customer receives.

USD figures in responses are display only. Never use them for accounting.