v1

latestOpenAPI 3.0.32026-07-2613529376.3 KB
Withdraw

Create express withdraw token

The endpoint creates a signed, single-use Express Withdraw payment token that charges a specific amount from a WhiteBIT user's balance to the partner's Main balance in an instant, off-chain, zero-fee internal transfer. The response returns a URL that embeds the token; the paying user confirms the exact ticker and amount on the WhiteBIT-hosted confirmation surface.

Token and payment constraints:

  • Each token is single-use: WhiteBIT marks the token used at confirmation and rejects any replay.
  • Each token expires 90 seconds after creation; the expireAt response field carries the authoritative expiry timestamp. Generate the token as close as possible to the moment of presenting the URL to the user.
  • The ticker must be a withdrawal-enabled cryptocurrency; the endpoint rejects fiat tickers.
  • Each payment is capped at the equivalent of 10,000 USDT; WhiteBIT enforces the cap at token creation and re-enforces the cap at confirmation.
  • WhiteBIT rejects self-payments: the paying user and the token creator must be different WhiteBIT accounts.
  • The endpoint is idempotent per externalId: re-submitting the same externalId with an identical ticker and amount while the token is still valid returns the same token instead of creating a duplicate charge. After the token expires, the same externalId receives a fresh token.
<Note> Standard private-API rate limits apply — see [Rate limits](/api-reference/rate-limits). The endpoint carries no endpoint-specific limit. </Note>
post/api/v4/main-account/express-withdraw/token

Request body

tickerstring required

Currency ticker to charge. Example: USDT

⚠️ The ticker must be a withdrawal-enabled cryptocurrency; the endpoint rejects fiat tickers. Use Asset Status endpoint to check the withdrawal status of a currency.

amountstring required

Amount to charge in the specified ticker. Numeric string.

⚠️ The amount converted to USDT-equivalent must not exceed 10,000; the endpoint rejects larger amounts with error code 191.

externalIdstring required

Partner-side reference for the payment (order or invoice identifier), unique per partner account. The identifier powers idempotency and replay protection: a pending externalId with an identical ticker and amount returns the same token; the endpoint rejects an already-paid externalId with error code 19.

requeststring required

Request signature

nonceinteger required

Unique request identifier

Example request

{
  "ticker": "USDT",
  "amount": "25.50",
  "externalId": "order-100294",
  "request": "{{request}}",
  "nonce": 1594297865000
}

Response

Token created. Present the returned URL to the paying user before the expiry in expireAt.

urlstring

URL to present to the paying user (redirect, deep link, or QR code). The value is the WhiteBIT-hosted web confirmation page by default, or a mobile deep link when one is configured for the partner at onboarding; in both cases the unique token travels in the token query parameter. Treat the value as opaque.

expireAtstring

Absolute token expiry timestamp in YYYY-MM-DD HH:MM:SS format (UTC). The authoritative expiry: each token expires 90 seconds after creation.

Example response

{
  "url": "https://whitebit.com/express-withdraw?token=8f3c0a7d4e21",
  "expireAt": "2026-07-10 12:34:56"
}