Preview a Crypto Withdrawal
Quotes a withdrawal to a counterparty without making it: the fee, what the counterparty receives, and whether the account's balance covers it. Nothing is stored and nothing is reserved; the id it answers cannot be looked up.
The fee is taken inside the amount: the counterparty receives amount minus fee. When the fee is larger than the amount asked for, it is added on top instead: amount becomes the amount asked for plus the fee, and the counterparty receives the amount asked for.
The minimum withdrawal and the minimum fee are set in US dollars and converted into the coin at its market price, so in units of the coin they move with the price.
Part of crypto v3, in beta. While crypto v3 withdrawals are off for the account, this answers 404 feature_not_enabled.
A workspace-scoped key names the account with account_id; an account-scoped key acts for its own account.
Replaces POST /api/v2/crypto/withdraw/preview.
Authorization:
Every request is signed with your API key: a short-lived JWT, signed with your private key, sent in one header on /v3/* and /api/v2/* alike.
Headers:
Authorization: APIKey {SIGNED_JWT}
How to build and sign the JWT: Authentication.
Endpoint
/v3/crypto/withdrawals/preview
Query parameters
| Parameter | Type | Description |
|---|---|---|
account_id | string (cst_…) | The account to withdraw from. Required for a workspace-scoped key; an account-scoped key may omit it. |
Request Body Sample
{
"counterparty_id": "wlt_01k8z5q7r9s1t3v5w7x9y1z3a5",
"coin": "USDC",
"amount": "250",
"description": "Supplier payment"
}
Request Body Schema
| Field | Type | Description |
|---|---|---|
counterparty_id | string (wlt_…) | Required. One of the account's counterparties. |
coin | string | Required. The coin to send: the counterparty's coin. Any casing. |
amount | string (decimal) | Required. How much to withdraw, in the coin, greater than zero, as a decimal string. |
description | string | Optional. Up to 255 characters. |
Response Sample
{
"id": "wtx_01k9a0x2y4z6a8b0c2d4e6f8g0",
"account_id": "cst_01h455vb4pex5vsknk084sn02q",
"status": "preview",
"coin": "USDC",
"amount": "250",
"fee": "10",
"total": "240",
"counterparty_id": "wlt_01k8z5q7r9s1t3v5w7x9y1z3a5",
"counterparty_address": "0x8f3b2c1d0e9a7b6c5d4e3f2a1b0c9d8e7f6a5b4c",
"description": "Supplier payment",
"estimate": {
"provider": "fireblocks",
"network_fee": "0.00042",
"provider_fee": "0",
"expires_at": "2026-10-20T18:05:00Z"
}
}
Response Schema
| Field | Type | Description |
|---|---|---|
id | string (wtx_…) | A disposable id. Nothing is stored under it; pass it to the create as preview_id to record which preview was shown. |
account_id | string (cst_…) | The account. |
status | string | Always preview. |
coin | string | The coin, upper case. |
amount | string (decimal) | What would leave the balance. |
fee | string (decimal) | What the account would pay, inside amount. |
total | string (decimal) | What the counterparty would receive: amount minus fee. |
counterparty_id | string (wlt_…) | The counterparty. |
counterparty_address | string | Its address, without the memo. |
description | string | As sent; absent when empty. |
estimate | object | The custodian's own figures, when it can give them: provider; network_fee, its estimate of the network cost as it reports it; provider_fee; and expires_at, until when the estimate holds. For information only: they are not part of fee. Absent when the custodian gives none. |
Amounts are decimal strings in the coin, without trailing zeros (see Amounts). The amounts are computed again when the withdrawal is created.
Errors
| Status | message | When |
|---|---|---|
400 | account_id_required | A workspace-scoped key named no account_id. |
400 | invalid_account_id | account_id is not a cst_… id. |
400 | failed to parse request | The body is not valid JSON, counterparty_id is not a wlt_… id, coin is not a ticker, or amount is not a decimal. |
400 | invalid_coin | coin is a fiat currency, such as USD. |
400 | invalid_amount | amount is missing, zero or negative. |
400 | counterparty_coin_mismatch | coin is not the counterparty's coin. |
401 | unauthorized | Missing or invalid signature. |
403 | forbidden | An account-scoped key named another account. |
404 | feature_not_enabled | Crypto v3 withdrawals are not enabled for the account. See Turning it on. |
404 | counterparty_not_found | counterparty_id is missing, names no counterparty, or names another account's or a deleted one. |
422 | withdrawal_below_minimum | amount is below the minimum withdrawal for this coin. |
422 | withdrawal_coin_unsupported | BlockWyre cannot send this coin. |
422 | insufficient_balance | The account's available balance in this coin does not cover amount. |
422 | Validation failed | coin is missing, or description is longer than 255 characters; details names it. |
Coming from v2
v2 (POST /api/v2/crypto/withdraw/preview) | v3 |
|---|---|
accountId in the body | account_id in the query, optional for an account-scoped key |
beneficiaryId | counterparty_id (wlt_…): the same id as a TypeID |
beneficiaryAddress | counterparty_address |
| — | estimate |
Support and Resources
If you need assistance or have any questions, our support team is here to help. You can contact our support team at support@blockwyre.com.
Stay Updated
Stay up-to-date with the latest news, updates, and features from BlockWyre by following us on social media:
- Instagram: BlockWyre Instagram
- Twitter: BlockWyre Twitter
- Facebook: BlockWyre Facebook
- LinkedIn: BlockWyre LinkedIn
We are excited to have you on board and look forward to seeing how you leverage BlockWyre's powerful tools to enhance your financial operations. Happy integrating!