polyrouter-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

bun install          # Install dependencies
bun run build        # Build to dist/
bun run dev          # Run in development mode (no build)
bun run start        # Run built version
bun run type-check   # TypeScript type checking

Architecture

This is a Model Context Protocol (MCP) server that provides:

1. Unified read access to prediction market platforms via the Polyrouter API (Polymarket, Kalshi, Limitless, Manifold)
2. Direct trading capabilities on Kalshi and Polymarket via their official SDKs

File Structure

src/
├── index.ts              # Main MCP server + all tool definitions
├── trading/
│   ├── types.ts          # Shared trading interfaces
│   ├── kalshi.ts         # Kalshi SDK wrapper
│   ├── polymarket.ts     # Polymarket CLOB client wrapper
│   └── unified.ts        # Unified router + order preview state

Tool Pattern

Each tool follows this pattern:

server.tool(
  "tool_name",
  "Description",
  { /* Zod schema for params */ },
  async (params) => {
    const data = await makeRequest("/endpoint", params);
    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
  }
);

Environment Variables

Create a .env file with:

# Required - Polyrouter API (for market data)
POLYROUTER_API_KEY=xxx
POLYROUTER_BASE_URL=https://api-v2.polyrouter.io  # Optional, defaults to production

# Optional - Kalshi Trading
KALSHI_API_KEY=xxx
KALSHI_API_SECRET=xxx   # RSA private key - see note below

# Optional - Polymarket Trading
POLYMARKET_PRIVATE_KEY=xxx           # Ethereum private key (with 0x prefix)
POLYMARKET_FUNDER_ADDRESS=xxx        # Your Polymarket profile address (optional)

Kalshi RSA Key Format

The Kalshi API secret is an RSA private key. In .env files, you must put the entire key on a single line with literal \n characters: