Back

Horse Race MCP

Tool specifications — The Horse Race MCP tools below are exposed through the main EventTrader MCP server. Read tools work unauthenticated; trade tools require an API key in the MCP transport headers.

The Model Context Protocol (MCP) server exposes Horse Race placement markets to LLM clients (Claude Desktop, Claude Code, MCP-compatible agents). Ask your AI assistant to read the placement grid for a race, find the cheapest 1st-place share, or place a podium bet — all through natural language.

REST & WebSocket Python SDK MCP Tools All Races

Server Endpoint

https://cymetica.com/mcp/v1

EventTrader exposes a single MCP surface — the same endpoint serves arena, exchange, OTC stocks, TGE-launch, and Horse Race placement markets. The tools below filter to Horse Race markets when called.

Discovery: GET /.well-known/mcp.json · Tools: GET /mcp/v1/tools · Register: POST /mcp/v1/register

For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "eventtrader": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cymetica.com/mcp/v1"]
    }
  }
}

Tools

Tool	Args	Description
`list_horse_races`	`active_only?`	Return all races. By default only races in `pending` or `trading` status.
`get_horse_race`	`race_id`	Full detail for a single race: assets, placements, active epoch, start-snapshot prices, live prices.
`get_horse_race_book`	`race_id, asset, position`	CLOB orderbook depth + best bid/ask for one (asset, position) cell.
`get_horse_race_grid`	`race_id`	Returns `{grid, row_sums, col_sums, field_size, max_placement}`. `grid` is `asset → position → {mid_price, best_bid, best_ask, last_trade}`. Row sums equal 1.0 in an efficient market (no arbitrage).
`place_horse_race_order`	`race_id, asset, position, side, price, size`	Place a limit or market order on a placement book. Requires authenticated MCP session.
`cancel_horse_race_order`	`race_id, order_id, asset, position`	Cancel a resting order. Requires `asset` and `position` — the engine routes by them.
`get_horse_race_positions`	`race_id`	Authenticated caller's shares in this race, grouped by (asset, position).
`get_horse_race_results`	`race_id`	Final placement order + $/share payouts after a race resolves.

Authentication

Read tools (list_horse_races, get_horse_race, get_horse_race_book, get_horse_race_grid, get_horse_race_results) work unauthenticated. Trade tools (place_horse_race_order, cancel_horse_race_order, get_horse_race_positions) require an EventTrader API key passed as Authorization: Bearer <key> in the MCP transport headers, or via the OAuth flow surfaced by your MCP client.

Example LLM Prompts

"List all active horse races right now."
"What's the placement grid for the next BTC/ETH/SOL/AVAX race?"
"Which asset has the cheapest 1st-place share in this race?"
"Buy 10 shares of BTC finishing 1st at $0.35."
"Show me my open positions across all races."
"What were the final placements in race race_abc123?"

Tool Reference

list_horse_races

{
  "name": "list_horse_races",
  "description": "List Horse Race placement markets. By default only races in pending or trading status.",
  "inputSchema": {"type":"object","properties":{
    "active_only":{"type":"boolean","default":true}
  }}
}

get_horse_race_grid

{
  "name": "get_horse_race_grid",
  "description": "Placement grid for a race. Returns {grid, row_sums, col_sums, field_size, max_placement}. grid is asset → position(str) → {mid_price, best_bid, best_ask, last_trade}.",
  "inputSchema": {"type":"object","required":["race_id"],"properties":{
    "race_id":{"type":"string"}
  }}
}

get_horse_race_book

{
  "name": "get_horse_race_book",
  "description": "CLOB orderbook for one (asset, position) cell.",
  "inputSchema": {"type":"object","required":["race_id","asset","position"],"properties":{
    "race_id":{"type":"string"},
    "asset":{"type":"string","description":"Asset symbol in the race field (e.g. BTC, ETH)"},
    "position":{"type":"integer","minimum":1,"description":"Finish position (1 = first place)"}
  }}
}

place_horse_race_order

{
  "name": "place_horse_race_order",
  "description": "Place a limit or market order on a placement book. Each share pays $1 if the asset lands in that position.",
  "inputSchema": {"type":"object","required":["race_id","asset","position","side","price","size"],"properties":{
    "race_id":{"type":"string"},
    "asset":{"type":"string"},
    "position":{"type":"integer","minimum":1,"maximum":5},
    "side":{"type":"string","enum":["buy","sell"]},
    "price":{"type":"number","exclusiveMinimum":0,"exclusiveMaximum":1.0,
             "description":"Price per share, strictly between 0 and 1"},
    "size":{"type":"number","exclusiveMinimum":0},
    "order_type":{"type":"string","enum":["limit","market"],"default":"limit"},
    "post_only":{"type":"boolean","default":false}
  }}
}

Limits

MCP tool calls share the same rate limits as the underlying REST endpoints — see X-RateLimit-* headers on the REST responses. Order placement is rate-limited per wallet/account.

EventTrader