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
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
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"
--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
whitebit completion --shell bash >> ~/.bash_completion
source ~/.bash_completion to ~/.bashrc.mkdir -p ~/.zfunc
whitebit completion --shell zsh > ~/.zfunc/_whitebit
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
