Withdrawals lifecycle

See Withdrawal statuses for the full status table and integration notes.

Create, listen, then settle

Request a withdrawal quote through the API (POST /withdrawal/quote)
Commit the quote (POST /withdrawal/commit)
Listen for withdrawal.statusChanged webhook events
Update your internal withdrawal status when the withdrawal reaches a final status (completed or failed)

Merchant requests a withdrawal quote and commits it

A withdrawal can be initiated either:
- through the admin panel
- via the API
When creating a withdrawal, the merchant provides the required details, such as:
- destination wallet address
- cryptocurrency
- either auto converting withdrawal allowed or not
- amount
Through the API, the flow is two steps:
1. Quote — returns a fee estimate and a short-lived quoteId
2. Commit — creates the withdrawal in created status and debits the required balance, including the network fee
Once the quote is committed, Cryptonly begins processing the withdrawal.
Cryptonly sends the on-chain transaction

Cryptonly creates and broadcasts an on-chain transaction based on the withdrawal request details.

The withdrawal moves to processing while the underlying network transfer is prepared, broadcast, and monitored.
Withdrawal completion and webhooks

Cryptonly sends a withdrawal.statusChanged webhook on each status transition after commit.

Your integration should handle at least:
- created → processing — on-chain send has started
- processing → completed — withdrawal confirmed on-chain
- processing → failed — withdrawal could not be completed; debited balance is returned
Treat completed and failed as final statuses for fulfilment.

The webhook endpoint can be defined in the admin panel, set as an organization default, or passed directly in the withdrawal commit API call.

Statusescreated, processing, completed, and failed

Auto convertingCover a shortfall before the quote is committed

Fees and commissionsNetwork fee returned on the quote

WebhooksVerify withdrawal.statusChanged