polymarket-agent-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.

Build & Test Commands

npm run build          # tsc
npm run start          # run MCP server (node dist/index.js)
npm run dev            # tsc --watch
npm test               # vitest run (all tests)
npm run test:watch     # vitest watch mode
npx vitest run tests/services/budget-manager.test.ts  # single test file
npx tsc --noEmit       # type-check without emitting

Architecture

MCP server for Polymarket trading and automation. Three-layer design: Tools → Services → Database.

Entry Point & MCP Server

src/index.ts bootstraps everything: opens SQLite DB, creates service instances (BudgetManager, TradeExecutor, WalletMonitor, PositionTracker), registers 48 MCP tools, and handles graceful shutdown (SIGINT/SIGTERM). Dashboard is a separate project (polymarket-dashboard).

Layers

Tools (src/tools/*.ts): Each file exports a Zod schema and an async handler function. Tools validate input, call services, and return markdown-formatted strings. All tools are registered in index.ts via server.tool().

Services (src/services/*.ts): Business logic layer.

• WalletMonitor — polls watched wallets on an interval, calls filterNewTrades to find copy candidates, runs market quality filter, uses BudgetManager to size positions, executes via TradeExecutor. Has tick-lock to prevent overlapping executions.
• TradeExecutor — preview mode records simulated trades in DB; live mode uses @polymarket/clob-client to place real orders. Validates CLOB responses. Supports atomic trade+budget recording via recordTradeWithBudget.
• PositionTracker — checks open positions for stop-loss/take-profit, trader exits (data API), and market resolutions (CLOB API). Recycles budget on close.
• BudgetManager — daily spending limits with conviction-based multipliers (low/normal/high).
• ConvictionScorer — 0-100 score across 5 dimensions (win rate, volume, consistency, experience, diversity).
• MarketFilter — spread, bid/ask depth, price range checks. Auto-integrated into WalletMonitor.
• Backtester — simulates copying a trader's historical trades.
• SmartFlow — scans top N traders for convergence signals (multiple traders buying same market).
• PriceHistory — historical price data from CLOB API with OHLC.