Deposits
Generate per-customer deposit addresses.
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. 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.
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 for PROCESSING, confirmation tiers and
per-chain timing.
Missed a webhook? Query GET /deposits to read the
current status and reconcile.
Your customer holds a token Cheddar doesn’t custody? 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.
mintIdselects the token (and therefore the chain) — list options withGET /mints.customerIdis your identifier for the end user. Cheddar creates the customer on first use.customerEmailis 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.
Filters combine. Results are newest first.
Reading the result:
- Credited:
status: "CONFIRMED"andisFlagged: false, or a flagged deposit withresolution: "APPROVED". - Held for review:
status: "FLAGGED"andresolution: null. Do not credit. - Returned / sent elsewhere:
resolutionis"REFUNDED"or"REDIRECTED". Do not credit.
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_DEPOSITwebhook, withisFlagged: trueandriskOfFundsset 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.
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:
Each outcome fires its own webhook — CUSTOMER_DEPOSIT_APPROVED,
CUSTOMER_DEPOSIT_REJECTED, or CUSTOMER_DEPOSIT_REDIRECTED. See Webhook
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.