Skip to main content
Move funds into and out of WhiteBIT programmatically: generate deposit addresses, submit crypto and fiat withdrawals, convert between currencies before withdrawing, settle between accounts with WhiteBIT Codes, and charge a WhiteBIT user’s balance with Express Withdraw. Each flow documents the transaction lifecycle, status state machine, fee calculation, and webhook events, where each applies.
EEA users: USDT deposits and withdrawals have been unavailable since December 30, 2024 (MiCA compliance). Use USDC or EURI as alternatives. See Regulatory Compliance for details.

Prerequisites

Before integrating any flow on this page:
  • API key — create an API key with the required permissions in the WhiteBIT dashboard. Every authenticated endpoint on this page except Issue card token requires HMAC-signed requests (X-TXC-APIKEY, X-TXC-PAYLOAD, X-TXC-SIGNATURE headers). Store the secret per Security Best Practices. Issue card token takes a JWT in the Authorization header, as its reference page describes; see Fiat withdrawal.
  • Webhook URL — configure the webhook endpoint to receive transaction notifications. See Webhooks for the setup flow.
  • Fiat access — fiat operations additionally require completed institutional onboarding with approved fiat access.
  • Convert terms — for the flows that convert, the account owner accepts the Convert terms once on whitebit.com before the first conversion. See Convert.

Use cases

Four scenarios cover the most common partner integrations. Each closes with a link to the section documenting the endpoints.

UC1 — Payment provider with per-end-user deposit address

A payment-provider partner assigns each end customer a unique deposit address and credits the customer’s account when funds arrive. Reconciliation is webhook-driven by uniqueId (each deposit address — plus memo on memo networks — corresponds to one customer in the partner’s database). See Unique address per user for endpoint detail.

UC2 — EEA crypto withdrawal with Travel Rule

A partner serving EEA end users submits withdrawals with the required travelRule object. The withdrawal goes through compliance review before on-chain broadcast. See Create a withdrawal for endpoint detail.

UC3 — Crypto payout with conversion

When the partner holds one currency on the Main balance but needs to send another, transfer the source currency to the Trade balance, wait until the amount shows, and convert it. Then transfer the converted amount back to the Main balance, wait until the amount shows, and submit the withdrawal. Convert through the API uses the Trade balance for both legs; see Convert. See Conversion in the withdrawal flow for endpoint detail.

UC4 — Charge a WhiteBIT user’s balance (Express Withdraw)

A merchant or partner service collects a crypto payment from a WhiteBIT user’s balance instantly and off-chain: the partner creates a single-use payment token, presents the returned URL, and the user confirms in one tap. Settlement is an internal zero-fee transfer into the partner’s Main balance. See Express Withdraw payments for endpoint detail.

Crypto deposits

Generate deposit addresses, track the deposit lifecycle, handle refunds, and clear Travel Rule holds.

Deposit address generation

This section covers one shared wallet per ticker and network. For a customer’s own address, see Unique address per user. Generate a deposit address by calling POST /api/v4/main-account/address. See the API Reference for the full endpoint specification. Required parameters: Optional parameters: network — cryptocurrency network (e.g., ERC20, TRC20). Required for multi-network currencies like USDT; omit for single-network currencies. Query the Asset Status endpoint for available networks per currency. The endpoint creates the address when none exists and returns the same address for the same ticker and network combination on repeated calls — addresses are permanent and reusable, not ephemeral. All tokens on one network share the address for that network. The endpoint does not return addresses created with POST /api/v4/main-account/create-new-address. Key response fields: account.address, account.memo (for currencies requiring a memo or destination tag), required.fixedFee, required.flexFee, required.minAmount, required.maxAmount. Rate limit: subject to platform-level rate limits — see Rate Limits for current enforced values.
For Go and PHP examples, see SDKs.

Unique address per user

The POST /api/v4/main-account/address endpoint above returns the same address for the same ticker and network combination on every call. For payment provider integrations that assign a unique deposit address per end user, use POST /api/v4/main-account/create-new-address instead — each successful call generates a fresh address, even when the previous address is unused; on memo networks, each call returns the same address with a new memo. The address is stored before the response is sent: after a timeout or a 5xx response, the address may already exist and still credit deposits to the account, but no endpoint returns the address. Store the address before showing it, and after a timeout show no address and request a new one. Before calling the endpoint, look up the address stored for the end user, the currency, and the network. Call the endpoint only when none is stored (see Address issuance and end-user mapping). See the API Reference for the full specification.
The /create-new-address endpoint is not available by default and returns 403 until access is enabled. Request access through the account manager. The number of addresses is not capped.
For sub-accounts, crypto deposits are disabled by default. To enable deposits, contact the assigned account manager. Each sub-account also needs its own deposit permission, depositsEnabled.
Required parameters: Optional parameters: network (required for multi-network currencies; for USDT the default network is ERC20), type (address type for currencies that support several formats — BTC and LTC accept p2sh-segwit and bech32; the default is bech32). Rate limit: subject to platform-level rate limits — see Rate Limits for current enforced values.
Choosing between the two endpoints: The choice depends on the partner’s reconciliation model. Partners managing one consolidated wallet per asset (treasury, market-maker, single-merchant) use /address; repeat calls return the same address. Partners assigning one address per end customer (payment provider, per-user wallet) use /create-new-address; each successful call returns a fresh address, or a new memo on memo networks, so an incoming deposit identifies the end user by its address, or by its memo on memo networks.

Deposit lifecycle

After funds arrive at a generated deposit address, the deposit passes through a defined sequence of states before crediting to the Main balance.
  1. Address issued: POST /api/v4/main-account/create-new-address for a customer’s own address (a new memo on memo networks), or POST /api/v4/main-account/address for one shared wallet per ticker and network (see Unique address per user)
  2. Funds sent by the external party — mempool detection begins
  3. Confirmation tracking begins — the deposit.accepted webhook may fire while confirmations.actual is below confirmations.required; not every crypto deposit sends deposit.accepted, so do not wait for the event
  4. Each confirmation-count change fires the deposit.updated webhook with the new confirmations.actual — this event tracks progress; it does not signal completion
  5. Where the network’s confirmations_for_trading count is lower than confirmations: funds credited early, and part of the deposit may stay held — status 29, deposit.updated webhook fires. See Network confirmations.
  6. Deposit fully confirmed and credited to Main balance (status 3 or 7) — deposit.processed webhook fires, and any hold clears — terminal success state
  7. OR: Deposit canceled — status 4 fires the deposit.canceled webhook; status 9 sends no webhook, so read the status from the history — terminal failure state
  8. OR (EEA/Turkey): Travel Rule hold — deposit frozen (status 27 or 28). If the Travel Rule API is enabled, submit originator data via API to unfreeze; otherwise manual action at whitebit.com is required. See Travel Rule below.

Deposit status state machine

The deposit/withdraw history endpoint returns numeric status codes. The following table maps each code to the meaning and the corresponding webhook event.
Numeric status codes are namespaced by transactionMethod. The same code may mean different things for deposits (transactionMethod: 1) and withdrawals (transactionMethod: 2). Always interpret the code in the context of the transactionMethod that returned it.
Every deposit ends in a final status: 3 or 7 (credited) or 4 or 9 (canceled). Statuses 5, 21, 22, 23 and 29 are not final. A deposit in status 29 ends as 3 or 7 when the network fully confirms it, or as 4 if canceled. The flowchart maps each deposit status in the table to the partner action.
Use POST /api/v4/main-account/history with transactionMethod: 1 to poll deposits. Omit the status filter. A filter on 3 and 7 alone leaves out deposits in every other status in the table, such as canceled (4, 9), on-hold (21, 29) or uncredited (22) deposits. A watcher that waits only for those codes never sees a canceled deposit and never closes. See the endpoint page for the current enforced rate limit.

Network confirmations

Each cryptocurrency network has two confirmation counts. At the earlier count, confirmations_for_trading, the platform credits the deposit for trading only. At the later count, confirmations, the deposit also becomes available for blockchain withdrawal, for transfer to the Collateral balance, and for transfer from a sub-account to its main account. Until the deposit reaches confirmations, the Main balance endpoint reports the held amount as pending_deposit_amount. During the hold, the deposit has status 29; the hold clears when the deposit reaches status 3 or 7, which the deposit.processed webhook reports. Webhook payloads include confirmations.actual and confirmations.required fields. Query the Asset Status endpoint (GET /api/v4/public/assets) for both counts per network. Confirmation requirements vary by currency and network. Do not hardcode specific numbers — always retrieve the current values from the Asset Status endpoint.

Partial / over-payment scenarios

Crypto deposits credit the actual on-chain amount received; the system does not flag deposits as “underpaid” or “overpaid”. A deposit below the network minimum (limits.deposit.<network>.min in Asset Status) is not credited at once: the deposit waits in status 22, deposits to the same address add up, and the deposits are credited together once the total reaches the minimum. Deposits that stay below the minimum are canceled with status 9 after 7 days. If a partner expects an exact amount (e.g., for invoice matching), reconciliation logic must compare the deposit amount in the deposit.processed webhook against the expected amount and surface mismatches as application-level alerts.

Refund flow

Only a crypto deposit in status 9 can be refunded through the API, and only when the deposit was frozen before it was canceled: held for an AML review (status 21) or under the Travel Rule (status 27 or 28). A deposit in status 4 and a deposit in status 9 that was never frozen cannot be refunded through the API. A refund becomes available in this order:
  1. The deposit is frozen (status 21, 27 or 28).
  2. WhiteBIT rejects the deposit after review, and WhiteBIT support allows a refund. The deposit moves to status 9.
  3. The partner sends the refund request.
Until support allows a refund, the endpoint returns 400 for the deposit. When support handles the refund itself, the endpoint keeps returning 400 for that deposit. Endpoint: POST /api/v4/main-account/refund-deposit — see the API Reference for the full specification and every reason for a 400 response. Prerequisites:
  • Support allowed a refund for the deposit, and no active refund of the deposit exists.
  • Obtain transactionId from the deposit/withdraw history in the WhiteBIT interface. A deposit in status 9 sends no webhook.
Parameters: The refund address must satisfy three constraints:
  • The address must support the same network and asset as the original deposit.
  • The address must not be a WhiteBIT-generated deposit address (an address created by /api/v4/main-account/address or /api/v4/main-account/create-new-address) — the endpoint refunds to external addresses only.
  • The address does not need to match the original sender address.
Review after the request: a 200 response means the refund request is accepted, not that the refund is sent. The request needs no email code or 2FA confirmation. Every refund then passes AML screening and an operator review, and WhiteBIT sends the refund on-chain only after approval. Until then, refund history shows the refund as in_process with refundHash null. A 423 response means another refund request from the same account is still in progress. Webhook events for refund outcomes (sent to the webhook of the account that owns the deposit):
  • refund.successful — refund completed. Includes refundAmount (the amount sent on-chain), refundNetworkFee and refundHash
  • refund.failed — the review rejected the refund, or a refund attempt failed. After a rejection, refund history shows canceled and no funds are sent
Track refund status: POST /api/v4/main-account/refund-history returns every refund on the account with its current status. A refund with status canceled is final. A refund with status in_process is not final yet, including after a refund.failed webhook caused by an internal failure. Filter by depositId to check one deposit. The refundAmount in refund history is the deposit amount; the amount sent on-chain and the network fee are only in refund.successful. The sequence shows a refund of a deposit in status 9 and each refund outcome. Rate limit: subject to platform-level rate limits — see Rate Limits for current enforced values.

Required endpoints for deposits

For integrations that use a single persistent deposit address instead of unique addresses per user, substitute POST /api/v4/main-account/address (API Reference) for the /create-new-address endpoint.

Travel Rule (EEA and Turkey)

Since May 18, 2025, WhiteBIT places inbound crypto deposits for EEA and Turkey accounts on hold until Travel Rule verification completes.
  • Status 27 (DEPOSIT_TRAVEL_RULE_FROZEN): deposit frozen, awaiting Travel Rule data from the account holder
  • Status 28 (DEPOSIT_TRAVEL_RULE_FROZEN_PROCESSING): Travel Rule data submitted, under review by WhiteBIT
API-based verification: When the Travel Rule API is enabled for the account, partners can submit originator data via POST /api/v4/travel-rule/deposit/verification to unfreeze deposits programmatically. See Travel Rule for the full verification flow and request format.
Manual verification fallback: If the Travel Rule API is not enabled for the account, frozen deposits require manual action at whitebit.com. Request Travel Rule API access through the account manager.
See Regulatory Compliance for the full Travel Rule reference. See the Travel Rule help center article for the complete requirements.

Crypto withdrawals

Submit crypto withdrawals, attach the Travel Rule payload for EEA accounts, and follow the withdrawal state machine and fee model.

Create a withdrawal

Submit a crypto withdrawal by calling POST /api/v4/main-account/withdraw. See the API Reference for the full endpoint specification. Two withdrawal endpoints are available:
Crypto withdrawals cannot be reversed once broadcast on-chain. Verify the destination address and network before submitting the request — funds sent to a wrong address or an incompatible network are lost.
Internal-transfer routing: When the destination address belongs to another WhiteBIT user, the platform may route the transfer as an internal off-chain transfer rather than an on-chain broadcast, in which case no blockchain fee applies and the recipient sees the funds immediately. This routing is not guaranteed for every destination — confirm the behavior with WhiteBIT for the specific flow before designing around fee-free instant settlement, or funds may settle on-chain with the standard fee. For deterministic fee-free settlement between known WhiteBIT accounts, use WhiteBIT Codes rather than relying on withdrawal auto-routing.
Required parameters: Optional parameters: network (for a multi-network currency, send it on every withdrawal, with the value from the Asset Status response; when network is omitted, the default for USDT is ERC20), memo (for currencies requiring a memo or destination tag). Rate limit: subject to platform-level rate limits — see Rate Limits for current enforced values.

Travel Rule for EEA withdrawals

Crypto withdrawals from EEA accounts require a travelRule object in the request body. The object identifies the destination wallet and, for hosted wallets, the destination VASP (Virtual Asset Service Provider — the exchange or custodian hosting the receiving wallet). See Travel Rule for the full schema reference and request examples.

Legacy format (deprecated)

The platform still accepts the legacy flat format, but legacy submissions do not pass Travel Rule verification. Migrate to the structured format above for compliance.
See Travel Rule — Legacy format for migration guidance.

Withdrawal confirmation model

After a withdrawal request is submitted, the system validates the request and begins processing. The POST /api/v4/main-account/withdraw endpoint returns HTTP 201 when validation succeeds. The 201 body is an empty array and carries no withdrawal ID, so follow the withdrawal by the uniqueId sent in the request, in the deposit and withdrawal history. The platform confirms and processes API-initiated withdrawals immediately — the signed request is the authentication. There is no interactive 2FA step between the POST response and the processing start. Exceptions to immediate processing:
  • Sub-account withdrawals wait for main-account approval before processing. A waiting withdrawal does not expire and sends no webhook; the main account finds it with List Unconfirmed Sub-Account Withdrawals.
  • Withdrawals to AML-blocked destination addresses freeze pending compliance review.
  • Temporary withdrawal freeze (72 hours) applies after a password change or a 2FA setting change on the account. Transfers between balances and to or from sub-accounts remain available during the freeze.
Status transitions follow the state machine below: unconfirmed → pending → successful or canceled. Webhook events track the lifecycle from withdraw.unconfirmed (status 5) onward. When two withdrawals compete for the same balance and one fails processing, that withdrawal is retried; if processing still fails, the withdrawal ends as canceled (status 4) and withdraw.canceled is sent.
A revised confirmation model for IP-whitelisted API keys is planned but not yet deployed. Contact institutional@whitebit.com for availability.

Withdrawal status state machine

The withdrawal lifecycle progresses through the following states. The flowchart maps each withdrawal status in the table to the partner action.

Fee calculation

Withdrawal fees combine a fixed component and a flexible (percentage-based) component. Fee model (sourced from the deposit address endpoint response and the Asset Status endpoint):
  • fixedFee — flat fee charged regardless of amount
  • flexFee — percentage-based fee with floor and ceiling:
    • percent — percentage rate
    • minFee — minimum fee (floor)
    • maxFee — maximum fee (ceiling)
Fee calculation formula:
If maxFee is "0", no ceiling applies. Worked example — BTC withdrawal of 0.5 BTC:
Fee parameters vary by currency and network. Query the Asset Status endpoint (GET /api/v4/public/assets) for current fee values.

Required endpoints for withdrawals

For withdrawals that include currency conversion before sending, see Withdrawal with conversion for the extended endpoint list.

Fiat operations

Generate fiat deposit invoices and submit fiat withdrawals once institutional fiat access is approved.

Prerequisites for fiat operations

Fiat deposit and withdrawal operations require completion of institutional onboarding with approved fiat access. This flow applies to the institutional partner’s main account. For sub-account fiat scope and constraints under Embedded Trading, see the Embedded Trading integration guide.
Fiat operations require completion of institutional onboarding including business verification (KYB) and fiat provider approval. See Institutional Onboarding for the full two-phase process. Fiat endpoints are not available until WhiteBIT explicitly approves fiat access.
The onboarding process has two phases: Phase 1 (crypto access via KYB) and Phase 2 (fiat access via fiat processing partner review). Fiat access is not automatic after KYB approval — a separate review process with the fiat processing partner is required.

Fiat deposit

The fiat deposit flow is invoice-based: generate a payment URL, hand it to the end user, and reconcile the settlement.
1

Generate a deposit invoice

Call POST /api/v4/main-account/fiat-deposit-url with the fiat ticker, amount, provider, and a partner-side uniqueId. The response contains a url. See the API Reference for the full specification.
2

Present the URL to the end user

The payer opens the returned URL and completes the payment with the provider: an end user pays by card, and a bank transfer comes only from the partner’s own KYB’d bank account.
3

For SEPA: add the payment reference

The bank transfer from the partner’s own KYB’d bank account must carry the uniqueId in the payment-reference field — see SEPA payment reference below.
4

Confirm completion and reconcile

Find the deposit in the deposit history (POST /api/v4/main-account/history) by the uniqueId of the request. The Main balance (POST /api/v4/main-account/balance) reports totals per currency and does not identify the deposit. Act on the deposit status as the Deposit status state machine describes.
The fiat deposit endpoint requires per-account activation. Request access through the account manager and provide the API key.
Required parameters: Optional parameters:
Not every fiat ticker is depositable via API. Check can_deposit in the Asset Status response before generating an invoice; tickers without API deposit support run through the WhiteBIT web interface.
The endpoint returns a URL that the end user opens to complete the fiat deposit. Take the provider value for the currency from the Asset Status response.

SEPA payment reference

The uniqueId submitted in the /fiat-deposit-url request must appear in the SEPA payment-reference field of the bank transfer. The transfer comes only from the partner’s own KYB’d bank account. WhiteBIT uses this string to match the incoming SEPA settlement to the original deposit request. A transfer without the reference, or with an altered one, may settle unmatched.

Card-provider flows

VISAMASTER Referer header: When using the VISAMASTER provider, configure the browser to send the Referer header when opening the invoice link. If the header is missing (e.g., when opening the link from a Telegram message or an email client that strips referrers), WhiteBIT redirects the end user to the homepage instead of the payment provider. Test the redirect path in the actual deployment surface (mobile app, email link, in-app web view) before go-live.

Deposit request errors

Common synchronous rejections from /fiat-deposit-url and the recovery for each:

Fiat withdrawal

Create a fiat withdrawal using the same POST /api/v4/main-account/withdraw endpoint used for crypto, specifying a fiat ticker. The same withdrawal endpoints apply (/withdraw and /withdraw-pay). Pass the currency in ticker (for example EUR or USD) and the payment provider from the Asset Status response in provider (for example VISAMASTER). Do not pass USD_VISAMASTER or EUR_VISAMASTER as ticker. A bank payout (IBAN, SEPA) goes only to the partner’s own KYB’d bank account. The IBAN goes in address. The Create withdraw request reference lists the providers that also need bankBic, and the On/Off-Ramp guide shows a complete SEPA request body. Card payouts use the card token flow below. For a card withdrawal with provider: "VISAMASTER", pass the card token returned by Issue card token in address. The Issue card token call authenticates with a JWT from Issue JWT token. The Issue card token reference page lists the required headers. The API does not accept a card number (PAN) and does not read a card token from beneficiary. The beneficiary object is required for fiat withdrawals with tickers USD and EUR. Set partialEnable to true for increased maximum limits — the application must then handle status 18 (“Partially successful”).

Beneficiary object fields

Sub-field requirements vary by ticker and provider. Verify the current contract on the Create Withdraw reference before integration. Fiat withdrawals require KYC verification. Accounts without KYC verification cannot process fiat withdrawals.
In exceptional cases, the WhiteBIT institutional team may grant a per-account override that permits fiat withdrawal without standard KYC. This is exception-only — not a default capability. Contact institutional@whitebit.com for integrations with a documented case requiring the override.
See Institutional Onboarding for the full fiat onboarding process.

Required endpoints for fiat operations

WhiteBIT Codes

Move balance fee-free between WhiteBIT accounts by creating and applying codes.

WhiteBIT Codes overview

WhiteBIT Codes enable fee-free value transfer between WhiteBIT accounts. WhiteBIT Codes are alphanumeric strings representing a fixed amount of a specific currency. One account creates a code, shares the code string via any channel, and another account applies the code to receive the funds.
  • Fee-free — no fees for creating or applying codes
  • Use cases: internal transfers between accounts, promotional distributions, settlement between sub-accounts or partner accounts
  • Optional passphrase protection (up to 25 characters)

Lifecycle and behavior

State machine: A WhiteBIT Code moves through two states: created (an unredeemed code exists; the platform reserves the creator’s funds) and applied (terminal — the code has been redeemed; funds credited to the redeemer). There is no void or cancel operation; the creator cannot reclaim an unredeemed code. Apply failures: Codes may fail to apply for several reasons (expired, invalid format, non-existent, wrong passphrase). The apply response distinguishes an already-applied code and a code applied by its own creator; the platform collapses the remaining failure modes into a generic rejection. If a redeemer’s apply fails on a recently-created code, request a fresh code from the creator. Correlation: The code string is the only correlation key shared between creator and redeemer. The creator-side description field is creator-only and not exposed to the redeemer. Partners running redemption flows must map the code to an internal user ID on the partner side.
The code string is a bearer token — possession grants redemption, and the creator cannot reclaim an unredeemed code. A leaked code is spendable by whoever holds it.
Security model: Share codes through trusted channels and consider the optional passphrase for an additional protection layer. Passphrases accept Latin letters, digits, and ASCII symbols (no whitespace, no Unicode) up to 25 characters. Treat the code string as sensitive on the partner side: do not log it in plaintext, do not include it in error reports, do not commit it to version control.

Create and apply a code

The code lifecycle has two steps: create and apply. Create: POST /api/v4/main-account/codes — see the API Reference Required parameters: Optional parameters: Key response fields: code — the generated WhiteBIT Code string to share with the redeemer; message — success message; external_id — external identifier. Rate limit: subject to platform-level rate limits — see Rate Limits for current enforced values. Apply: POST /api/v4/main-account/codes/apply — see the API Reference Required parameters: Optional parameters: Rate limit: subject to platform-level rate limits — see Rate Limits for current enforced values. Webhook event: code.apply fires when an account applies a code.

Express Withdraw

Charge a WhiteBIT user’s balance in one confirmation with a single-use payment token.

Express Withdraw payments

Express Withdraw lets an approved partner charge a specific amount from a WhiteBIT user’s balance in one confirmation. The partner integrates a single endpoint — POST /api/v4/main-account/express-withdraw/token (API Reference) — and WhiteBIT hosts everything the paying user sees. Settlement is an internal balance move: instant, off-chain, and fee-free on both sides.
Express Withdraw is available only for B2B partner services and requires a separate approval process. Request access through the account manager. Without the permission, the endpoint returns 403 Forbidden.

Token lifecycle

A payment token moves through four states:
  1. Created — the partner calls the create-token endpoint with ticker, amount, and a partner-side externalId (order or invoice identifier). The response carries the payment url and expireAt (UTC); every token is valid for 90 seconds after creation.
  2. Presented — the partner hands the url to the user as a redirect, mobile deep link, or QR code. Treat the value as opaque: WhiteBIT returns the hosted web confirmation page by default, or a deep link when one is configured for the partner at onboarding; the token travels in the token query parameter either way.
  3. Confirmed (terminal) — the user, authenticated on WhiteBIT, reviews the exact ticker and amount and confirms. WhiteBIT re-validates balance, limits, and permissions, debits the user, credits the partner’s Main balance in the same operation, and marks the token used.
  4. Expired (terminal) — a token left unconfirmed for 90 seconds becomes unusable. Re-create the payment with the same externalId; WhiteBIT issues a fresh token.
Create the token as close as possible to the moment of presenting it — the 90-second window covers the user’s review and confirmation, not the partner’s checkout flow.

Idempotency and replay protection

The externalId is unique per partner account and drives both guarantees:
  • Re-requesting a token for the same externalId with an identical ticker and amount while the token is still valid returns the same token — safe to retry after a timeout without double-charging.
  • Changing ticker or amount for a pending externalId fails with error code 18 — parameters of a pending payment cannot change; use a new externalId.
  • Re-submitting an externalId that the user already paid fails with error code 19 — the order is settled, and the rejection prevents a duplicate charge.
See the endpoint page for the full error-code table.

Limits and eligibility

  • Per-payment cap: 10,000 USDT-equivalent, rejected with error code 191 above the cap. WhiteBIT enforces the cap at token creation and re-enforces it at confirmation.
  • Currency: crypto only; the ticker must be withdrawal-enabled on the platform. The endpoint rejects fiat tickers.
  • No self-payments: the paying user and the token creator must be different WhiteBIT accounts.
  • Payer eligibility: at confirmation the user must have withdrawals enabled, pass the standard withdrawal restriction checks, and hold a sufficient balance.
  • Rate limits: standard private-API limits apply — see Rate Limits; the endpoint has no endpoint-specific limit.

Withdrawal with conversion

Convert the source currency before withdrawing, using the Convert service.

Conversion in the withdrawal flow

When the currency held in Main balance differs from the currency the end user needs to withdraw, convert the funds before the withdrawal. Convert through the API uses the Trade balance for both legs. Transfer the source currency from Main to Trade and wait until the amount shows on the Trade balance before the conversion. Then transfer the converted amount back to Main and wait until the amount shows on the Main balance before the withdrawal. See Convert balances.

Step-by-step flow

1

Check Main balance

Verify the source currency is available in Main balance.Endpoint: POST /api/v4/main-account/balance — API Reference
2

Transfer the source currency to Trade

Transfer the source currency from Main to Trade. The transfer returns 201 with an empty array ([]). The 201 means accepted, not completed. Request the estimate after the transferred amount shows on the Trade balance (POST /api/v4/trade-account/balance). The transfer request takes no idempotency key, and a transfer can still complete after a timeout or a 5xx, so check Get transfer history for the transfer. A matching record means the transfer completed. No record can also mean the transfer is still queued, so repeat the check and do not resend automatically. A transfer that never shows is a manual check, as the between-balances row in Retry strategy by error type describes.Endpoint: POST /api/v4/main-account/transfer — API Reference
3

Request a conversion estimate

Request a quote for converting the source currency to the withdrawal currency. The response includes an id (quote identifier), the quoted rate, and expireAt (Unix timestamp in seconds).Endpoint: POST /api/v4/convert/estimate — API Reference
4

Confirm the conversion

Confirm the quote using quoteId from the estimate response. A 200 response means the conversion executed, and the converted amount is on the Trade balance. For responses that leave the outcome open, see Results and retries.Endpoint: POST /api/v4/convert/confirm — API Reference
5

Transfer the converted amount to Main

Transfer the converted currency from Trade to Main. The withdrawal endpoints debit the Main balance, so withdraw after the transferred amount shows on the Main balance (POST /api/v4/main-account/balance). A transfer that never shows is a manual check, as the between-balances row in Retry strategy by error type describes.Endpoint: POST /api/v4/main-account/transfer — API Reference
6

Create withdrawal request

Submit a withdrawal to the end user’s external address using the converted currency. To tie the withdrawal to its conversions, put a reference unique to the withdrawal in uniqueId; see Convert in payment flows.Endpoint: POST /api/v4/main-account/withdraw or POST /api/v4/main-account/withdraw-pay — API Reference
7

Receive webhook confirmation

The withdraw.successful webhook fires when the withdrawal completes. See Webhooks for setup and signature verification.
8

Verify via history

Query the history endpoint to confirm the withdrawal status. See Withdrawal status state machine for the full status state machine.Endpoint: POST /api/v4/main-account/history — API Reference
The convert service sets quote expiry per quote and returns the value in expireAt (Unix timestamp in seconds). Confirm the quote before that time elapses, or request a new estimate. See Convert for full parameter details, direction options, and history queries.

Conversion errors

Common synchronous rejections from /convert/confirm and the recovery for each:
Error text is not part of the contract and may change. Treat the HTTP status, the code, and the field name under errors as the stable contract.

Code example

Convert USDT to BTC and withdraw BTC to an external address. The estimate returns a short-lived quote — confirm it before it expires, or request a new one: The critical-path call is the estimate: the confirm step reuses the quote id from the estimate response. The Crypto deposits section defines the send_request() helper used below.
For Go and PHP examples, see SDKs.

Required endpoints for withdrawal with conversion

Webhook reconciliation

Reliable fund tracking requires both webhook-based and polling-based reconciliation. Primary method — webhooks for real-time notifications:
  • Configure the webhook URL (see Webhooks)
  • Verify the HMAC-SHA512 signature on every incoming webhook. Each delivery includes three headers — X-TXC-APIKEY (the WhiteBIT webhook API key), X-TXC-PAYLOAD (base64-encoded JSON body), and X-TXC-SIGNATURE (HMAC-SHA512 of the payload with the webhook key’s secret). See Security Best Practices for the verification algorithm.
  • Track the nonce field — each webhook nonce is strictly greater than the previous. The nonce travels inside the JSON payload, not in a separate header.
Retry policy: The platform retries failed deliveries on a best-effort basis, with no guaranteed cadence. See Webhooks for the delivery window. Fallback method — poll POST /api/v4/main-account/history:
  • Use transactionMethod: 1 for deposits, transactionMethod: 2 for withdrawals
  • Omit status, so the response returns every status for the chosen transactionMethod (see the deposit and withdrawal status tables)
  • Recommended polling interval: every 5 minutes for active monitoring
  • See Rate Limits for current enforced values
For balance endpoints, WebSocket account streams, and polling-interval guidance beyond deposits and withdrawals, see Account Monitoring. Deduplication: Use the uniqueId from webhook payloads and history responses to deduplicate across webhook and polling paths.
The meaning of uniqueId differs by direction: for withdrawals, the value echoes the identifier supplied in the withdrawal request; for crypto deposits, the platform assigns the value (the transaction identifier that the refund endpoint consumes as transactionId); for fiat deposits, the history record carries the uniqueId of the deposit request. All are unique per transaction and safe as idempotency keys.
WhiteBIT does not offer a webhook replay mechanism. Implement polling as a fallback to reconcile events missed during extended consumer downtime. Store all processed uniqueId values to prevent double-processing.
Reconciliation pattern:
  1. Receive webhook — verify signature — extract uniqueId and status
  2. Store the event with uniqueId as the idempotency key
  3. On polling cycle: query the history endpoint — compare uniqueId values against stored events
  4. Process any events found via polling that the webhook path did not deliver
  5. Mark transactions as complete only when the transaction reaches a terminal status (3/7 for success, 4/9 for canceled deposits, 4 for canceled withdrawals)
The flowchart combines the webhook path and the polling path into one reconciliation loop.

What’s next

Webhooks

Webhook setup, event types, signature verification, and retry behavior.

Convert

Estimate and confirm flow, plus conversion history queries.

Security Best Practices

API key management, IP whitelisting, and secret storage.

On/Off-Ramp Guide

Journey-level guide for corporate fiat ↔ crypto clients: onboarding gates, EUR/SEPA flows, and failure paths.