Interact with 100+ cryptocurrency exchanges — fetch markets, order books, tickers, place orders, check balances, and more using the CCXT CLI.
---
name: ccxt
description: Interact with 100+ cryptocurrency exchanges — fetch markets, order books, tickers, place orders, check balances, and more using the CCXT CLI.
homepage: https://docs.ccxt.com
user-invocable: true
metadata: {"openclaw":{"emoji":"📊","requires":{"bins":["ccxt"]},"install":[{"id":"node","kind":"node","package":"ccxt-cli","bins":["ccxt"]}]}}
---
# CCXT — Cryptocurrency Exchange Trading
You have access to the `ccxt` CLI tool which lets you interact with 100+ cryptocurrency exchanges (Binance, Bybit, OKX, Kraken, Coinbase, and many more). You can fetch market data, place orders, check balances, and stream live data.
## Core Syntax
```bash
ccxt <exchange_id> <methodName> [args...] [options]
```
## Before Calling Any Method
If you're unsure about the required arguments for a method, run:
```bash
ccxt explain <methodName>
```
This will show you the required and optional arguments with descriptions.
## Available Options
| Flag | Purpose |
|------|---------|
| `--verbose` | Show raw request/response data |
| `--sandbox` | Use testnet/sandbox environment |
| `--raw` | Output clean JSON without formatting |
| `--swap` | Target swap/perpetuals account |
| `--future` | Target futures account |
| `--spot` | Target spot account |
| `--option` | Target options account |
| `--param key=value` | Pass extra exchange-specific params (repeatable) |
| `--no-keys` | Skip API key loading |
## Common Operations
### Market Data (Public — No API Keys Required)
**Fetch markets (list all trading pairs on an exchange):**
```bash
ccxt <exchange> fetchMarkets --raw
```
**Fetch a single ticker:**
```bash
ccxt <exchange> fetchTicker "BTC/USDT" --raw
```
**Fetch multiple tickers:**
```bash
ccxt <exchange> fetchTickers --raw
```
**Fetch order book:**
```bash
ccxt <exchange> fetchOrderBook "BTC/USDT" --raw
```
**Fetch OHLCV candles:**
```bash
ccxt <exchange> fetchOHLCV "BTC/USDT" 1h undefined 10 --raw
```
**Fetch recent trades:**
```bash
ccxt <exchange> fetchTrades "BTC/USDT" --raw
```
**Fetch exchange status:**
```bash
ccxt <exchange> fetchStatus --raw
```
**Fetch currencies:**
```bash
ccxt <exchange> fetchCurrencies --raw
```
### Trading (Private — Requires API Keys)
**Create an order:**
```bash
ccxt <exchange> createOrder "BTC/USDT" limit buy 0.001 50000 --raw
ccxt <exchange> createOrder "BTC/USDT" market buy 0.001 --raw
```
**Create order with extra params:**
```bash
ccxt <exchange> createOrder "BTC/USDT" limit buy 0.001 50000 --param stopPrice=49000 --raw
```
**Cancel an order:**
```bash
ccxt <exchange> cancelOrder "<order_id>" "BTC/USDT" --raw
```
**Fetch open orders:**
```bash
ccxt <exchange> fetchOpenOrders "BTC/USDT" --raw
```
**Fetch closed orders:**
```bash
ccxt <exchange> fetchClosedOrders "BTC/USDT" --raw
```
**Fetch a specific order:**
```bash
ccxt <exchange> fetchOrder "<order_id>" "BTC/USDT" --raw
```
### Account (Private — Requires API Keys)
**Fetch balance:**
```bash
ccxt <exchange> fetchBalance --raw
```
**Fetch balance for derivatives:**
```bash
ccxt <exchange> fetchBalance --swap --raw
```
**Fetch my trades:**
```bash
ccxt <exchange> fetchMyTrades "BTC/USDT" --raw
```
**Fetch positions (derivatives):**
```bash
ccxt <exchange> fetchPositions --swap --raw
```
**Fetch deposit address:**
```bash
ccxt <exchange> fetchDepositAddress "BTC" --raw
```
### Derivatives
**Fetch funding rate:**
```bash
ccxt <exchange> fetchFundingRate "BTC/USDT:USDT" --raw
```
**Fetch funding rate history:**
```bash
ccxt <exchange> fetchFundingRateHistory "BTC/USDT:USDT" --raw
```
**Fetch mark price / index price:**
```bash
ccxt <exchange> fetchMarkOHLCV "BTC/USDT:USDT" 1h --raw
ccxt <exchange> fetchIndexOHLCV "BTC/USDT:USDT" 1h --raw
```
## Important Rules
1. **Always quote symbols** that contain `/` or `:` — e.g., `"BTC/USDT"`, `"BTC/USDT:USDT"`.
2. **Use `undefined`** as a positional placeholder to skip optional arguments while providing later ones. For example: `ccxt binance fetchOHLCV "BTC/USDT" 1h undefined 10` skips `since` but provides `limit`.
3. **Use `--raw`** when you need to parse the output programmatically or when the user needs clean JSON.
4. **Use `--sandbox`** for testing with testnet environments. Always recommend sandbox mode when the user is experimenting with orders.
5. **ISO8601 datetimes** (e.g., `"2025-01-01T00:00:00Z"`) are auto-converted to milliseconds.
6. **API keys** must be configured via environment variables (e.g., `BINANCE_APIKEY`, `BINANCE_SECRET`) or the config file. If a private method fails due to missing credentials, instruct the user to set them up.
7. **Derivatives symbols** use the format `"BASE/QUOTE:SETTLE"` — e.g., `"BTC/USDT:USDT"` for USDT-margined perpetuals.
8. **Be careful with order methods** — always confirm amounts and prices with the user before executing `createOrder`. The CLI executes immediately with no confirmation prompt.
9. When the output is large (e.g., `fetchMarkets` returns hundreds of entries), consider piping through `| head` or filtering, or suggest the user narrows their query.
10. For the list of supported exchanges, you can check: `ccxt exchanges` or refer to https://docs.ccxt.com.
## Authentication Setup
Tell users to configure credentials in one of two ways:
**Option 1 — Environment variables:**
```bash
export BINANCE_APIKEY=your_api_key
export BINANCE_SECRET=your_secret
```
**Option 2 — Config file** (path shown in `ccxt --help`):
```json
{
"binance": {
"apiKey": "your_api_key",
"secret": "your_secret"
}
}
```
## Error Handling
- If you get an `AuthenticationError`, the API keys are missing or invalid.
- If you get an `ExchangeNotAvailable` or `NetworkError`, the exchange may be down or rate-limiting.
- If you get an `BadSymbol`, the trading pair doesn't exist on that exchange — use `fetchMarkets` to check available pairs.
- If you get an `InsufficientFunds`, the account doesn't have enough balance for the operation.
don't have the plugin yet? install it then click "run inline in claude" again.
restructured into implexa's 6-part format (intent, inputs, procedure with numbered steps, explicit decision points including auth failures and exchange downtime, output contract with JSON structure details, and outcome signal with verification steps), added edge cases like rate limits and insufficient funds, clarified api credential setup as inputs, documented exchange-specific env var naming, and preserved all original author content and command examples.
use the ccxt CLI to interact with 100+ cryptocurrency exchanges (Binance, Bybit, OKX, Kraken, Coinbase, etc.). fetch market data, place or cancel orders, check account balances, stream live data, and query derivatives positions. use this when you need real-time crypto market info or need to execute trades programmatically. public methods (markets, tickers, order books) work without auth; private methods (orders, balance, positions) require valid API credentials.
required:
ccxt CLI binary installed via npm install -g ccxt-cli (node.js 14+)binance, bybit, kraken, coinbase (full list: ccxt exchanges)fetchMarkets, createOrder, fetchBalancefor private methods (trading, balance, positions):
BINANCE_APIKEY environment variable (or exchange-specific equivalent like BYBIT_APIKEY, KRAKEN_APIKEY)BINANCE_SECRET environment variable (or exchange-specific equivalent like BYBIT_SECRET, KRAKEN_SECRET)BINANCE_UID or BINANCE_PASSWORD (check ccxt explain <methodName>)optional:
--sandbox flag to route to testnet (supported by most major exchanges)--raw flag for clean JSON output (recommended for programmatic parsing)--verbose flag to inspect raw HTTP requests/responses (debugging)--param key=value flags to pass exchange-specific optional params (repeatable)--spot, --swap, --future, --option (defaults to spot)input: desired exchange name (e.g. binance)
output: list of supported exchanges, or explanation of a specific method
run ccxt exchanges to see all 100+ supported exchanges.
run ccxt explain <methodName> to see required and optional arguments for any method, e.g. ccxt explain createOrder.
input: exchange id, symbol (quoted if contains / or :)
output: JSON object or array with market data
for single ticker:
ccxt <exchange> fetchTicker "BTC/USDT" --raw
for multiple tickers:
ccxt <exchange> fetchTickers --raw
for order book (bid/ask levels):
ccxt <exchange> fetchOrderBook "BTC/USDT" --raw
for OHLCV candles (open, high, low, close, volume):
ccxt <exchange> fetchOHLCV "BTC/USDT" 1h undefined 10 --raw
(here undefined skips the since param; 10 is limit)
for recent trades:
ccxt <exchange> fetchTrades "BTC/USDT" --raw
for all markets on the exchange:
ccxt <exchange> fetchMarkets --raw
for exchange status (uptime, maintenance):
ccxt <exchange> fetchStatus --raw
for supported currencies and network info:
ccxt <exchange> fetchCurrencies --raw
input: exchange API key and secret from your exchange account output: environment variables or config file
option A (environment variables, simplest):
export BINANCE_APIKEY=your_api_key_here
export BINANCE_SECRET=your_secret_here
(replace BINANCE_ with exchange name in uppercase, e.g. BYBIT_APIKEY, KRAKEN_APIKEY)
option B (config file):
locate config path with ccxt --help, typically ~/.ccxt/config.json or ./ccxt.config.json.
create or edit it:
{
"binance": {
"apiKey": "your_api_key",
"secret": "your_secret"
}
}
input: exchange id, optional account type flag (--spot, --swap, etc.)
output: JSON object with coin balances (free, used, total)
spot balance:
ccxt <exchange> fetchBalance --raw
derivatives (swap/margin) balance:
ccxt <exchange> fetchBalance --swap --raw
input: exchange id, symbol (quoted), order type (limit or market), side (buy or sell), amount, price (limit only)
output: order object with id, status, timestamp, filled amount, fees
limit order (specify price):
ccxt <exchange> createOrder "BTC/USDT" limit buy 0.001 50000 --raw
market order (buys/sells at current market price):
ccxt <exchange> createOrder "BTC/USDT" market buy 0.001 --raw
with exchange-specific params (e.g. stop price, post-only, reduce-only):
ccxt <exchange> createOrder "BTC/USDT" limit buy 0.001 50000 --param stopPrice=49000 --raw
input: exchange id, optional symbol, optional order id output: array of order objects with status, fills, fees
open orders for a symbol:
ccxt <exchange> fetchOpenOrders "BTC/USDT" --raw
closed orders for a symbol:
ccxt <exchange> fetchClosedOrders "BTC/USDT" --raw
specific order by id:
ccxt <exchange> fetchOrder "<order_id>" "BTC/USDT" --raw
your trade history for a symbol:
ccxt <exchange> fetchMyTrades "BTC/USDT" --raw
input: exchange id, order id, symbol (quoted) output: cancelled order object
ccxt <exchange> cancelOrder "<order_id>" "BTC/USDT" --raw
input: exchange id, symbol in format BASE/QUOTE:SETTLE (e.g. BTC/USDT:USDT), account type flag --swap
output: funding rates, positions, mark prices
funding rate (current):
ccxt <exchange> fetchFundingRate "BTC/USDT:USDT" --swap --raw
funding rate history:
ccxt <exchange> fetchFundingRateHistory "BTC/USDT:USDT" --swap --raw
open positions:
ccxt <exchange> fetchPositions --swap --raw
mark price OHLCV:
ccxt <exchange> fetchMarkOHLCV "BTC/USDT:USDT" 1h --swap --raw
index price OHLCV:
ccxt <exchange> fetchIndexOHLCV "BTC/USDT:USDT" 1h --swap --raw
input: exchange id, currency code (e.g. BTC, ETH, USDT)
output: deposit address (string) or withdrawal receipt (object)
fetch your deposit address for a coin:
ccxt <exchange> fetchDepositAddress "BTC" --raw
(withdrawal via withdrawal() method requires additional user id or account params; check ccxt explain withdrawal)
if using a public method (fetchMarkets, fetchTicker, fetchOrderBook, fetchTrades, etc.):
if using a private method (createOrder, fetchBalance, fetchOpenOrders, cancelOrder, fetchMyTrades, etc.):
EXCHANGE_APIKEY and EXCHANGE_SECRET env vars are set or config file exists.AuthenticationError, stop and prompt user to set up credentials.if the user is testing or experimenting with order placement:
--sandbox flag. check if the target exchange supports sandbox (most major ones do). if not, warn user that orders will be live.if the output is large (e.g., fetchMarkets on Binance returns 1000+ entries):
| head -20 to preview or suggest user filter by symbol using fetchTicker or fetchOrderBook instead.if a method requires a symbol and the user is unsure which symbols are tradeable:
ccxt <exchange> fetchMarkets --raw to list all, or run ccxt <exchange> fetchTicker "BTC/USDT" --raw to test a specific pair.if the user gets ExchangeNotAvailable or NetworkError:
if the user gets BadSymbol error:
BTC/USDT not BTCUSDT) and run fetchMarkets to find the correct symbol name.if the user gets InsufficientFunds error when placing an order:
fetchBalance --raw to check available balance and adjust order amount.if using derivatives (perpetuals, swaps, futures):
--swap, --future, or --option flags to target the correct account.BASE/QUOTE:SETTLE, e.g. BTC/USDT:USDT for USDT-margined perps.if passing complex params (e.g., stopPrice, postOnly, timeInForce):
--param key=value syntax (repeatable for multiple params).all methods with --raw flag output valid JSON (object or array of objects).
each response has exchange-specific keys, but common ones include:
id: unique identifier (order id, trade id, etc.)timestamp: unix millisecondsdatetime: ISO8601 stringstatus: e.g. open, closed, canceledsymbol: trading pair, e.g. BTC/USDTprice, amount, cost: numeric valuesfilled, remaining: for ordersfee: object with currency, cost, ratemarket data responses (fetchMarkets, fetchTickers, fetchOrderBook) contain standardized CCXT objects with bid/ask levels, last trade price, 24h volume, etc.
account responses (fetchBalance) contain nested objects: { BTC: { free: 1.5, used: 0.5, total: 2.0 }, ... }
no data is written to disk unless user explicitly pipes output to a file.
the command exits with status code 0 on success. JSON is printed to stdout.
if the user sees valid JSON in the terminal, the command worked. if you're piping to a file, check that the file exists and contains valid JSON:
ccxt binance fetchBalance --raw > balance.json
cat balance.json # should show JSON, not errors
if the user placed an order with createOrder, the returned object will include an id field. the order is live on the exchange immediately. confirm the status field is not rejected or canceled. if the user needs confirmation, they can call fetchOrder <id> <symbol> to verify.
if the user withdrew or deposited funds, the fetchDepositAddress command returns a wallet address; the withdrawal() method (if successful) returns a txid. check the exchange's withdrawal/deposit history page to verify the transaction.