CLI - WhiteBIT

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

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

Homebrew
npm
From source

brew install whitebit-exchange/tap/whitebit

npm install -g whitebit-cli

git clone https://github.com/whitebit-exchange/whitebit-cli
cd whitebit-cli
bun install
bun src/cli.ts --help

Requires Bun ≥ 1.0.0.

Quick start

# 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

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.

Config file

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

[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:

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

# 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

# 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

# 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

# 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

Bash
Zsh
Fish

whitebit completion --shell bash >> ~/.bash_completion

To load automatically, add source ~/.bash_completion to ~/.bashrc.

mkdir -p ~/.zfunc
whitebit completion --shell zsh > ~/.zfunc/_whitebit

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

whitebit completion --shell fish > ~/.config/fish/completions/whitebit.fish

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 — Use natural language to trade and query data via an AI client
AI tools FAQ — Common questions about the CLI, API keys, and automation
AI tools overview — All WhiteBIT AI tools in one place
Authentication — How to generate and manage WhiteBIT API keys
API Reference Overview — Full REST API endpoint listing

​Prerequisites

​Install the CLI

​Quick start

​Authentication

​Config file

​Commands

​Examples

​Market data

​Account and balance

​Spot trading

​JSON output and scripting

​Shell completion

​Global options

​Exit codes

​Security best practices

​What’s next

Prerequisites

Install the CLI

Quick start

Authentication

Config file

Commands

Examples

Market data

Account and balance

Spot trading

JSON output and scripting

Shell completion

Global options

Exit codes

Security best practices

What’s next