> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whitebit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WhiteBIT Codes

> Create and apply fee-free digital vouchers to transfer crypto between WhiteBIT accounts.

Base URL

:

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.

**1. Create a code**

Send a `POST` request to [`/api/v4/main-account/codes`](/api-reference/account-wallet/create-code) 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](/concepts/balances). The response returns a `code` string (format: `WB{uuid}{TICKER}`, e.g., `WBe11f4fce-2a53-4edc-b195-66b693bd77e3ETH`) and an `external_id`.

**2. Share the code**

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

**3. Apply the code**

The recipient calls [`POST /api/v4/main-account/codes/apply`](/api-reference/account-wallet/apply-code) with the `code` string and `passphrase` (if set). Funds are credited to the recipient's [Main balance](/concepts/balances). A `code.apply` [webhook event](/platform/webhook) fires on the creator's account.

## API endpoints

WhiteBIT Codes uses 4 authenticated endpoints. All operate on the [Main balance](/concepts/balances).

| Endpoint | Purpose | Rate limit |
| - | - | - |
| [`POST /api/v4/main-account/codes`](/api-reference/account-wallet/create-code) | Create a new code | 1,000 req / 10 sec |
| [`POST /api/v4/main-account/codes/apply`](/api-reference/account-wallet/apply-code) | Apply (redeem) a code | 60 req / 1 sec |
| [`POST /api/v4/main-account/codes/my`](/api-reference/account-wallet/get-my-codes) | List codes created by the account | 1,000 req / 10 sec |
| [`POST /api/v4/main-account/codes/history`](/api-reference/account-wallet/get-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**

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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
  }'
```

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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
  }'
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "message": "Code was successfully applied",
  "ticker": "ETH",
  "amount": "0.002",
  "external_id": "be08a482-5faf-11ed-9b6a-0242ac120002"
}
```

**Python**

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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](/guides/first-api-call) documents the signing details (payload construction, nonce, and headers).

For Go and PHP examples, see [SDKs](/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 |

> [!NOTE]
>
> For apply errors, the most common is "Incorrect code or passphrase" — verify the code string and passphrase are correct.

## Regional restrictions

> [!WARNING]
>
> 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](/institutional/compliance) for details.

## What's next

> **[Webhook Events](/platform/webhook)**
>
> Receive real-time notifications when codes are applied.

> **[Convert](/platform/convert)**
>
> Instantly convert between currencies at a quoted rate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.