Skip to main content
A deposit happens when crypto is sent to a wallet address you generated via the API. Breet detects the transaction on-chain, waits for confirmations, runs checks, converts the value to FIAT, and credits your Breet wallet — or pays it out to a bank if you’ve enabled auto-settlement. Every deposit, successful or not, fires a webhook so you can react in real time.
You don’t need real crypto to integrate. In the sandbox environment, you can mock deposits to any of your addresses and exercise the full lifecycle — webhooks, confirmations, auto-settlement, everything — without sending real funds. See Testing for the step-by-step.
Let’s dig in further.

​
Deposit states

Each state change fires trade.pending, trade.completed, trade.flagged, or trade.deleted.

​
Happy path

1

You generate a deposit address

Call POST /trades/sell/assets/{id}/generate-address once per asset per user. Addresses are permanent and reusable — no need to generate a fresh one per deposit.
2

Your customer sends crypto

Any wallet or exchange, any amount. Breet has no control over this step.
3

Breet detects the transaction

When the transaction appears on-chain, Breet creates a deposit record and fires trade.pending with confirmations: 0, the txHash, and the amount.
4

Breet waits for confirmations

Confirmations required are configured per asset — don’t hardcode them. Treat trade.completed or trade.flagged as your source of truth. trade.pending may fire multiple times as confirmations increments.
5

Breet checks the amount

On the final confirmation, Breet checks that the deposit’s USD value meets the asset’s minimum (see thresholds or call GET /trades/assets).Meets the minimum → completed. Below the minimum → flagged.
6

Breet credits your wallet

On completed, Breet converts the USD value to your receive currency (USD, NGN, or GHS), deducts the platform fee (feeAmountInUsd), and credits your balance. trade.completed fires with the final amounts.If auto-settlement is enabled on the address, Breet also pays the net amount to the linked bank account. See Auto-settlement for the explanation.

​
Webhook sequence, by scenario

Use id + event as your idempotency key. Breet retries non-2xx deliveries up to 7 times — see Webhooks.

​
What happens when a deposit is flagged

A flagged deposit is held, not lost. Example: your customer sends $3 of USDT on Tron, minimum is $10. The deposit sits in flagged until one of three things happens:
  1. Customer tops up. Any later deposit to the same address in the same asset combines with outstanding flagged deposits at that address. The moment the combined USD total crosses the minimum, every flagged deposit flips to completed in one batch — one credit, one trade.completed per deposit, each carrying settledTrades with the id of every deposit in the batch. No fee applied. The trade.flagged payload carries balanceRemaining — how much more, in USD, has to land on that address to clear the minimum — so you can tell your customer the exact top-up amount. It already nets off every outstanding flagged deposit at that address, so each later below-minimum deposit fires its own trade.flagged carrying a smaller balanceRemaining.
  2. You pay a resolution fee. From your dashboard, or over the API. Breet deducts the resolution fee from the USD value of the crypto that was actually received, credits the remainder to your wallet immediately, and fires trade.completed with the flagFeeUSD field populated so your system knows a fee was applied. From the dashboard: log in to partners.breet.io, open the flagged transaction, click Pay Resolution Fee, and confirm. Over the API: see Resolving a flagged deposit via the API below.
  3. You’ve turned on auto-resolution. When trade auto-resolution is enabled on your integration, Breet handles step 2 automatically the moment a deposit is flagged — it deducts the resolution fee from the USD value of the crypto that was actually received, credits the remainder to your wallet, and fires trade.completed with flagFeeUSD populated. No dashboard action, no waiting on the customer. Turn this on from the Business tab on the Developer page in your dashboard, or with PUT /users/auto-resolution/enable.

​
Resolving a flagged deposit via the API

POST /trades/sells/sell/{id}/complete does from your backend exactly what Pay Resolution Fee does from the dashboard. Use it when you want to decide per deposit rather than switching auto-resolution on for every one.
1

Catch the trade.flagged webhook

The id on the payload is the deposit ID you pass to the endpoint.
2

Check that the deposit is resolvable by fee

Only deposits flagged for being below the minimum can be resolved this way. Fetch the deposit with GET /trades/transactions/{id}: status is flagged and passAMLCheck is true. A deposit flagged by an AML check is not eligible — contact support for those.
3

Work out what your customer nets

The resolution fee is the asset’s flagFeeUSD, returned by GET /trades/assets. Breet deducts it from amountReceived (the USD value actually received), so the credit is based on amountReceived - flagFeeUSD. That remainder must be greater than $1 — below that, the call returns 400 and a top-up is the only route.
4

Call the endpoint

No request body. The deposit is credited inside a single transaction, so the call either credits in full or changes nothing.
5

Settle on the webhook, not the response

trade.completed fires for the deposit with flagFeeUSD populated. Treat that event as your source of truth, exactly as you do on the happy path. If auto-settlement is enabled on the address, the net amount also pays out to the linked bank account and you’ll get the withdrawal.* events.

​
Edge cases

​
Wrong asset

If a customer sends a different asset to one of your addresses (e.g. they send ETH to a USDT address), recovery is automatic — no support ticket needed. This applies only if the received asset is one of our supported assets. What happens behind the scenes:
  1. We detect the asset mismatch.
  2. A new address is generated on your integration for the asset that actually arrived. The original wallet’s bank account and auto-settlement configurations are carried over.
  3. The deposit processes as a normal trade on the new wallet.
Webhooks you’ll receive, in order:
  • trade.address.created — new address payload with id, address, asset, label, and createdAt.
  • An email from us confirming the mismatch and recovery. No action needed on your end.
  • trade.pending → trade.completed — standard trade lifecycle on the new wallet. The trade.pending payload includes isWrongAssetDeposit: true so you can identify this as a wrong-asset recovery.
  • If auto-settlement was on: withdrawal.pending → withdrawal.processing → withdrawal.completed. Funds settle to the bank account from the original wallet.
  • If auto-settlement was off: funds credit your dashboard balance. Resolve with your user from there as you normally would.

​
USD value and timing

amountInUSD is recalculated on each webhook, not locked at detection. The value on trade.completed is authoritative — use it for accounting. Local-currency conversion uses the rate at completion time.

​
Chain reorganisations

Rare on supported networks. If a pending deposit is orphaned before it confirms, the deposit moves to deleted and fires trade.deleted — always before trade.completed could fire. Nothing is credited.

​
Fetching deposits via the API

Rather than relying only on webhooks, you can inspect deposits directly:
On every webhook, fetch the deposit by id before updating your system of record. Combined with IP and secret verification, this is defence in depth.

​
FAQ

Seconds/Minutes on Solana/Tron/TON; up to an hour on slow chains. If a deposit is pending for more than 6 hours, contact support with the txHash.
No. Generate a separate address per customer (or per order) and pass their ID in the label field. When a deposit webhook fires, destinationAddress and destinationDescription (the label) tell you exactly who paid.Addresses are permanent and reusable, so you generate a customer’s address once, store it, and reuse it for all their future deposits.
No. Your customer pays their own on-chain fee. Breet’s only charge on a deposit is the platform fee (feeAmountInUsd).
feeAmountInUsd is the platform fee on a normal completed deposit. flagFeeUSD is the resolution fee applied when you pay to release a flagged below-minimum deposit — from your dashboard, over the API, or automatically through auto-resolution. On the happy path, flagFeeUSD is 0.
Yes. Call POST /trades/sells/sell/{id}/complete to pay the resolution fee for one deposit, or turn on auto-resolution with PUT /users/auto-resolution/enable to have every below-minimum deposit resolved the moment it’s flagged. See Resolving a flagged deposit via the API.

​
Next steps