> ## 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.

# API Reference

> WhiteBIT REST API overview — base URL, authentication, quickstart examples, rate limits, and links to all endpoint groups.

## Base URL

All REST API endpoints are available at:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
https://whitebit.com/api/v4/{endpoint}
```

* **Public endpoints** use the `GET` method and accept parameters as query strings.
* **Private endpoints** use the `POST` method and accept parameters as JSON in the request body.
* All endpoints return time in Unix-time format and respond with JSON.

***

## Quickstart

### Prerequisites

* A WhiteBIT account ([Sign up](https://whitebit.com/auth))
* An API key with appropriate permissions ([API Settings](https://whitebit.com/settings/api))
* A programming language or HTTP client (cURL, Python, JavaScript, or similar)

### Step 1: First public API call

The [Server Status](/api-reference/market-data/server-status) endpoint returns the API life-state. No authentication is required.

**Request:**

<Tabs>
  <Tab title="cURL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X GET "https://whitebit.com/api/v4/public/ping"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    import requests

    response = requests.get("https://whitebit.com/api/v4/public/ping")
    print(response.json())
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
    const response = await fetch("https://whitebit.com/api/v4/public/ping");
    const data = await response.json();
    console.log(data);
    ```
  </Tab>
</Tabs>

**Expected response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
["pong"]
```

A response of `["pong"]` confirms the API is operational.

### Step 2: Authentication setup

Private endpoints require HMAC-SHA512 signed requests. See the [Authentication](/api-reference/authentication) guide for the full signing process.

WhiteBIT provides the [API Quick Start Helper](https://github.com/whitebit-exchange/api-quickstart) with examples in Python, PHP, Node.js, Go, JavaScript, Kotlin, .NET, Ruby, C++, and Rust.

**Required headers for private endpoints:**

| Header            | Value                               |
| ----------------- | ----------------------------------- |
| `Content-type`    | `application/json`                  |
| `X-TXC-APIKEY`    | The public API key                  |
| `X-TXC-PAYLOAD`   | Base64-encoded request body         |
| `X-TXC-SIGNATURE` | HMAC-SHA512 signature (hex encoded) |

### Step 3: First authenticated API call

The [Main Balance](/api-reference/account-wallet/main-balance) endpoint retrieves the main account balance. The request body must include `request` (the endpoint path) and `nonce` (unique identifier).

**Request body:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "request": "/api/v4/main-account/balance",
  "nonce": 1594297865000
}
```

**Example with cURL** (replace `YOUR_API_KEY` and `YOUR_SIGNATURE` with the signed payload):

<Tabs>
  <Tab title="cURL">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://whitebit.com/api/v4/main-account/balance" \
      -H "Content-type: application/json" \
      -H "X-TXC-APIKEY: YOUR_API_KEY" \
      -H "X-TXC-PAYLOAD: BASE64_ENCODED_PAYLOAD" \
      -H "X-TXC-SIGNATURE: YOUR_SIGNATURE" \
      -d '{"request":"/api/v4/main-account/balance","nonce":1594297865000}'
    ```
  </Tab>

  <Tab title="Python (with helper)">
    ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    # Use the API Quick Start Helper: https://github.com/whitebit-exchange/api-quickstart
    from whitebit import Whitebit

    wb = Whitebit(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")
    balance = wb.main_account_balance()
    print(balance)
    ```
  </Tab>
</Tabs>

**Expected response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "BTC": { "main_balance": "0" },
  "USDT": { "main_balance": "100.50" }
}
```

The response contains balance data for each asset. Omitted assets have a zero balance.

***

## Rate Limits

For complete rate limits, error codes, and best practices, see [Rate Limits & Error Codes](/api-reference/rate-limits).

## Error Format

All V4 endpoints return errors as JSON. The format differs slightly between public and private APIs:

**Public endpoints:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "success": false,
  "message": "ERROR MESSAGE",
  "params": []
}
```

**Private endpoints:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": 0,
  "message": "MESSAGE",
  "errors": {
    "PARAM1": ["MESSAGE"],
    "PARAM2": ["MESSAGE"]
  }
}
```

## HTTP Status Codes

For retry strategies, authentication errors, and best practices, see
[Rate Limits & Error Codes](/api-reference/rate-limits).

***

## Endpoint Groups

<CardGroup cols={2}>
  <Card title="Market Data" icon="chart-bar" href="/api-reference/market-data/overview">
    Public market info, orderbook, trades, fees, server status, and more. No authentication required. See [Markets & Trading Pairs](/concepts/markets) for pair notation.
  </Card>

  <Card title="Spot Trading" icon="arrow-right-arrow-left" href="/api-reference/spot-trading/overview">
    Place and manage spot orders, query execution history, and control kill-switch timers.
  </Card>

  <Card title="Collateral Trading" icon="scale-balanced" href="/api-reference/collateral-trading/overview">
    Manage collateral positions, leverage, hedge mode, and collateral order types (limit, market, OCO, OTO).
  </Card>

  <Card title="Convert" icon="rotate" href="/api-reference/convert/convert-estimate">
    Estimate, confirm, and review currency conversion operations.
  </Card>

  <Card title="Account & Wallet" icon="wallet" href="/api-reference/account-wallet/overview">
    Main balance, deposits, withdrawals, transfers, codes, crypto lending, and fees. See [Balances & Transfers](/concepts/balances) for account types.
  </Card>

  <Card title="Mining Pool" icon="pickaxe" href="/api-reference/mining-pool/pool-overview">
    Monitor mining operations, manage payouts, track worker performance, and create watcher links.
  </Card>

  <Card title="Sub-Accounts" icon="users" href="/api-reference/sub-accounts/overview">
    Create and manage sub-accounts, balances, transfers, and API keys.
  </Card>

  <Card title="OAuth" icon="key" href="/api-reference/oauth/usage/overview">
    Third-party authorization: token exchange, refresh, OAuth API keys, and account endpoints.
  </Card>
</CardGroup>

## What's next

* [Authentication](/api-reference/authentication) — Full signing process and common errors
* [Rate Limits & Error Codes](/api-reference/rate-limits) — Per-endpoint limits, error formats, and troubleshooting
* [Market Data](/api-reference/market-data/overview) — Public endpoints for orderbook, trades, and market info
* [Spot Trading](/api-reference/spot-trading/overview) — Place and manage orders
* [WebSocket API](/websocket/overview) — Real-time market data and account streams
* [API Quick Start Helper](https://github.com/whitebit-exchange/api-quickstart) — Multi-language SDK for authentication and requests