WhiteBIT Codes

WhiteBIT Codes are fee-free digital vouchers for transferring cryptocurrency between WhiteBIT accounts. A code encapsulates a specific amount of a currency — the creator generates the code, shares the code string, and the recipient applies the code to receive the funds.

Use cases

Codes provide a simple transfer mechanism without requiring the recipient’s deposit address.

Internal transfers — Move funds between accounts without withdrawal fees
Partner payouts — Distribute funds to multiple recipients by generating codes programmatically
Promotions and rewards — Create codes as promotional vouchers; optionally protect with a passphrase

Code lifecycle

The code lifecycle has two phases: creation and application.

Create a code

Send a POST request to /api/v4/main-account/codes with ticker (e.g., ETH), amount (string, up to 18 decimal places), optional passphrase (max 25 characters, latin letters + numbers + symbols, no whitespace), and optional description (max 280 characters, visible only to the creator). The amount is debited from the Main balance. The response returns a code string (format: WB{uuid}{TICKER}, e.g., WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH) and an external_id.

Share the code

Transmit the code string to the intended recipient. If a passphrase was set, share the passphrase separately.

Apply the code

The recipient calls POST /api/v4/main-account/codes/apply with the code string and passphrase (if set). Funds are credited to the recipient’s Main balance. A code.apply webhook event fires on the creator’s account.

API endpoints

WhiteBIT Codes uses 4 authenticated endpoints. All operate on the Main balance.

Endpoint	Purpose	Rate limit
`POST /api/v4/main-account/codes`	Create a new code	1,000 req / 10 sec
`POST /api/v4/main-account/codes/apply`	Apply (redeem) a code	60 req / 1 sec
`POST /api/v4/main-account/codes/my`	List codes created by the account	1,000 req / 10 sec
`POST /api/v4/main-account/codes/history`	Full code history (created + applied)	1,000 req / 10 sec

Create parameters

Parameter	Type	Required	Description
`ticker`	string	Yes	Currency ticker (e.g., `ETH`, `BTC`)
`amount`	string	Yes	Amount to encapsulate. Up to 18 decimal places. Must be greater than 0, capped at 1e17, and not exceed the Main balance.
`passphrase`	string	No	Optional protection. Latin letters, numbers, symbols only. Max 25 characters. No whitespace.
`description`	string	No	Internal note visible only to the creator. Max 280 characters.

Code example

Create a code for 0.002 ETH with a passphrase, then apply the code on a different account.

cURL
Python

# Step 1: Create a WhiteBIT code
curl -X POST https://whitebit.com/api/v4/main-account/codes \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
  -H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "ETH",
    "amount": "0.002",
    "passphrase": "mySecretPass1",
    "request": "/api/v4/main-account/codes",
    "nonce": 1
  }'

{
  "code": "WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH",
  "message": "Code was successfully created",
  "external_id": "be08a482-5faf-11ed-9b6a-0242ac120002"
}

# Step 2: Apply the code on the recipient's account
curl -X POST https://whitebit.com/api/v4/main-account/codes/apply \
  -H "X-TXC-APIKEY: YOUR_API_KEY" \
  -H "X-TXC-PAYLOAD: YOUR_PAYLOAD" \
  -H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH",
    "passphrase": "mySecretPass1",
    "request": "/api/v4/main-account/codes/apply",
    "nonce": 2
  }'

{
  "message": "Code was successfully applied",
  "ticker": "ETH",
  "amount": "0.002",
  "external_id": "be08a482-5faf-11ed-9b6a-0242ac120002"
}

# Step 1: Create a WhiteBIT code.
# Request body for POST /api/v4/main-account/codes:
create_body = {
    "ticker": "ETH",
    "amount": "0.002",
    "passphrase": "mySecretPass1",
}
# The response returns the code string and an external_id.

# Step 2: Apply the code on the recipient's account.
# Request body for POST /api/v4/main-account/codes/apply:
apply_body = {
    "code": "WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH",  # from the create response
    "passphrase": "mySecretPass1",
}
# To send: add "request" and "nonce" to the body, serialize with compact
# separators (the server rejects spaced JSON), sign with HMAC-SHA512, and
# send with the X-TXC-APIKEY / X-TXC-PAYLOAD / X-TXC-SIGNATURE headers —
# implementation in the First API Call guide linked below.

First API Call documents the signing details (payload construction, nonce, and headers). For Go and PHP examples, see SDKs.

Error codes

Create endpoint error codes:

Code	Description
0	Fiat currencies available on the front-end only
1	Currency is not withdrawable
3	Amount is too small
5	Not enough balance
6	Amount is less than or equal to fee

For apply errors, the most common is “Incorrect code or passphrase” — verify the code string and passphrase are correct.

Regional restrictions

EEA users: USDT codes are blocked since December 30, 2024 (MiCA compliance). Tether has not obtained EU authorization. Use USDC or EURI as alternatives. See Regulatory Compliance for details.

Group

Use cases

Code lifecycle

API endpoints

Create parameters

Code example

Error codes

Regional restrictions

What’s next

Webhook Events

Convert

​Use cases

​Code lifecycle

​API endpoints

​Create parameters

​Code example

​Error codes

​Regional restrictions

​What’s next

Webhook Events

Convert

Use cases

Code lifecycle

API endpoints

Create parameters

Code example

Error codes

Regional restrictions

What’s next