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

# CLI

> Trade, manage accounts, and query market data from the terminal using the WhiteBIT CLI. Built for scripting, CI/CD pipelines, and automated workflows.

The WhiteBIT CLI provides 110+ commands covering the full WhiteBIT API surface — market data, spot trading, collateral trading, lending, sub-accounts, deposits, and withdrawals — directly from the terminal.

## Prerequisites

* A WhiteBIT account with an API key for authenticated commands — see [Authentication](/api-reference/authentication)

Public market data commands (`market`, `server`) require no account or API key.

| Feature | Detail |
| - | - |
| **110+ commands** | Full API surface: spot, collateral, lending, sub-accounts, deposits, withdrawals |
| **Multi-profile** | Named profiles in `~/.whitebit/config.toml`, switch with `--profile` |
| **`--dry-run` mode** | Preview the exact request payload before sending |
| **JSON output** | `--json` flag on every command — pipe into `jq` or any automation tool |
| **Shell completion** | Tab-completion for Bash, Zsh, and Fish |
| **Cross-platform** | macOS (ARM + x64), Linux, and Windows |

## Install the CLI

<Tabs>
  <Tab title="Homebrew">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    brew install whitebit-exchange/tap/whitebit
    ```
  </Tab>

  <Tab title="npm">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install -g whitebit-cli
    ```
  </Tab>

  <Tab title="From source">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    git clone https://github.com/whitebit-exchange/whitebit-cli
    cd whitebit-cli
    bun install
    bun src/cli.ts --help
    ```

    Requires [Bun](https://bun.sh) ≥ 1.0.0.
  </Tab>
</Tabs>

## Quick start

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 1. Set credentials (required for account and trading commands)
export WHITEBIT_API_KEY="YOUR_API_KEY"
export WHITEBIT_API_SECRET="YOUR_SECRET"

# 2. Verify setup — no authentication required
whitebit market info

# 3. Check the spot balance
whitebit spot balance

# 4. Place a limit order
whitebit spot limit-order --market BTC_USDT --side buy --amount 0.001 --price 50000
```

## Authentication

Credentials are resolved in priority order (highest first):

| Method | Best for | Persistence | Security note |
| - | - | - | - |
| CLI flags (`--api-key`, `--api-secret`) | Quick testing | None | Visible in process list |
| Environment variables | CI/CD, Docker, one-off scripts | Per-session | Depends on environment |
| Config file (`~/.whitebit/config.toml`) | Daily use, multiple profiles | Permanent | Set `chmod 600` on the file |

<Warning>
  Store API keys securely. Do not commit `~/.whitebit/config.toml` to version control. Avoid `--api-key` flags in production scripts — the value is visible in the process list.
</Warning>

### Config file

Create `~/.whitebit/config.toml` with one or more named profiles:

```toml theme={"theme":{"light":"github-light","dark":"github-dark"}}
[default]
api_key = "YOUR_API_KEY"
api_secret = "YOUR_SECRET"
default_format = "table"  # or "json"

[work]
api_key = "WORK_API_KEY"
api_secret = "WORK_SECRET"
```

Switch profiles with `--profile`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
whitebit spot balance --profile work
```

## Commands

| Module | Commands | Auth | Description |
| - | - | :-: | - |
| `server` | 3 | No | Server ping, time, and maintenance status |
| `market` | 11 | No | Markets, order book, trades, depth, funding rates, assets |
| `spot` | 14 | Yes | Limit, market, stop orders; cancel, modify, kill-switch |
| `collateral` | 16 | Yes | Margin: leverage, positions, OCO, conditional orders |
| `account` | 7 | Yes | Main balance, history, deposit address, withdraw, transfer, fees |
| `convert` | 3 | Yes | Estimate and execute asset conversions |
| `lending` | 11 | Yes | Fixed and flexible staking, interest history |
| `mining` | 6 | Yes | Rewards, hashrate, worker stats, payout destination |
| `sub-account` | 10 | Yes | Sub-account management, balances, transfers |
| `config` | 2 | No | Manage CLI credentials and profiles |

## Examples

### Market data

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# List all available markets
whitebit market info

# Get 24h pricing and volume for all markets
whitebit market activity

# Get order book
whitebit market orderbook --market BTC_USDT

# Get recent trades
whitebit market trades --market BTC_USDT
```

### Account and balance

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Check spot balance
whitebit spot balance

# Check main account balance
whitebit account main-balance

# Transfer 100 USDT from main to spot
whitebit account transfer --from main --to spot --ticker USDT --amount 100
```

### Spot trading

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Place a limit buy order
whitebit spot limit-order --market BTC_USDT --side buy --amount 0.001 --price 50000

# Place a market sell order
whitebit spot market-order --market BTC_USDT --side sell --amount 0.001

# List open orders
whitebit spot active-orders --market BTC_USDT

# Cancel an order
whitebit spot cancel --market BTC_USDT --order-id ORDER_ID
```

### JSON output and scripting

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Output as JSON
whitebit spot balance --json

# Pipe into jq
whitebit spot balance --json | jq '.[] | {currency: .currency, balance: .available}'

# Dry run — preview the request without sending
whitebit spot limit-order --market BTC_USDT --side buy --amount 0.001 --price 50000 --dry-run
```

## Shell completion

<Tabs>
  <Tab title="Bash">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    whitebit completion --shell bash >> ~/.bash_completion
    ```

    To load automatically, add `source ~/.bash_completion` to `~/.bashrc`.
  </Tab>

  <Tab title="Zsh">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    mkdir -p ~/.zfunc
    whitebit completion --shell zsh > ~/.zfunc/_whitebit
    ```

    Add `fpath=(~/.zfunc $fpath)` and `autoload -Uz compinit && compinit` to `~/.zshrc`.
  </Tab>

  <Tab title="Fish">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    whitebit completion --shell fish > ~/.config/fish/completions/whitebit.fish
    ```
  </Tab>
</Tabs>

## Global options

| Option | Description |
| - | - |
| `--profile <name>` | Use a named config profile (default: `default`) |
| `--api-key <key>` | Override the API key for this command |
| `--api-secret <secret>` | Override the API secret for this command |
| `--api-url <url>` | Override the API base URL |
| `--format <table\|json>` | Output format |
| `--json` | Shorthand for `--format json` |
| `--verbose`, `-V` | Show raw API responses |
| `--dry-run` | Show the request payload without sending |

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success |
| `1` | General error |
| `2` | Authentication or credential error |
| `3` | Network error |
| `4` | Usage or bad arguments |
| `5` | Rate limit (HTTP 429) |

## Security best practices

* Never commit credentials to version control.
* Use environment variables for CI/CD pipelines.
* Set restrictive file permissions: `chmod 600 ~/.whitebit/config.toml`.
* Use API key restrictions in the WhiteBIT dashboard — IP whitelist and read-only scope when appropriate.
* Avoid `--api-key` and `--api-secret` flags in production scripts — values are visible in the process list.

## What's next

* [MCP server](/guides/mcp-server) — Use natural language to trade and query data via an AI client
* [AI tools FAQ](/guides/ai-faq) — Common questions about the CLI, API keys, and automation
* [AI tools overview](/guides/use-with-ai) — All WhiteBIT AI tools in one place
* [Authentication](/api-reference/authentication) — How to generate and manage WhiteBIT API keys
* [API Reference Overview](/api-reference/overview) — Full REST API endpoint listing


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