@2oolkit/backpack-cli

backpack-cli

Trade spot and perpetuals on Backpack Exchange from your terminal or AI agent.

One package, two interfaces:

Interface	Command	Use Case
CLI	backpack	Terminal trading, scripting, automation
MCP Server	backpack-mcp	AI agents (Claude, Cursor, Windsurf, etc.)

Spot, perpetuals, borrow/lend, and full account management.

Installation

npm install -g @2oolkit/backpack-cli

This installs both backpack (CLI) and backpack-mcp (MCP server).

Prerequisites

• Node.js >= 20
• A Backpack Exchange account with API keys
• Your API key and API secret (ED25519 key pair from Backpack settings)

CLI Usage

Quick Start

# 1. Set API credentials
backpack config set --api-key <your-key> --api-secret <your-secret>

# 2. Check a price (no auth needed)
backpack market ticker -s SOL_USDC

# 3. Place a limit buy
backpack order create -s SOL_USDC --side Bid --type Limit -q 1 -p 100

# 4. View open orders
backpack order list

Configuration

# Set credentials
backpack config set --api-key <base64-key> --api-secret <base64-secret>

# View current config (secrets masked)
backpack config get

# Clear all credentials
backpack config clear

Config is saved to ~/.backpack-cli/config.json.

Command Reference

Market Data (no auth required)

backpack market assets                                  # List all assets
backpack market list                                    # List all markets
backpack market list -t PERP                            # List perpetual markets only
backpack market info -s SOL_USDC                        # Market details
backpack market ticker -s SOL_USDC                      # Price, volume, 24h change
backpack market tickers                                 # All tickers
backpack market depth -s SOL_USDC                       # Order book
backpack market depth -s SOL_USDC -l 50                 # Order book (50 levels)
backpack market klines -s SOL_USDC -i 1h --start <ts>   # Candlestick data (time range)
backpack market klines -s SOL_USDC -i 1h --count 2000   # 2000 most recent 1h bars (single request)
backpack market klines -s SOL_USDC -i 1h --count 5000 --paginate  # 5000 bars (auto-windowed)
backpack market mark-prices                             # Mark prices
backpack market open-interest                           # Open interest
backpack market funding-rates -s SOL_USDC_PERP          # Historical funding rates
backpack market trades -s SOL_USDC                      # Recent trades
backpack market trade-history -s SOL_USDC               # Trade history

Candles / klines

Backpack's GET /api/v1/klines endpoint is time-range based (no count/limit param) and returns at most 2000 bars per request — wider windows are rejected by the server (Time range between startTime and endTime is too long).

• Intervals: 1s, 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 8h, 12h, 1d, 3d, 1w, 1month
• --count <n>: fetch the N most recent bars without computing timestamps (sets endTime = now, startTime = now - n * intervalSeconds). For n <= 2000 this is a single request.
• --paginate: to fetch more than 2000 bars, add --paginate. The CLI windows the time range into consecutive <= 2000 * intervalSeconds chunks (next window starts where the previous ended), then dedupes by candle start time and sorts ascending. The result is capped to the requested --count.
• Requesting --count > 2000 (or a --start window wider than 2000 bars) without --paginate fails fast with guidance instead of leaking a raw server error.
• --start/--end (unix seconds) still work for explicit time ranges; combine with --paginate for large ranges.

backpack market klines -s SOL_USDC -i 1h --count 2000              # 2000 bars, single request (max)
backpack market klines -s SOL_USDC -i 1h --count 5000 --paginate   # 5000 bars via windowing
backpack market klines -s SOL_USDC -i 1m --start 1700000000 --end 1700100000  # explicit range

System (no auth required)

backpack system status                                  # Exchange status
backpack system ping                                    # Connectivity check
backpack system time                                    # Server time
backpack system wallets                                 # Exchange wallet addresses

Orders (auth required)

# Place orders
backpack order create -s SOL_USDC --side Bid --type Limit -q 1 -p 100       # Limit buy
backpack order create -s SOL_USDC --side Ask --type Limit -q 1 -p 200       # Limit sell
backpack order create -s SOL_USDC --side Bid --type Market -q 1             # Market buy
backpack order create -s SOL_USDC --side Bid --type PostOnly -q 1 -p 100    # Post-only
backpack order create -s SOL_USDC --side Ask --type Limit -q 1 -p 200 --reduce-only  # Reduce-only

# Manage orders
backpack order list                                     # Open orders
backpack order list -s SOL_USDC                         # Open orders for symbol
backpack order get --order-id <id>                      # Order details
backpack order cancel --order-id <id> -s SOL_USDC       # Cancel one
backpack order cancel-all -s SOL_USDC                   # Cancel all for symbol

# History
backpack order history                                  # Order history
backpack order fills                                    # Fill history
backpack order fills -s SOL_USDC --from <ts> --to <ts>  # Fills with filters

Order create options:

Option	Required	Description
-s, --symbol <symbol>	Yes	Market symbol (e.g., SOL_USDC)
--side <side>	Yes	Bid (buy) or Ask (sell)
--type <orderType>	Yes	Limit, Market, PostOnly, FillOrKill, ImmediateOrCancel
-q, --quantity <qty>	Yes	Order quantity
-p, --price <price>	Limit	Limit price
--tif <timeInForce>	No	GTC, IOC, FOK, PostOnly
--client-id <id>	No	Client order ID
--reduce-only	No	Reduce only
--trigger-price <price>	No	Trigger price (stop/conditional)
--take-profit-price <price>	No	Take profit trigger price
--take-profit-limit-price <price>	No	Take profit limit price
--stop-loss-price <price>	No	Stop loss trigger price
--stop-loss-limit-price <price>	No	Stop loss limit price

Positions (auth required)

backpack position list                                  # All open positions
backpack position list -s SOL_USDC_PERP                 # Filter by symbol
backpack position get -s SOL_USDC_PERP                  # Single position
backpack position history                               # Position history

Account (auth required)

backpack account info                                   # Account info (fees, limits)
backpack account balances                               # Token balances
backpack account collateral                             # Collateral info
backpack account max-order -s SOL_USDC --side Bid       # Max order quantity
backpack account max-withdrawal -s SOL                  # Max withdrawal
backpack account max-borrow -s SOL                      # Max borrow
backpack account update --auto-lend true                # Update settings

Capital (auth required)

backpack capital deposits                               # Deposit history
backpack capital deposit-address -s SOL                  # Get deposit address
backpack capital withdrawals                            # Withdrawal history
backpack capital withdraw -s SOL -q 1 -a <address> -b Solana  # Withdraw

Funding

backpack funding rates -s SOL_USDC_PERP                 # Funding rates (public)
backpack funding history -s SOL_USDC_PERP               # Payment history (auth)

Borrow / Lend

# Public
backpack borrow markets                                 # Borrow/lend markets
backpack borrow markets-history -i 1d                   # Market history
backpack borrow apy                                     # Current APY rates

# Authenticated
backpack borrow positions                               # Your borrow/lend positions
backpack borrow execute -s SOL --side Lend -q 10        # Lend SOL
backpack borrow execute -s USDC --side Borrow -q 100    # Borrow USDC
backpack borrow history                                 # Borrow/lend history
backpack borrow interest-history                        # Interest payments

Output Formats

All commands support -f json (default) or -f table:

backpack market ticker -s SOL_USDC -f table
backpack order list -f json | jq '.[].orderId'

MCP Server

The MCP (Model Context Protocol) server exposes all Backpack Exchange functionality as tools for AI agents. Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

Setup for Claude Code

claude mcp add backpack-mcp -- backpack-mcp

Setup for Claude Desktop / Cursor / Windsurf

Add to your MCP config file:

{
  "mcpServers": {
    "backpack": {
      "command": "backpack-mcp"
    }
  }
}

Or without global install:

{
  "mcpServers": {
    "backpack": {
      "command": "npx",
      "args": ["-y", "-p", "@2oolkit/backpack-cli", "backpack-mcp"]
    }
  }
}

Setting Credentials via Environment Variables

Instead of running backpack config set, you can pass API credentials directly through environment variables in your .mcp.json config. This is useful when you want per-project credentials or don't want to store keys in a shared config file.

{
  "mcpServers": {
    "backpack": {
      "command": "backpack-mcp",
      "env": {
        "BACKPACK_API_KEY": "<your-base64-api-key>",
        "BACKPACK_SECRET_KEY": "<your-base64-api-secret>"
      }
    }
  }
}

With npx:

{
  "mcpServers": {
    "backpack": {
      "command": "npx",
      "args": ["-y", "-p", "@2oolkit/backpack-cli", "backpack-mcp"],
      "env": {
        "BACKPACK_API_KEY": "<your-base64-api-key>",
        "BACKPACK_SECRET_KEY": "<your-base64-api-secret>"
      }
    }
  }
}

Environment variables take priority over the config file (~/.backpack-cli/config.json). You can also set them in your shell:

export BACKPACK_API_KEY=<your-base64-api-key>
export BACKPACK_SECRET_KEY=<your-base64-api-secret>

Available Tools (46)

Category	Tools	Auth
Auth	auth_config_set, auth_config_get, auth_config_clear	—
Market	get_assets, get_markets, get_market, get_ticker, get_tickers, get_depth, get_klines, get_mark_prices, get_open_interest, get_funding_rates, get_recent_trades, get_trade_history, get_system_status, get_server_time	No
Account	get_account, update_account, get_balances, get_collateral, get_max_order_quantity, get_max_withdrawal_quantity, get_max_borrow_quantity	Yes
Orders	create_order, get_order, list_open_orders, cancel_order, cancel_all_orders, get_order_history, get_fill_history	Yes
Positions	list_positions, get_position, get_position_history	Yes
Capital	get_deposits, get_deposit_address, get_withdrawals, withdraw	Yes
Funding	get_funding_rates_public, get_funding_payment_history	Yes
Borrow	get_borrow_lend_markets, get_borrow_lend_apy, get_borrow_lend_positions, execute_borrow_lend, get_borrow_history, get_interest_history	Yes

MCP Prerequisites

Before using tools that require authentication, set credentials using one of these methods:

• Environment variables in .mcp.json (recommended for MCP) — set BACKPACK_API_KEY and BACKPACK_SECRET_KEY in the env field (see above)
• CLI config — backpack config set --api-key <key> --api-secret <secret>
• MCP tool — use the auth_config_set tool from your AI agent

Market Symbols

Backpack uses trading pair symbols:

Symbol	Description
SOL_USDC	SOL/USDC spot
BTC_USDC	BTC/USDC spot
ETH_USDC	ETH/USDC spot
SOL_USDC_PERP	SOL/USDC perpetual
BTC_USDC_PERP	BTC/USDC perpetual

Use backpack market list for the full list of available markets.

Error Handling

Errors include actionable recovery instructions:

Error: API credentials are not configured.

Try: backpack config set --api-key <key> --api-secret <secret>

Safety

• Use --reduce-only for exit orders — prevents accidental position flips
• Check max quantities — backpack account max-order before placing large orders
• Start with small sizes when testing
• Never expose your API secret — credentials are masked in output

Configuration Files

File	Path	Description
Config	~/.backpack-cli/config.json	API key and secret

Resources

• Backpack Exchange: https://backpack.exchange
• GitHub: https://github.com/haeminmoon/backpack-cli
• Backpack API Docs: https://docs.backpack.exchange

License

ISC