Skip to main content
Breet offers two levels of auto-settlement. Both automate the process of moving funds after a crypto deposit, but they work differently and can be used independently or together.

​
Per-address auto-settlement (via API)

This applies to individual wallet addresses. When you generate a crypto wallet address through the API, you can enable auto-settlement on that specific address. Once enabled, every deposit to that address is automatically converted and paid out to the bank account linked to it. Without per-address auto-settlement, crypto deposits are received, converted, and held in your chosen wallet currency (USD, NGN, or GHS). You can view the balance on your dashboard. You can set your preferred currency from the dashboard under Settings > Crypto Settings. You must then manually initiate a withdrawal. With per-address auto-settlement enabled, the entire flow from crypto receipt through currency conversion to bank payout happens automatically for that address.

​
Business-wide auto-settlement (via dashboard)

This applies to your entire business. You can activate it from your dashboard under Settings > Automatic Settlement. Once turned on, after every transaction across all your wallet addresses, a withdrawal is automatically placed for you to a single destination of your choice. The destination can be a bank account (NGN or GHS) or a stablecoin address. This means all deposits to all addresses funnel to one place, regardless of which address received the crypto.
Per-address auto-settlement lets you route each wallet address to a different bank account. Business-wide auto-settlement sends everything to one destination. You can use either or both depending on your needs.

​
How per-address auto-settlement works

1

Customer sends crypto

A customer sends crypto (e.g. BTC, USDT) to a wallet address generated via your integration.
2

Breet confirms the transaction

Breet detects and confirms the transaction on-chain.
3

Crypto is converted to USD

The crypto is converted to USD at the current market rate and the sell is marked as completed.
4

Auto-settlement kicks in

If the wallet has auto-settlement enabled and a linked bank account:
  • The USD amount is converted to local currency (NGN or GHS) using the current settlementRate.
  • If your integration has a markupPercent configured, the markup is deducted from the converted amount.
  • The remaining amount (amountSettled) is sent to the linked bank account.
5

Webhook is fired

A webhook is sent to your configured URL with the full transaction details, including the auto-settlement fields.

​
Prerequisites

Before per-address auto-settlement can work, complete these steps in order:
1

Generate a wallet address with bank details

Pass bank details during address generation to automatically link the bank to the wallet.
curl -X POST https://api.breet.io/v1/trades/sell/assets/{id}/generate-address \
  -H "x-app-id: YOUR_APP_ID" \
  -H "x-app-secret: YOUR_APP_SECRET" \
  -H "X-Breet-Env: production" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "my-btc-wallet",
    "bankId": "BANK_ID",
    "accountNumber": "0123456789",
    "narration": "BTC revenue"
  }'
If you need to change the linked bank account later, use PUT /trades/wallets/{id}/bank.
2

Enable auto-settlement

curl -X PUT https://api.breet.io/v1/trades/wallets/{id}/auto-settlement \
  -H "x-app-id: YOUR_APP_ID" \
  -H "x-app-secret: YOUR_APP_SECRET" \
  -H "X-Breet-Env: production" \
  -H "Content-Type: application/json" \
  -d '{
    "autoSettlement": true
  }'
The wallet must already have a linked bank account, otherwise the request will fail with a 422 Unprocessable Entity.
You can optionally set a markup percentage (0-10%) which is deducted from each settlement as your revenue margin. This can be configured via the API or from your dashboard under Settings. 
curl -X PUT https://api.breet.io/v1/users/integration/markup-percent \
  -H "x-app-id: YOUR_APP_ID" \
  -H "x-app-secret: YOUR_APP_SECRET" \
  -H "X-Breet-Env: production" \
  -H "Content-Type: application/json" \
  -d '{
    "markupPercent": 2.5
  }'

​
Comparison

Per-address (API)Business-wide (Dashboard)
ScopeIndividual wallet addressAll wallet addresses
SetupEnable via API per addressToggle in Settings > Automatic Settlement
DestinationBank account linked to that addressOne destination for your entire business
Destination typeBank account (NGN or GHS)Bank account (NGN or GHS) or stablecoin address
ScenarioWhat happens
Both offCrypto is received and converted to your chosen wallet currency (USD, NGN, or GHS). Funds remain in your wallet balance. You withdraw manually from the dashboard when ready.
Per-address onDeposits to that address are automatically converted and paid out to its linked bank account. Webhook includes settlement fields.
Business-wide onAfter every transaction across all addresses, a withdrawal is automatically placed to your configured destination.

​
Settlement calculation

Given a crypto deposit that converts to 100 USD, with a settlementRate of 1600 (NGN per USD), a settlementConversionRate of 1 (Nigeria), and a markupPercent of 2.5%: 
Converted amount   = 100 USD x 1600       = NGN 160,000
Markup amount      = NGN 160,000 x 2.5%   = NGN 4,000
Amount settled     = NGN 160,000 - 4,000   = NGN 156,000
For Ghanaian integrations, an additional conversion from NGN to GHS is applied using the settlementConversionRate.

​
Webhook payload with auto-settlement

When a trade completes and auto-settlement is applied, the webhook payload includes these additional fields:
FieldTypeDescription
markupPercentnumberThe percentage markup configured on your integration (e.g. 2.5).
markupAmountnumberThe absolute amount deducted as markup from the converted local currency amount.
amountSettlednumberThe final amount paid out to the linked bank account, after markup deduction.
settlementRatenumberThe exchange rate used to convert USD to the base local currency (NGN).
settlementConversionRatenumberThe conversion rate applied when settling in a secondary currency (e.g. NGN to GHS). For Nigerian accounts this is 1.
Auto-settlement works with or without a markup configured. When a markup percentage is set, these fields are populated with the calculated values. When no markup is set, the full converted amount is settled and these fields default to 0.

​
Example webhook (auto-settlement enabled)

{
  "id": "664363cb9cfe2c4286ccf472",
  "asset": "BTC",
  "feePercentage": 0,
  "feeAmountInUsd": 0,
  "cryptoAmount": 0.0025,
  "amountInUSD": 100,
  "flagFeeUSD": 0,
  "destinationAddress": "bc1q...",
  "txHash": "abc123...",
  "status": "completed",
  "event": "trade.completed",
  "settlementRate": 1600,
  "settlementConversionRate": 1,
  "amountSettled": 156000,
  "markupPercent": 2.5,
  "markupAmount": 4000,
  "createdAt": "2026-03-06T12:00:00.000Z",
  "updatedAt": "2026-03-06T12:00:05.000Z"
}
For full webhook documentation including all event types and verification, see the Webhooks guide.

​
Summary

  • Per-address auto-settlement: Link a bank to a wallet address, enable auto-settlement on it, and every deposit to that address is automatically converted and paid out to the linked bank account. You can optionally set a markup percentage as your revenue margin.
  • Business-wide auto-settlement: Toggle it on from the dashboard, set a single destination, and all deposits across all addresses are automatically settled there.
  • No auto-settlement: Crypto deposits are received, converted, and held in your chosen wallet currency (USD, NGN, or GHS). You withdraw manually when ready.
Use either or both options depending on your needs.