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

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

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

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