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

StateWhat it means
pendingDetected on-chain, waiting for confirmations. Nothing has been credited.
completedFully confirmed, checks passed, wallet credited (and settled if auto-settlement is on).
flaggedConfirmed on-chain but below the asset’s minimum deposit amount. Funds are held, not credited.
Each state change fires trade.pending, trade.completed, or trade.flagged.

​
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

ScenarioEvents (same id)
Clean deposittrade.pending → trade.completed
Slow confirmationstrade.pending (×N as confirmations increments) → trade.completed
Below minimumtrade.pending → trade.flagged
Flagged → later resolvedtrade.flagged → trade.completed
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 $20. The deposit sits in flagged until one of two 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. No fee applied.
  2. You pay a resolution fee from your dashboard. Log in to partners.breet.io, open the flagged transaction, click Pay Resolution Fee, and confirm. 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.

​
Edge cases

​
Wrong asset or wrong network

If a customer sends a different asset to one of your addresses (e.g. USDT-BSC to a USDT-Tron address), it is not auto-credited. Contact support with the txHash — recovery is manual and not guaranteed.

​
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 settlementRate at completion time.

​
Chain reorganisations

Rare on supported networks. If a pending deposit is orphaned before it confirms, the deposit moves to a non-credited terminal state — always before trade.completed could fire.

​
Fetching deposits via the API

Rather than relying only on webhooks, you can inspect deposits directly:
PurposeEndpoint
List depositsGET /trades/transactions
Fetch one by IDGET /trades/transactions/{id}
List your wallet addressesGET /trades/wallets
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. On the happy path, flagFeeUSD is 0.

​
Next steps