Withdrawals

A withdrawal moves funds out of your Breet wallet. The Partners API supports two types:

Crypto withdrawals to an external wallet address — POST /payments/withdraw/address. Stablecoins (USDT, USDC) on Ethereum, Tron, BSC, Solana, TON, and Base, plus the UTXOs BTC, LTC, DOGE, and BCH. Debited from your USD balance.
Bank withdrawals to an NGN or GHS bank account — POST /payments/withdraw/bank/{id}. Debited from your local-currency balance.

Both types share the same lifecycle and webhook events. This page focuses on crypto withdrawals; bank withdrawals differ in destination and currency. The fee bearer setting applies to both. For automatic bank payouts tied to deposits, see Auto-settlement.

Withdrawal states

State	What it means
`pending`	Request accepted, your USD balance debited in full, queued for processing. Not yet on-chain.
`processing`	Approved and being paid out. Not yet confirmed on-chain. `txHash` is populated once the transaction is broadcast. Balance stays debited.
`completed`	Broadcast succeeded and confirmed on-chain. `txHash` is populated. Balance stays debited.
`reversed`	Broadcast was attempted but was unsuccessful. Balance refunded in full.
`rejected`	Failed an internal check before broadcast. Not sent on-chain. Balance refunded in full.

Each state change fires a webhook: withdrawal.pending, withdrawal.processing, withdrawal.completed, withdrawal.reversed, or withdrawal.rejected.

Rejected ≠ reversed. Both refund your balance, but rejected means Breet blocked the withdrawal before it touched the blockchain; reversed means the transaction came back with a failure after an attempt to broadcast it. Only withdrawal.completed means the funds are on-chain at the destination.

Withdrawal assets (mainnet)

Stablecoins — pick a network:

Network	USDT	USDC
Ethereum (ERC20)	Yes	Yes
Tron (TRC20)	Yes	Yes
BNB Smart Chain (BSC)	Yes	Yes
Solana	Yes	Yes
TON	Yes	No
Base	No	Yes

UTXOs — single-chain, no network: BTC, LTC, DOGE, BCH. See UTXO withdrawals. Call GET /payments/supported-assets-info for what is currently enabled on your integration — a token missing from that response cannot be withdrawn. For testnet IDs and the full deposit/withdrawal asset catalog, see Supported assets.

Validating an address

POST /payments/wallet-addresses/validate checks an address against a token and network before you submit a withdrawal.

{
  "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
  "token": "USDT",
  "network": "TRC20"
}

A valid address returns 200:

{
  "success": true,
  "message": "wallet address is valid",
  "data": {
    "address": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE",
    "token": "USDT",
    "network": "TRC20",
    "valid": true
  }
}

An invalid one returns 422.

This is a check on the address format only — that it is well-formed for that token and network. It does not confirm the address exists, is reachable, or is permitted. A withdrawal to an address that passes here can still be rejected. See Common failures.

Before you can withdraw

Requirement	Detail
Active credentials	Valid `x-app-id` / `x-app-secret`, integration in `active` state.
Funded USD wallet	Balance ≥ `amount`, debited at request time. If your fee bearer is `business`, you need `amount + fee`.
PIN set	The `pin` field is required in the request body. Set or rotate it from the dashboard.
Account in good standing	Suspended or frozen accounts are blocked.
IP allowlist (optional)	If configured on your integration, the request must come from an allowed IP.

Happy path

You submit the request

Call POST /payments/withdraw/address:

{
  "amount": 100,
  "token": "USDT",
  "network": "TRC20",
  "walletAddress": "TRecipientTronAddressHere...",
  "pin": "1234",
  "externalId": "your-internal-id-123"
}

Field	Notes
`amount`	USD value, up to 2 decimal places. Subject to your integration’s min/max.
`cryptoAmount`	Alternative to `amount` — the value in crypto units, up to 8 decimal places. Send `amount` or `cryptoAmount`, never both.
`token`	`USDT`, `USDC`, `BTC`, `LTC`, `DOGE`, or `BCH`.
`network`	`ERC20`, `TRC20`, `BSC`, `SOL`, `TON` (USDT only), or `BASE` (USDC only). Stablecoins only — omit it for UTXOs.
`feeLevel`	`low`, `medium`, or `high`. Required for UTXOs. Ignored for stablecoins, which use a flat fee per network. See UTXO withdrawals.
`walletAddress`	Valid address for the token and network. Cannot be a Breet-managed address.
`pin`	Required even for server-to-server calls.
`externalId`	Optional. Your reference, useful for matching webhooks.

Breet responds synchronously with the withdrawal id.

Breet validates and debits

Synchronous checks, in order:

Credentials and integration active.
IP in allowlist (if configured).
PIN is correct. After enough wrong attempts the account is frozen, and you must reset the PIN to unfreeze it.
amount within min/max.
Address is valid for the network and not a Breet-managed address.
Not a duplicate. The same amount to the same address within 1 minute is rejected. See Duplicate withdrawals.
Sufficient balance — amount, or amount + fee if your fee bearer is business.

All pass → the amount is debited, withdrawal is created with status: pending, withdrawal.pending webhook is queued.Any fail → no record, no debit, no webhook. You receive an HTTP error. See Error handling.

Breet approves and broadcasts

Approval is mostly automatic. The withdrawal moves to processing, then the transaction is signed and broadcast on the chosen network. By default the recipient receives amount − fee on-chain (see Fees).Withdrawals flagged for internal review may stay in pending until Breet approves (typically within a few minutes).

Breet confirms completion

Once the withdrawal is successful, withdrawal.completed fires with the on-chain txHash.

Webhook sequence, by scenario

Scenario	Events (same `id`)
Clean withdrawal	`withdrawal.pending` → `withdrawal.processing` → `withdrawal.completed`
Blocked pre-broadcast	`withdrawal.pending` → `withdrawal.rejected` (refunded)
Broadcast failed	`withdrawal.pending` → `withdrawal.processing` → `withdrawal.reversed` (refunded)

Webhook delivery is asynchronous and ordering isn’t guaranteed under variable endpoint latency. Trust the event and status fields on each payload, not the order they arrive in.

UTXO withdrawals

BTC, LTC, DOGE, and BCH use the same endpoint as stablecoins, with three differences. No network. Each UTXO runs on exactly one chain. Sending network alongside a UTXO is rejected with {token} does not support a network. feeLevel is required. low, medium, or high — it decides how much network fee is paid, and so how quickly the transaction confirms. Stablecoins ignore it. The network fee is dynamic. Stablecoins carry a flat fee per network; UTXOs are quoted per request against live network conditions. Estimate it first.

Pricing in USD or in crypto units

Send either amount (USD, up to 2 dp) or cryptoAmount (crypto units, up to 8 dp) — exactly one. Breet converts with the market rate at the time of the request and records it on the withdrawal as meta.cryptoAmountRate. Your USD balance is debited either way, and your integration’s min/max still applies to the USD value. A cryptoAmount outside the range is rejected with both bounds shown in crypto units and USD.

Estimating the network fee

Call POST /payments/estimate-network-fee with the UTXO token, the amount, and the destination:

{
  "token": "BTC",
  "cryptoAmount": 0.01,
  "walletAddress": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"
}

You get back all three levels, in crypto units and USD:

{
  "low": { "networkFee": 0.00001842, "networkFeeUsd": 1.21 },
  "medium": { "networkFee": 0.00002765, "networkFeeUsd": 1.82 },
  "high": { "networkFee": 0.00004212, "networkFeeUsd": 2.77 }
}

Estimates are cached for 60 seconds and the endpoint is limited to 5 requests per minute.

An estimate is not a locked quote. The fee is re-estimated when the withdrawal is submitted, so the fee recorded on the withdrawal can differ from what you were quoted.

What the recipient gets

By default the fee is deducted from the amount you requested, the same as for stablecoins. withdrawalFeeBearer changes that. The withdrawal records both sides of the conversion:

Field	Meaning
`cryptoAmount`	Crypto units actually sent on-chain, after the fee.
`feeCrypto`	Network fee in crypto units.
`fee`	The same network fee, in USD.
`meta.cryptoAmountRate`	USD per crypto unit used for the conversion.
`meta.cryptoAmount`, `meta.amountUsd`	What you requested, before the fee.

If the fee would consume the whole withdrawal, the request is rejected with the {token} network fee of $X leaves no payout for a $Y withdrawal — nothing is debited.

Fees and minimums

Stablecoin withdrawals carry a small flat fee per network, readable from GET /payments/supported-assets-info. UTXO withdrawals carry a dynamic network fee instead. Either way the fee is reported on the withdrawal and its webhooks as fee. By default the fee is deducted from the amount you request. Your balance is debited the full amount, and the recipient receives amount − fee on-chain. You can flip this with withdrawalFeeBearer. Example. You call with amount: 100, USDT on Tron, fee $1. Your balance is debited $100. The recipient receives $99 of USDT on Tron.

Who bears the fee

Every withdrawal carries a fee. The withdrawalFeeBearer setting on your integration decides who absorbs it — you or your end-user. It applies to all withdrawals: bank, stablecoin, and UTXO. You control this yourself. Open the Developer page in your partner dashboard, go to the Business tab, and set Withdrawal fee bearer to one of:

User — your end-user pays. The fee comes out of the payout, so the recipient gets less than you requested. This is the default.
Business — you pay. The fee is added to what we debit from your balance, so the recipient gets the full amount.

You can also change it with PUT /users/withdrawal-fee-bearer. Bank withdrawals carry a flat fee per payout, set per destination currency. Read the fee that currently applies to your integration from GET /users/fetch-integration as withdrawalFee:

"withdrawalFee": {
  "ngn": 50,
  "ghs": 1
}

Crypto withdrawals carry the network fee instead — flat per network for stablecoins, dynamic for UTXOs. The bearer setting works the same way on both.

`withdrawalFeeBearer`	Debited from your balance	Recipient is credited	Use when
`user` (default)	`amount`	`amount − fee`	You pass the fee on to your end-user.
`business`	`amount + fee`	`amount`	You absorb the fee so your end-user is paid in full.

Example. A ₦50,000 payout with a ₦50 fee:

user — your balance is debited ₦50,000, the destination account is credited ₦49,950.
business — your balance is debited ₦50,050, the destination account is credited ₦50,000.

Breet charges the fee exactly once either way. The setting only decides who absorbs it, never how much it is. Crypto example. You call with amount: 100, USDT on Tron, fee $1:

user — your balance is debited $100, the recipient receives $99 of USDT.
business — your balance is debited $101, the recipient receives $100 of USDT.

Auto-settlement payouts follow this setting too.

Changing it

A new value applies only to withdrawals created after you save it. A withdrawal already in pending keeps the pricing it was created with. To check what is live now, read withdrawalFeeBearer from GET /users/fetch-integration. Every withdrawal also records the bearer that applied to it as meta.feeBearer, so you can reconcile a payout against the setting that was live when it was created.

Duplicate withdrawals

Breet rejects a repeat of the same USD amount to the same destination address within 1 minute:

{
  "success": false,
  "message": "Duplicate withdrawal detected. Enter a different amount."
}

Common failures

Status	Message	What it means
422	`invalid wallet address`	The address is not well-formed for that token and network. Validate it first.
422	`{token} does not support a network`	You sent `network` with a UTXO token. Omit it.
422	`feeLevel must be one of: low, medium, high`	`feeLevel` is missing or invalid on a UTXO withdrawal.
403	`{token} withdrawals are currently disabled`	That token is switched off for your integration. Check `GET /payments/supported-assets-info`.
403	`the minimum crypto amount required is …`	Your `cryptoAmount` converts to a USD value outside your min/max. Both bounds are shown in the message.
403	`the {token} network fee of $X leaves no payout for a $Y withdrawal`	The fee would consume the whole withdrawal. Nothing is debited.
403	`you can not use a Breet wallet address for this action`	The destination is a Breet-managed address. Use an external one.
400	`unable to fetch network fee for {token} on {level} fee level`	The fee estimate failed. Retry.
400	`unable to quote a {token} network fee right now, …`	Breet cannot price a payout that size in that coin. See Temporary payout capacity.
400	`Duplicate withdrawal detected. Enter a different amount.`	See Duplicate withdrawals.
400	`insufficient balance`	Your USD balance is below the amount to debit.
403	`insufficient wallet balance`	Same cause, caught at the point of debit.

See Error handling for the full response shape.

Fetching withdrawals via the API

Purpose	Endpoint
List withdrawals	`GET /payments/withdrawals`
Fetch one by ID	`GET /payments/withdrawal/{id}`

On every webhook, fetch the withdrawal by id before updating your system of record. Combined with IP and secret verification, this is defence in depth.

FAQ

Can I withdraw BTC, ETH, SOL, or other native coins?

BTC, LTC, DOGE, and BCH are supported — see UTXO withdrawals. Other native coins, including ETH and SOL, are not. To move those, sell them via a deposit first, then withdraw as a stablecoin.

Can I cancel a pending withdrawal?

Not via API. Contact support immediately after submitting if it’s critical. Once approved and broadcast, the withdrawal can only complete or reverse.

What if I send to the wrong address?

On-chain transactions are irreversible. Breet validates address format, not ownership. Always confirm the destination with your end-user before submitting.

How quickly do withdrawals complete?

Seconds/Minutes on Solana, Tron, and TON. Longer on EVM chains due to confirmation times. For UTXOs, the feeLevel you pick decides it — high confirms soonest, low can take much longer when the network is busy.

Why do I need a PIN for an API call?

It’s an additional verification layer in case your API keys leak. Store the PIN alongside your secrets and rotate it from the dashboard if exposed.

Next steps

Set up webhook handling → Webhooks
See supported withdrawal networks and tokens → Supported assets
Handle 429s correctly → Rate limiting
Simulate a withdrawal on testnet → Testing

Getting started

Core concepts

Use cases

Withdrawal states

Withdrawal assets (mainnet)

Validating an address

Before you can withdraw

Happy path

Webhook sequence, by scenario

UTXO withdrawals

Pricing in USD or in crypto units

Estimating the network fee

What the recipient gets

Fees and minimums

Who bears the fee

Changing it

Duplicate withdrawals

Common failures

Fetching withdrawals via the API

FAQ

Next steps

​Withdrawal states

​Withdrawal assets (mainnet)

​Validating an address

​Before you can withdraw

​Happy path

​Webhook sequence, by scenario

​UTXO withdrawals

​Pricing in USD or in crypto units

​Estimating the network fee

​What the recipient gets

​Fees and minimums

​Who bears the fee

​Changing it

​Duplicate withdrawals

​Common failures

​Fetching withdrawals via the API

​FAQ

​Next steps

Withdrawal states

Withdrawal assets (mainnet)

Validating an address

Before you can withdraw

Happy path

Webhook sequence, by scenario

UTXO withdrawals

Pricing in USD or in crypto units

Estimating the network fee

What the recipient gets

Fees and minimums

Who bears the fee

Changing it

Duplicate withdrawals

Common failures

Fetching withdrawals via the API

FAQ

Next steps