okx-trader

OKX Trading Plugin for Claude Code

A comprehensive Claude Code plugin for monitoring and managing your OKX Exchange account through the Model Context Protocol (MCP).

Features

Read-Only Position Monitoring

• Current Positions: View open positions across margin, swap, futures, and options
• Position History: Access historical closed positions and P&L
• Account Balance: Check balances across trading and funding accounts
• Risk Metrics: Monitor margin requirements, equity, and liquidation risk

Order Tracking

• Pending Orders: View active orders across all instrument types
• Order History: Review past orders (last 7 days)
• Transaction Fills: See executed trades and fill details (3 days to 3 months)

Trading Bot Management

• DCA Bots: Monitor Dollar Cost Averaging / Martingale strategy bots
• Grid Bots: Track grid trading bots (spot, contract, moon grid)
• Algo Orders: View conditional orders, OCO, trigger orders, iceberg, TWAP
• Recurring Strategies: Monitor recurring buy/sell strategies

Built-in Slash Commands

• /okx-positions - Quick positions summary
• /okx-balance - Account balance overview
• /okx-risk - Risk metrics dashboard
• /okx-bots - Trading bots summary

Installation

Prerequisites

• Claude Code CLI installed
• Python 3.11 or higher
• OKX account with API credentials

Quick Install

1. Clone or download this plugin:

   git clone https://github.com/your-org/okx-plugin.git
   cd okx-plugin
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure API credentials:

   cp .env.example .env
   # Edit .env and add your OKX API credentials
   

4. Install the plugin (from the plugin directory):

   # If hosting on GitHub
   /plugin marketplace add your-org/okx-plugin
   
   # Or install locally
   # (Add plugin path to your Claude Code settings)
   

Configuration

Step 1: Create OKX API Keys

1. Log in to OKX
2. Navigate to Profile → API or visit https://www.okx.com/account/my-api
3. Click Create API Key

Recommended Permissions:

• ✅ Read - Required for position monitoring
• ❌ Trade - Not needed (read-only plugin)
• ❌ Withdraw - Not needed

Step 2: Configure Credentials

The plugin searches for credentials in the following order:

1. Environment variables (if already set)
2. Explicit path via OKX_ENV_FILE environment variable
3. Current directory .env file (where you run Claude Code)
4. Home directory ~/.okx.env
5. Config directory ~/.config/okx/.env

Option A: Using Environment Variables (Recommended for production)

export OKX_API_KEY="your-api-key-here"
export OKX_SECRET_KEY="your-secret-key-here"
export OKX_PASSPHRASE="your-passphrase-here"
export OKX_TESTNET="false"

Option B: Using .env File (Recommended for development)

Create .env in any of these locations:

• Current directory (where you run Claude Code)
• ~/.okx.env
• ~/.config/okx/.env

# OKX API Credentials
OKX_API_KEY=your-api-key-here
OKX_SECRET_KEY=your-secret-key-here
OKX_PASSPHRASE=your-passphrase-here

# Set to 'true' for testnet/demo, 'false' for real account
OKX_TESTNET=false

Option C: Custom .env Path

export OKX_ENV_FILE="/path/to/your/.env"

Usage

Once installed, you can interact with your OKX account through Claude Code:

Natural Language Queries

Show my OKX positions

What's my account balance on OKX?

Check my OKX risk metrics

Show all my DCA bots

Get pending orders for BTC-USDT-SWAP

Slash Commands

/okx-positions    # Quick positions overview
/okx-balance      # Account balances
/okx-risk         # Risk metrics
/okx-bots         # All trading bots

Available MCP Tools

The plugin exposes 19 MCP tools for fine-grained queries:

Positions & Risk:

• get_positions - Current open positions
• get_positions_history - Historical positions
• get_position_risk - Risk metrics
• get_account_balance - Trading account balance
• get_asset_balances - Funding account balance

Orders:

• get_pending_orders - Active orders
• get_order_history - Past orders (7 days)
• get_fills - Recent fills (3 days)
• get_fills_history - Fill history (3 months)

Algo Orders:

• get_algo_orders_pending - Active algo orders
• get_algo_orders_history - Past algo orders

Grid/Recurring Bots:

• get_grid_bots_pending - Active grid bots
• get_grid_bots_history - Past grid bots
• get_grid_bot_details - Detailed bot info
• get_grid_bot_sub_orders - Bot sub-orders

DCA Bots:

• get_dca_bots_pending - Active DCA bots
• get_dca_bots_history - Past DCA bots
• get_dca_bot_details - Detailed DCA bot info

Examples

Monitor DCA Bot Performance

Show me details for DCA bot 123456789

List all my active DCA bots with their P&L