🎒 Backpack Exchange MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with tools to interact with the Backpack Exchange API. Manage your orders directly from Cursor or other MCP-compatible AI assistants.

Features

Order Management:
List open spot orders (optionally filtered by trading pair)
Create limit or market orders (buy/sell) for both SPOT and PERP markets
Cancel specific orders by ID
Position Management:
List all open perpetual positions with PnL, entry price, liquidation price, etc.
Account Management:
Get account balances (available, locked, staked, and lent funds)
Secure Authentication: ED25519 signature-based authentication
Local-Only: Uses stdio transport for secure local communication

Project Structure

backpack-mcp/
├── auth.py                 # ED25519 authentication module
├── backpack_client.py      # Backpack API client wrapper
├── mcp_server.py           # MCP server with tools
├── requirements.txt        # Python dependencies
├── .env.example            # Environment variables template
├── .env                    # Your API keys (not in git)
├── examples/               # Example code
│   └── example_auth.py     # Direct API usage examples
└── test_integration.py     # Integration tests

Prerequisites

Before installing, ensure you have:

Python 3.8 or higher (Python 3.12+ recommended)
make (usually pre-installed on macOS/Linux)

Python Installation

If you don't have Python 3.8+ installed, we recommend using pyenv to manage Python versions:

Install pyenv: ```bash

macOS (using Homebrew)

brew install pyenv

Linux (using pyenv-installer)

curl https://pyenv.run | bash ```

Install Python 3.12: ``bash pyenv install 3.12.12 pyenv local 3.12.12 ``

Verify Python version: ``bash python3 --version # Should show Python 3.8 or higher ``

The Makefile will automatically check if Python 3 is available and show an error if it's missing.

Installation

1. Clone or Navigate to Project

cd backpack-mcp

2. Install Dependencies

Option A: Using Makefile (Recommended)

The easiest way to set up the project:

make setup

This will:

Create a virtual environment
Install all dependencies
Copy .env.example to .env (if it doesn't exist)

Then edit .env and add your API keys (see step 3 below).

Other useful Makefile commands: ``bash make help # Show all available commands make test # Run integration tests make clean # Remove virtual environment ``

Option B: Manual Installation

If you prefer to install manually:

# Using pip
pip3 install -r requirements.txt

# Or using virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Configure API Keys

Copy the example environment file and add your keys:

cp .env.example .env

Edit .env and add your Backpack Exchange API keys:

BACKPACK_PRIVATE_KEY=your_base64_encoded_private_key
BACKPACK_PUBLIC_KEY=your_base64_encoded_public_key

To generate key pair: `` python3 -c "from cryptography.hazmat.primitives.asymmetric import ed25519; import base64; key = ed25519.Ed25519PrivateKey.generate(); seed = key.private_bytes_raw(); pub = key.public_key().public_bytes_raw(); print(f'Seed: {base64.b64encode(seed).decode()}\nPublic Key: {base64.b64encode(pub).decode()}')" ``

To get your API key:

Log in to Backpack Exchange
Go to Settings > API Keys
Click New API key
Add the public key
Add the generated key pair to your .env file

Usage

MCP Server (Recommended)

The MCP server allows AI assistants like Cursor to interact with your Backpack account.

Setup in Cursor

Create MCP configuration at ~/.cursor/mcp.json:

{
  "mcpServers": {
    "backpack": {
      "command": "/path/to/backpack-mcp/venv/bin/python",
      "args": [
        "/path/to/backpack-mcp/mcp_server.py"
      ]
    }
  }
}

Important: Replace /path/to/backpack-mcp with the actual path to your project directory. For example:

On macOS/Linux: /Users/yourusername/Code/backpack-mcp or ~/Code/backpack-mcp
On Windows: C:\Users\yourusername\Code\backpack-mcp

You can find your project path by running pwd (macOS/Linux) or cd (Windows) in your project directory.

Why API keys aren't in the MCP configuration:

The MCP configuration (~/.cursor/mcp.json) only tells Cursor where to find the Python script and interpreter. It does not contain your API keys. This is a security best practice:

Separation of concerns: Configuration (where to run code) is separate from credentials (API keys)
Security: The .env file with your keys is gitignored and never committed
Runtime loading: The MCP server loads keys from .env when it starts, not from the MCP config
Flexibility: You can change keys without modifying the MCP configuration

How ED25519 key pairs connect to subaccounts:

According to the official Backpack Exchange API documentation:

One key pair per main account: The ED25519 key pair (public/private) authenticates your main Backpack account, not individual subaccounts.

Subaccounts are identified by parameter: When you want to use a specific subaccount, you include subaccountId as a parameter in API requests. The same key pair authenticates all subaccounts under your main account.

No separate keys needed: You do not need different key pairs for different subaccounts. One key pair gives you access to all subaccounts, and you specify which one to use via the subaccountId parameter.

Example flow:

Generate one ED25519 key pair in Backpack Exchange settings
Store it in .env (BACKPACK_PRIVATE_KEY and BACKPACK_PUBLIC_KEY)
The MCP server uses these keys to sign all requests
To access a specific subaccount, include subaccountId in the request parameters (if the endpoint supports it)

Restart Cursor completely (quit and reopen)

Use the tools by asking Cursor:

"List my open orders"
"Create a limit buy order for 0.001 BTC at $80,000"
"Cancel order 12345 for BTC_USDC"
"Show my positions"
"Get my balances"
"Open a long position in SOL_USDC_PERP for $10"

Available MCP Tools

`list_orders`

List all open spot orders.

Parameters:

symbol (optional): Trading pair filter (e.g., "BTC_USDC")

Returns:

orders: List of order objects
count: Number of orders
symbol: Filter used

Example: `` List my open orders List my BTC_USDC orders ``

`create_order`

Create a new order (limit or market). Works for both SPOT and PERP markets.

Parameters:

symbol (required): Trading pair (e.g., "BTC_USDC" for spot, "BTC_USDC_PERP" for perpetual)
side (required): "Bid" (buy) or "Ask" (sell)
orderType (required): "Limit" or "Market"
quantity (optional): Order quantity (required for limit orders, optional for market if quoteQuantity provided)
price (optional): Limit price (required for Limit orders)
timeInForce (optional): "GTC" (default), "IOC", or "FOK"
quoteQuantity (optional): Quote quantity for market orders (e.g., "10" for $10 worth)

Returns:

success: Boolean
order: Order object with ID and details
error: Error message (if failed)

Example: `` Create a limit buy order for 0.001 BTC at $80,000 Open a long position in SOL_USDC_PERP for $10 (market order) ``

`cancel_order`

Cancel a specific order by ID.

Parameters:

orderId (required): Order ID to cancel
symbol (required): Trading pair (e.g., "BTC_USDC")

Returns:

success: Boolean
order: Cancelled order object
error: Error message (if failed)

Example: `` Cancel order 12345 for BTC_USDC ``

`list_positions`

List all open perpetual positions.

Parameters:

None

Returns:

positions: List of position objects with:
symbol: Trading pair
netQuantity: Net quantity (positive = long, negative = short)
entryPrice: Entry price
markPrice: Current mark price
pnlUnrealized: Unrealized profit/loss
pnlRealized: Realized profit/loss
estLiquidationPrice: Estimated liquidation price
And more...
count: Number of positions

Example: `` Show my positions List my perpetual positions ``

`get_balances`

Get all account balances including lent funds.

Parameters:

showZeroBalances (optional): If False (default), only show assets with non-zero balances. If True, show all assets.

Returns:

balances: Dictionary with asset symbols as keys, each containing:
available: Available balance (can be used for trading)
locked: Locked balance (committed to open orders)
staked: Staked balance (staked for rewards)
lent: Lent balance (funds currently lent out, earning interest)
count: Number of assets with non-zero balances
totalAssets: Total number of assets

Example: `` Get my balances Show my account balances ``

Testing

Run the integration tests:

# Using virtual environment
venv/bin/python test_integration.py

# Or system Python
python3 test_integration.py

The tests verify:

Scenario 1: Full workflow (create → list → cancel orders)
Scenario 2: Error handling for all tools
Scenario 3: Response structure validation
Scenario 4: Positions functionality
Scenario 5: Balances functionality (including lent funds)

All tests are integrated into test_integration.py and cover:

Order management (list, create, cancel)
Position management (list positions)
Account management (get balances with lent funds)
Error handling and edge cases

Security

Local-Only: MCP server uses stdio transport (no network exposure)
Environment Variables: API keys stored in .env (gitignored)
ED25519 Signing: All requests are cryptographically signed
No Key Logging: Logging redacts sensitive information

Requirements

Python 3.8+ (see Prerequisites for installation instructions)
Backpack Exchange API keys (ED25519) - see Configure API Keys
Dependencies (automatically installed via make setup or pip install -r requirements.txt):
mcp[cli] - MCP Python SDK
requests - HTTP client
cryptography - ED25519 signing
python-dotenv - Environment variables

Troubleshooting

MCP Server Not Connecting

Check Python path in ~/.cursor/mcp.json matches your system
Restart Cursor completely after configuration changes
Verify dependencies: pip3 install -r requirements.txt
Check API keys: Ensure .env file exists with valid keys

Import Errors

# Make sure you're using the virtual environment
venv/bin/python -c "from mcp_server import list_orders; print('OK')"

API Errors

Verify API keys are correct and base64-encoded
Check you have sufficient funds for orders
Ensure network connectivity to api.backpack.exchange

License

This project is for personal use. Use at your own risk when trading.

Backpack Exchange MCP Server