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

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:

1. Environment variables in .mcp.json (recommended for MCP) — set BACKPACK_API_KEY and BACKPACK_SECRET_KEY in the env field (see above)
2. CLI config — backpack config set --api-key <key> --api-secret <secret>
3. 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

1. Use --reduce-only for exit orders — prevents accidental position flips
2. Check max quantities — backpack account max-order before placing large orders
3. Start with small sizes when testing
4. 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