Alpha Arena MCP

An MCP server that delivers hyperliquid account data, perpetuals market context, and trading tools for AI agents — inspired by nof1.ai and open-nof1.ai.

Overview

Alpha Arena MCP bridges AI models with the Hyperliquid perpetual futures exchange, allowing LLMs to:

• Analyze real-time market data (prices, indicators, open interest).
• Fetch and format account positions and performance.
• Execute trades with risk-managed orders (including auto-calculated take-profit/stop-loss).
• Close positions or cancel orders programmatically.

Designed for algorithmic trading bots, this server supports both mainnet and testnet operations. It uses the CCXT library for exchange interactions and pandas_ta for technical analysis.

Key Use Case: Integrate with Claude Desktop or similar MCP clients to create an AI trading assistant that generates recommendations based on prompts and executes them via tools.

Features

• Trading Tools:

  • Place limit/market orders with leverage, TP/SL (auto-calculated if omitted).
  • Close all positions for a symbol (reduce-only market orders).
  • Cancel all open orders for a symbol.
  • Retrieve formatted account info (balance, positions, PnL).
  • Get formatted market state (OHLCV, EMAs, MACD, RSI, volume, OI, funding rate).

• MCP Prompts:

  • System prompt for expert crypto analysis.
  • User prompt template incorporating market/account data for LLM invocations.

• Exchange Support: Hyperliquid perpetuals (sandbox/testnet configurable).

• Risk Management: Built-in TP/SL calculation based on leverage (2:1 reward:risk ratio).

• Error Handling: Graceful fallbacks for API errors.

Prerequisites

• Python 3.10+
• uv for dependency management (recommended; fallback to pip)
• A Hyperliquid account with API credentials (wallet address and private key).

Installation

1. Clone the Repository:

   git clone https://github.com/kukapay/alpha-arena-mcp.git
   cd alpha-arena-mcp
   

2. Install dependencies with uv:

   uv sync 
   

3. Install to Claude Desktop:

   Install the server as a Claude Desktop application:

   uv run mcp install main.py --name "Alpha Arena"
   

   Configuration file as a reference:

   {
      "mcpServers": {
          "Alpha Arena": {
              "command": "uv",
              "args": [ "--directory", "/path/to/alpha-arena-mcp", "run", "main.py" ],
              "env": { 
                "MAIN_ACCOUNT_ADDRESS": "your_main_account_address", 
                "API_ACCOUNT_PRIVATE_KEY": "your_api_account_private_key",
                "NETWORK": "testnet"  /* testnet | main */                  
              }
          }
      }
   }
   

   Replace /path/to/alpha-arena-mcp with your actual installation path, and update your_main_account_address and your_ai_account_private_key with your own account details.

Usage

Example Workflow

1. Set Up Analysis (via Prompt):

   • Use nof1_system_prompt() to load the expert trader persona.

2. Generate Recommendation (via Prompt + Data):

   • Use nof1_user_prompt("BTC/USDC:USDC") → Injects market/account data into the user prompt for LLM analysis.

3. Execute Trade (via Tool):

   • place_order(symbol="BTC/USDC:USDC", side="buy", size=0.01, leverage=10) → Places order with auto-TP/SL.

4. Manage Position:

   • close_position("BTC/USDC:USDC") → Closes all positions.
   • cancel_open_orders("BTC/USDC:USDC") → Cancels pending orders.

Available Tools

place_order

Places a limit/market order with optional TP/SL. Auto-calculates TP/SL if not provided based on leverage (2:1 reward:risk).

Parameters:

• symbol (str): Trading pair, e.g., "BTC/USDC:USDC".
• side (str: buy/sell): Order direction.
• size (float): Order size (quantity).
• price (float, optional): Limit price (defaults to current market price).
• leverage (float=10): Leverage multiplier.
• tp_price/sl_price (float, optional): Take-profit/stop-loss prices.

Returns: Dict: Order IDs or error.

Usage Example

Prompt:

Buy 0.01 BTC with 10x leverage on Hyperliquid, using market price.

Response:

{
  "status": "success",
  "result": {
    "main_order_id": "abc123",
    "tp_order_id": "def456",
    "sl_order_id": "ghi789",
    "status": "success"
  }
}

close_position

Closes all positions for a symbol using reduce-only market orders.

Parameters:

• symbol (str): Trading pair, e.g., "BTC/USDC:USDC".

Returns: Dict: Close orders or no-action message.

Usage Example

Prompt:

Close my entire BTC position now.

Response:

{
  "close_orders": [
    {
      "order_id": "jkl012",
      "side": "sell",
      "size": 0.01,
      "status": "closed"
    }
  ],
  "status": "success"
}

cancel_open_orders

Cancels all open orders for a symbol.

Parameters:

• symbol (str): Trading pair, e.g., "ETH/USDC:USDC".

Returns: Dict: Canceled orders or no-action message.

Usage Example

Prompt:

Cancel all my pending orders for ETH.

Response:

{
  "canceled_orders": [
    {
      "id": "mno345",
      "status": "canceled"
    },
    {
      "id": "pqr678",
      "status": "canceled"
    }
  ],
  "status": "success"
}

account_info

Fetches and formats account balance, positions, and performance summary.

Parameters: None.

Returns: str: Formatted account summary.

Usage Example

Prompt:

What's my current account status?

Response:

Current Total Return (percent): 2.5%
Available Cash: 1500.0
Current Account Value: 1525.0
Positions: {"symbol": "BTC/USDC:USDC", "quantity": 0.01, "unrealized_pnl": 25.0, ...}

market_state

Fetches and formats market data, including technical indicators, volume, open interest, and funding rate.

Parameters:

• symbol (str): Trading pair, e.g., "SOL/USDC:USDC".

Returns: str: Formatted market state.

Usage Example

Prompt:

Give me the latest market data for SOL.

Response:

Current Market State:
current_price = 150.25, current_ema20 = 148.50, current_macd = 1.20, current_rsi (7 period) = 65.3

Open Interest: Latest: 100000.0 Average: 100000.0
Funding Rate: 0.0001

Intraday series (by minute, oldest → latest):
Mid prices: [145.0, 146.2, ...]
...

Available Prompts

nof1_system_prompt

Expert crypto analyst system prompt.

Parameters: None
Returns: str: System message.

Example:

You are an expert cryptocurrency analyst and trader with deep knowledge of blockchain technology, market dynamics, and technical analysis.

Your role is to:
- Analyze cryptocurrency market data, including price movements, trading volumes, and market sentiment
- Evaluate technical indicators such as RSI, MACD, moving averages, and support/resistance levels
- Consider fundamental factors like project developments, adoption rates, regulatory news, and market trends
- Assess risk factors and market volatility specific to cryptocurrency markets
- Provide clear trading recommendations (BUY, SELL, or HOLD) with detailed reasoning
- Suggest entry and exit points, stop-loss levels, and position sizing when appropriate
- Stay objective and data-driven in your analysis

[... full prompt continues ...]

Today is November 01, 2025.

nof1_user_prompt

Data-enriched user prompt for analysis.

Parameters: symbol (str)
Returns: str: Prompt with market/account data.

It has been 45 minutes since you started trading. The current time is 2025-11-01T10:30:00 and you've been invoked 3 times. Below, we are providing you with a variety of state data, price data, and predictive signals so you can discover alpha. Below that is your current account information, value, performance, positions, etc.

ALL OF THE PRICE OR SIGNAL DATA BELOW IS ORDERED: OLDEST → NEWEST

Timeframes note: Unless stated otherwise in a section title, intraday series are provided at 3-minute intervals. If a coin uses a different interval, it is explicitly stated in that coin's section.

# HERE IS THE CURRENT MARKET STATE
## ALL SOL DATA FOR YOU TO ANALYZE
Current Market State:
current_price = 150.25, current_ema20 = 148.50, current_macd = 1.20, current_rsi (7 period) = 65.3

[... full formatted market data ...]

---------------------------------------------------------- 
## HERE IS YOUR ACCOUNT INFORMATION & PERFORMANCE
Current Total Return (percent): 2.5%
Available Cash: 1500.0
Current Account Value: 1525.0
Positions: {"symbol": "BTC/USDC:USDC", "quantity": 0.01, ...}

License

MIT License. See LICENSE for details.