Crypto Withdrawals

A crypto withdrawal sends crypto from your Confirmo balance to one of your own accounts in the Crypto Address Book. You can withdraw whenever you want, with no settlement schedule to wait for.

How a withdrawal works

A withdrawal has two steps:

1. Create. You choose the destination and the amount. Confirmo locks the network fee and reserves the funds on your balance. The withdrawal is prepared.
2. Confirm. You accept the locked fee before it expires. The withdrawal is confirmed, and Confirmo sends it.

1. Create the withdrawal

curl -X POST https://confirmo.net/api/v3/withdrawals/crypto \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a1e-1f7b-4d55-9a8e-2b9a3f0c7d11" \
  -d '{
    "cryptoAddressId": "cab7Ym1kPq3",
    "balanceAssetId": "USDC",
    "balanceQuantity": 25000,
    "feePaymentMode": "net",
    "reference": "treasury-sweep-2026-10",
    "notifyUrl": "https://merchant.example/hooks/withdrawals",
    "notifyEmail": "[email protected]"
  }'

Withdrawal endpoints accept an optional Idempotency-Key header (see Idempotent requests in the API reference). Use it so that a retried request doesn't create a second withdrawal.

Response 201 Created

{
  "id": "cwdQ8nB2xL5",
  "status": "prepared",
  "substatus": null,
  "address": "0x1111111111111111111111111111111111111111",
  "networkId": "ETHEREUM-BLOCKCHAIN-MAINNET",
  "balanceAssetId": "USDC",
  "enteredBalanceQuantity": 25000,
  "networkFeeQuantity": 1.84,
  "totalFeeQuantity": 1.84,
  "debitedBalanceQuantity": 25001.84,
  "feePaymentMode": "net",
  "expiresAt": 1772539320,
  "reference": "treasury-sweep-2026-10",
  "notifyUrl": "https://merchant.example/hooks/withdrawals",
  "createdAt": 1772539200
}

All amounts and fees are in the withdrawn asset. Confirmo pays the gas in the network's native token and charges you the equivalent in the asset you withdraw.

2. Confirm before expiresAt

The fee quote is valid for a short time, about 2 minutes. Use expiresAt to check. Confirm within the window:

curl -X PATCH https://confirmo.net/api/v3/withdrawals/crypto/cwdQ8nB2xL5 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "CONFIRM" }'

If you don't confirm in time, the withdrawal moves to expired and the reserved funds return to your balance. Create a new withdrawal to get a fresh quote.

Network fees

You choose who pays the fee with feePaymentMode:

In gross mode, a withdrawal that is too small to cover the fee is refused with crypto_withdrawal_amount_below_fee.

Lifecycle

Withdrawals use the payout lifecycle without the draft and pending_verification steps:

substatus on canceled

A cancelled withdrawal is never retried. To try again, create a new one.

Reading withdrawals

The list is newest first. createdAtFrom and createdAtTo are inclusive Unix timestamps in seconds. limit is at most 100.

On-chain details are in the nested transaction object. It is absent until a transaction exists. Its hash is absent until the transaction is broadcast.

Withdrawals are reported separately from payouts in the settlements API (GET /v3/settlements: cryptoWithdrawalAmountSum, cryptoWithdrawalFeeSum, cryptoWithdrawalIds).

Webhooks and emails

• Webhooks. If you set notifyUrl, Confirmo sends a POST with the full withdrawal object every time the status changes (prepared, confirmed, sending, done, canceled, expired). Webhooks are signed with your callback password, like payout webhooks. Re-read the withdrawal before acting on a webhook.
• Delivery-failure email. If webhook delivery keeps failing, Confirmo sends a warning to notifyEmail, or to your account email if you didn't set one.
• No webhook configured. If you didn't set a notifyUrl, Confirmo emails notifyEmail when a withdrawal is canceled.

Permissions