/ccxt-cli

name: ccxt-cli
description: CCXT command-line interface (ccxt-cli) for interacting with 100+ cryptocurrency exchanges directly from the terminal — no code required. Covers installing the CLI, calling any unified CCXT method (fetchTicker, fetchOHLCV, createOrder, fetchBalance), passing arguments and exchange-specific params, authenticating with API keys, sandbox/testnet mode, streaming live tickers and orderbooks over WebSocket, plotting OHLCV charts, and scripting with raw JSON output. Use when the user wants to query an exchange, test API credentials, place or inspect orders, or debug exchange requests from the command line or in shell scripts.

CCXT CLI

The CCXT CLI (`ccxt-cli` on npm) exposes the entire unified CCXT API as a terminal command. Anything you can call in code — `fetchTicker`, `fetchOHLCV`, `createOrder`, `fetchBalance`, `withdraw`, exchange-specific implicit methods — you can call as:

ccxt <exchangeId> <methodName> [args...] [options]

It supports 100+ exchanges, REST and WebSocket, public and private endpoints, live terminal dashboards, and interactive OHLCV charts.

Installation

npm install -g ccxt-cli     # installs the `ccxt` command
ccxt --help

One-off use without installing (note `-p ccxt-cli` — the package name differs from the binary name):

npx -y -p ccxt-cli ccxt kraken fetchTicker BTC/USD

From a clone of the CCXT repository (contributor mode — uses the local source tree instead of the published package):

npm run cli.ts -- kraken fetchTicker BTC/USD    # runs cli/ts/cli.ts against local ts/

Quick start

# Public data — no API keys needed
ccxt kraken fetchTicker BTC/USD
ccxt kraken fetchOrderBook ETH/BTC
ccxt bybit fetchOHLCV BTC/USDT 15m
ccxt okx fetchTrades BTC/USDT

# Private data — needs API keys (see Authentication)
ccxt kraken fetchBalance
ccxt binance fetchOpenOrders BTC/USDT

# Place an order (start with --sandbox and small amounts!)
ccxt binance createOrder BTC/USDT limit buy 0.001 60000 --sandbox

Every run prints the CCXT version, the resolved call (e.g. `kraken.fetchTicker ("BTC/USD")`), the result, and timing. Use `--raw` to suppress everything except the JSON result.

Discovering methods and arguments

ccxt --help                 # all options, commands, and the config path for your OS
ccxt methods kraken         # every method the exchange supports (its `has` capabilities)
ccxt explain createOrder    # required/optional arguments for any unified method
ccxt history                # your previously executed commands

`ccxt explain <method>` output shows the argument order you must follow:

Method: createOrder
Usage:
  binance createOrder <symbol> <type> <side> <amount> [price] [params]
Arguments:
  - symbol       (required) — Market symbol e.g., BTC/USDT
  - type         (required) — e.g., limit or market
  - side         (required) — order side e.g., buy or sell
  - amount       (required)
  - price        (optional) — Price per unit of asset e.g., 26000.50
  - params       (optional) — Extra parameters for the exchange

Argument rules (important)

Arguments are positional and must follow the method's signature order. The CLI auto-converts each argument:

| You type | The method receives | |---|---| | `BTC/USDT` | string `'BTC/USDT'` | | `0.001`, `100` | number | | `undefined` | `undefined` (placeholder to skip an optional arg — the call echo displays it as `null`, which is expected) | | `true` / `false` / `null` | boolean / null | | `"2025-05-01T01:23:45Z"` | milliseconds timestamp (ISO8601 datetimes auto-convert; date-only strings like `2025-05-01` do NOT — include the time part) | | `'{"recvWindow":5000}'` | object (JSON must be shell-quoted) | | `'["BTC/USDT","ETH/USDT"]'` | array (shell-quoted) |

**Rule 1 — pad skipped optionals with `undefined`.** To pass `limit` without `since`:

ccxt binance fetchOHLCV BTC/USDT 1h undefined 10    # since=undefined, limit=10

**Rule 2 — `--param key=value` appends to the trailing `params` object.** Repeat it for multiple keys. Values are coerced the same way (`true`, `false`, `null`, numbers, strings):

ccxt binance createOrder BTC/USDT market buy 0.01 undefined --param test=true --param clientOrderId=myOrder

**Rule 3 — when using `--param`, explicitly fill ALL earlier optional positionals with `undefined`.** If you leave gaps, the CLI mis-assigns arguments (a known quirk — the params object can end up in the wrong position). Correct:

ccxt bybit fetchOHLCV BTC/USDT 15m undefined undefined --param until=1722161166530   # ✅
ccxt bybit fetchOHLCV BTC/USDT --param until=1722161166530                           # ❌ args get scrambled

Authentication

Private methods (`fetchBalance`, `createOrder`, `fetchMyTrades`, ...) need credentials. Three sources:

1. Environment variables

Pattern: `<EXCHANGEID>_<CREDENTIAL>` upper-cased. The credential names come from each exchange's `requiredCredentials` (`apiKey`, `secret`, `password`, `uid`, `walletAddress`, `privateKey`, ...):

export BINANCE_APIKEY=your_api_key
export BINANCE_SECRET=your_secret
ccxt binance fetchBalance

# okx also needs a passphrase:
export OKX_APIKEY=... OKX_SECRET=... OKX_PASSWORD=...

Pass `--no-keys` to ignore detected credentials and force unauthenticated calls.

2. Config file (persistent)

The CLI keeps a config at `$CACHE/ccxt-cli/config.json`, keyed by exchange id. `ccxt --help` prints the exact path for your OS:

• macOS: `~/Library/Caches/ccxt-cli/config.json`
• Linux: `~/.cache/ccxt-cli/config.json` (or `$XDG_CACHE_HOME/ccxt-cli/`)
• Windows: `%LOCALAPPDATA%\ccxt-cli\cache\config.json`

{
  "binance": {
    "apiKey": "your apiKey here",
    "secret": "your secret here",
    "options": { "defaultType": "swap" }
  },
  "okx": { "apiKey": "...", "secret": "...", "password": "..." }
}

Any key in the exchange object is set as a property on the exchange instance — s