> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breet.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Auto-settlement
> Automatically convert incoming crypto deposits to local currency and pay out to a linked bank account using the Breet API.
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 should be a bank account (NGN or GHS). 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
A customer sends crypto (e.g. BTC, USDT) to a wallet address generated via your integration.
Breet detects and confirms the transaction on-chain.
The crypto is converted to USD at the current market rate and the sell is marked as completed.
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 `rate`.
* 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.
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:
Pass bank details during address generation to automatically link the bank to the wallet.
```bash theme={null}
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`](/api-reference/crypto-wallet/update-bank-for-existing-wallet-address).
```bash theme={null}
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`](/errors).
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**.
```bash theme={null}
curl -X PUT https://api.breet.io/v1/users/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) |
| -------------------- | ----------------------------------- | --------------------------------------------- |
| **Scope** | Individual wallet address | All wallet addresses |
| **Setup** | Enable via API per address | Toggle in **Settings > Automatic Settlement** |
| **Destination** | Bank account linked to that address | One destination for your entire business |
| **Destination type** | Bank account (NGN or GHS) | Bank account (NGN or GHS) |
| Scenario | What happens |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Both off** | Crypto 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 on** | Deposits to that address are automatically converted and paid out to its linked bank account. Webhook includes settlement fields. |
| **Business-wide on** | After 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 `rate` of **1600** (NGN per USD), and a `markupPercent` of **2.5%**:
```text theme={null}
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 `conversionRate`.
***
## Webhook payload with auto-settlement
When a trade completes and auto-settlement is applied, the webhook payload includes these additional fields:
| Field | Type | Description |
| --------------- | ------ | -------------------------------------------------------------------------------- |
| `markupPercent` | number | The percentage markup configured on your integration (e.g. `2.5`). |
| `markupAmount` | number | The absolute amount deducted as markup from the converted local currency amount. |
| `amountSettled` | number | The final amount paid out to the linked bank account, after markup deduction. |
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)
```json theme={null}
{
"id": "664363cb9cfe2c4286ccf472",
"asset": "BTC",
"feePercentage": 0,
"feeAmountInUsd": 0,
"cryptoAmount": 0.0025,
"amountInUSD": 100,
"flagFeeUSD": 0,
"senderAddress": "Tvg...",
"destinationAddress": "bc1q...",
"txHash": "abc123...",
"status": "completed",
"event": "trade.completed",
"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](/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.