Withdrawals

Initiate fund movements from your wallet to any external blockchain address — BTC and stablecoins across seven chains — with HMAC-signed, idempotent requests and webhook-driven confirmation.

Key Features

Three assets: BTC, USDT, and USDC — sent in the chain's smallest unit as a string to preserve precision.

Idempotent by design: A client-provided reference deduplicates retries — the same reference always returns the same withdrawal.

Stellar memo support: Pass memo through exactly as the destination exchange / wallet instructs for user-level attribution.

Async with webhooks: Subscribe to transfer.success for on-chain confirmation instead of polling.

Withdrawal API Endpoints

Create Withdrawal

Use Case

Initiate a withdrawal of cryptocurrency from your wallet to an external blockchain address. The withdrawal is processed asynchronously — you'll receive a pending status immediately and can track completion via webhooks or the Transactions API.

Create Withdrawal Request

Withdrawal Request Payload Schema

to_addressstringRequired

Destination blockchain address where funds will be sent. Must be a valid address format for the specified chain the API rejects addresses that don't match the chain's format (e.g. a Tron address on Ethereum).

amountstringRequired

Amount to withdraw, expressed as an integer string in the currency's smallest unit — 6-decimal minor units for USDT/USDC (e.g. '150500000' = 150.5 USDT) and satoshis for BTC (e.g. '100000000' = 1 BTC). Sent as a string to preserve precision.

currencystringRequired

Asset to withdraw. Supported values: 'USDC', 'USDT', 'BTC'. Must be a currency your account holds a balance in.

chainstringRequired

Blockchain network to settle the withdrawal on. Supported values: 'ethereum', 'bsc', 'polygon', 'solana', 'tron', 'stellar', 'bitcoin'. Must be supported for the chosen currency.

referencestringOptional

Unique client-generated identifier for this withdrawal, used for idempotency. Retrying a request with the same reference returns the original withdrawal instead of creating a duplicate — always include one when retrying on network errors.

memostringOptional

On-chain memo attached to the transaction. Primarily used on Stellar, where destination exchanges/wallets rely on the memo to attribute the deposit to a specific user. Leave as an empty string for chains that don't use memos or when the destination doesn't require one.

descriptionstringOptional

Internal note describing the purpose of the withdrawal (e.g. 'Vendor payment'). Stored with the transaction record for your own reconciliation — not sent on-chain.

Idempotency

Always include a unique reference value. If a network issue causes you to retry a request, the reference ensures the withdrawal is only processed once.

Request Body

Withdrawal Response

successBoolean

Top-level flag indicating whether the request was processed successfully.

messageString

Human-readable status message describing the outcome.

dataObject

Envelope wrapping the withdrawal record.

data.transaction_idUUID

Unique identifier for this withdrawal. Use it to look up the record via the Transactions API.

data.statusString

Current lifecycle state. One of 'pending' (accepted, awaiting broadcast), 'completed' (confirmed on-chain), or 'failed' (funds returned to available balance).

data.addressString

Destination blockchain address the funds are being sent to.

data.amountString

Amount in the currency's smallest unit (6-decimal minor units for USDT/USDC, satoshis for BTC).

data.currencyString

Asset being withdrawn: 'USDC', 'USDT', or 'BTC'.

data.chainString

Blockchain network the withdrawal is settling on (e.g. 'ethereum', 'tron', 'stellar', 'bitcoin').

data.referenceString

The client-provided idempotency key from the request, echoed back.

data.memoString

On-chain memo echoed back from the request. Populated for Stellar when the destination requires attribution; empty string otherwise.

data.descriptionString

The internal description from the request, echoed back for your reconciliation.

data.created_atDate

RFC 3339 / ISO 8601 timestamp of when the withdrawal record was created.

metadataObject

Top-level response metadata (support and debugging info).

metadata.request_idString

Unique identifier for this API request, useful for log correlation and support.

timestampDate

Top-level RFC 3339 / ISO 8601 server timestamp of when the response was generated (UTC).

Withdrawal Response

Withdrawal Status Lifecycle

After a successful POST, a withdrawal moves through up to two state changes before it reaches a terminal status. Funds are debited from your available balance the moment the withdrawal is accepted — they are returned only if it fails.

pending: Accepted by the API and queued for on-chain broadcast. Funds are already held against your balance.

completed (terminal): Broadcast and confirmed on-chain. The on-chain tx hash is delivered on the transfer.success webhook.

failed (terminal): Could not be completed. Held funds are returned to your available balance. Inspect the error for the reason.

Typical Lifecycle

State Transitions

Webhook-Driven Confirmation

Subscribe to the transfer.success event instead of polling — the webhook fires once the withdrawal is confirmed on-chain and carries the on-chain hash, fee, and timestamp. See the Webhooks documentation for setup.

Webhook Event Examples

Stellar Withdrawal Notes

When withdrawing to a Stellar destination, the receiving side (exchange, custodian, or shared-address service) often relies on a memo to attribute the incoming transfer to a specific account. Always include whatever memo the destination instructs — otherwise funds may land in the right address but be credited to the wrong account or held pending manual reconciliation.

Memo Is Passed Through As-Is

Bitnob does not generate, validate, or interpret the memo — it is forwarded exactly as provided on the Stellar transaction. Use the value the destination gave you; do not substitute your own.

Checklist for Stellar Withdrawals

Use a valid Stellar address for to_address (56-character, starts with G).

Set currency to a Stellar-supported asset (e.g. USDC) and chain to stellar.

If the destination provided a memo, copy it exactly into the memo field — matching type (text / id / hash) and casing.

If no memo is required, leave memo as an empty string.

Stellar Withdrawal — with destination memo

Stellar Withdrawal — no memo required


Error Responses
Common errors when creating withdrawals.
1
400 Bad RequestError
Invalid request body. Missing required fields, unsupported currency/chain combination, or invalid address format.
2
401 UnauthorizedError
Invalid or missing authentication headers.
3
402 Insufficient FundsError
Your available balance is less than the withdrawal amount. Check your balance before retrying.
4
409 ConflictError
A withdrawal with the same reference already exists. The existing withdrawal is returned in the response.
5
422 Unprocessable EntityError
The address is not valid for the specified chain, or the amount is below the minimum withdrawal threshold.
6
429 Too Many RequestsError
Rate limit exceeded. Wait and retry.
Error Response Examples