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

# Deposits

Deposits are on-chain: you generate a deposit address for a customer, they send
funds to it, and Cheddar credits the deposit and fires a `CUSTOMER_DEPOSIT`
[webhook](/webhooks/events). There is no deposit action in the dashboard — deposits are
API-driven.

The webhook payload has **no deposit `status` field**. Map cleared vs flagged
deposits using **`isFlagged`** on `CUSTOMER_DEPOSIT` — see [Mapping deposits on your system](/webhooks/custodial#mapping-deposits-on-your-system).

A deposit is spendable once it is `CONFIRMED`. Credit only on
`CUSTOMER_DEPOSIT`: the earlier `CUSTOMER_DEPOSIT_PROCESSING` webhook is
informational, and a processing deposit can still end in
`CUSTOMER_DEPOSIT_FAILED`. See [Transaction statuses](/guides/transaction-statuses) for `PROCESSING`, confirmation tiers and
per-chain timing.

Missed a webhook? Query [`GET /deposits`](#check-deposit-status) to read the
current status and reconcile.

> **Tip**
>
> Your customer holds a token Cheddar doesn't custody? [Deposit swaps](/guides/deposit-swaps) accept almost any token on almost any chain and
> credit the balance in USDC — the same `CUSTOMER_DEPOSIT` webhook fires.

## Get a deposit address

`POST /deposit` returns a stable address for a `(customer, chain)` pair. Calling
it again for the same customer and token returns the same address.

```bash
curl -X POST https://api.cheddar.biz/v1/deposit \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{ "mintId": 1, "customerId": "your-customer-id" }'
```

```json
{ "customerId": "your-customer-id", "chain": "ETHEREUM", "address": "0x…" }
```

* `mintId` selects the token (and therefore the chain) — list options with
  `GET /mints`.
* `customerId` is **your** identifier for the end user. Cheddar creates the
  customer on first use.
* `customerEmail` is optional.

Show the returned `address` to your customer. When their transfer confirms,
you receive a `CUSTOMER_DEPOSIT` webhook.

## Check deposit status

Webhooks are the primary signal, but delivery can fail (your endpoint was down,
retries exhausted). `GET /deposits` is the fallback: it returns each deposit's
**current** state so you can reconcile your records.

```bash
# One deposit, by the `id` from the CUSTOMER_DEPOSIT webhook (returns the object, 404 if unknown)
curl "https://api.cheddar.biz/v1/deposits/3f2b8c1e-7a4d-4e9b-9c21-5d6e8f0a1b2c" \
  -H "x-api-key: YOUR_API_KEY"

# A customer's deposits in a time window
curl "https://api.cheddar.biz/v1/deposits?customerId=your-customer-id&from=2026-11-01T00:00:00Z&to=2026-11-02T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "items": [
    {
      "id": "3f2b8c1e-7a4d-4e9b-9c21-5d6e8f0a1b2c",
      "customerId": "your-customer-id",
      "status": "CONFIRMED",
      "isFlagged": false,
      "resolution": null,
      "resolvedAt": null,
      "mint": { "id": 1, "symbol": "USDC", "chain": "SOLANA" },
      "amount": "2500000",
      "uiAmount": "2.5",
      "txHash": "5x…",
      "fromAddress": "…",
      "toAddress": "…",
      "scannerUrl": "https://solscan.io/tx/5x…",
      "createdAt": "2026-11-01T10:00:00.000Z",
      "confirmedAt": "2026-11-01T10:00:12.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
```

| Filter             | Meaning                                                                              |
| ------------------ | ------------------------------------------------------------------------------------ |
| `depositId`        | The deposit `id` (UUID) — same as on `CUSTOMER_DEPOSIT` and the resolution webhooks. |
| `customerId`       | Your identifier for the customer.                                                    |
| `txHash`           | On-chain transaction hash.                                                           |
| `status`           | `PENDING`, `CONFIRMED`, `FLAGGED`, …                                                 |
| `from` / `to`      | ISO-8601 timestamps on `createdAt` (`from` inclusive, `to` exclusive).               |
| `limit` / `cursor` | Page size (1–100, default 20) and the previous page's `nextCursor`.                  |

Filters combine. Results are newest first.

Reading the result:

* **Credited**: `status: "CONFIRMED"` and `isFlagged: false`, or a flagged
  deposit with `resolution: "APPROVED"`.
* **Held for review**: `status: "FLAGGED"` and `resolution: null`. Do not credit.
* **Returned / sent elsewhere**: `resolution` is `"REFUNDED"` or `"REDIRECTED"`.
  Do not credit.

> **Tip**
>
> Poll sparingly. A good pattern is to re-query by `depositId` for deposits you
> hold as pending or flagged, plus a periodic `from`/`to` sweep over the last few
> hours to catch deposits whose first webhook never arrived.

## Flagged deposits

Cheddar screens incoming deposits against the reputation of the **sending
wallet**. A deposit that looks risky is held rather than credited, and someone
on your team decides what happens to it.

### When a deposit is screened

Screening runs only when all of the following hold:

* Your organization has both a **risk severity threshold** and a **USD
  threshold** configured, under **Organization → Risk Score Thresholds**. If
  either is unset, deposits are never screened.
* The deposit's USD value is **above** your USD threshold. Smaller deposits pass
  through untouched.
* The deposit has not already been flagged.

Cheddar then analyses the sending address and compares the returned severity
against your threshold. Anything at or below it is credited normally.

### What a flag does

A flagged deposit is **held, not credited**. Specifically:

* The customer's balance does **not** move. The funds stay in the deposit wallet
  and are excluded from sweeps.
* You still receive a `CUSTOMER_DEPOSIT` webhook, with `isFlagged: true` and
  `riskOfFunds` set to the severity. No **resolution** webhook is sent until the
  deposit is approved, rejected, or redirected.
* The reason — score, severity, and the entity behind the sending wallet, where
  the provider identifies one — is recorded and shown alongside the deposit.

> **Warning**
>
> If you credit players from `CUSTOMER_DEPOSIT`, check `isFlagged` before
> crediting. A flagged deposit may be returned to the sender or sent elsewhere,
> and the funds will not be yours.

### Resolving a flagged deposit

Flagged deposits appear under **Transactions to Approve → Flagged deposits**,
with the flag reason attached. There are three outcomes:

| Outcome      | What happens                                                                                                                                                | Who can do it  |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| **Approve**  | The deposit is credited and swept as normal.                                                                                                                | You or Cheddar |
| **Reject**   | The funds are returned to the address that sent them.                                                                                                       | You or Cheddar |
| **Redirect** | The funds are sent to a different address. Used when returning them is not the right answer — a compliance hold, or a destination named by law enforcement. | Cheddar only   |

Each outcome fires its own webhook — `CUSTOMER_DEPOSIT_APPROVED`,
`CUSTOMER_DEPOSIT_REJECTED`, or `CUSTOMER_DEPOSIT_REDIRECTED`. See [Webhook events](/webhooks/events) for payloads and timing; reject and redirect move funds
on-chain, so their events arrive only once the transfer confirms.

There is no deadline. A flagged deposit stays in the queue until someone acts on
it.

### When an action fails

If an action fails before anything reaches the chain — the transfer could not be
funded or broadcast — the deposit returns to the flagged queue and you simply try
again with the same buttons. Every failed attempt is kept and shown on the
deposit with its timestamp and reason, so a deposit that has failed repeatedly is
visible as such.

Once a transfer **has** been broadcast, the deposit does not return to the queue,
because the funds may already have left the wallet. Those cases are completed by
Cheddar rather than retried by you.

### Reviewing past decisions

**Transactions to Approve → Resolution history** lists resolved deposits: what
was decided, when, by whom, where the funds went, and the resulting transaction
hash. Redirects are included, so a decision Cheddar made on your deposits is
visible to you.