Polymarket Agents 📈🤖

Autonomous AI trading agents for Polymarket BTC Up/Down prediction markets. Agents consume live market data, analyze probabilities, and execute trades, all orchestrated with the Calfkit distributed agents framework.

If you find this project interesting or useful, please consider:

• ⭐ Starring the repository — it helps others discover it!
• 🐛 Reporting issues
• 🔀 Submitting PRs

Note

If you're interested in AI agents daytrading crypto spot markets, check out another project I built: Crypto Trading Arena. It's an open source arena where AI agents trade on live market data 24/7, with no guardrails.

Architecture

┌──────────────────┐   ┌─────────────────────┐   ┌─────────────────────┐
│    Scheduler     │   │    Agent Worker     │   │    Tool Worker      │
│  (run_client)    │──▶│   (run_agents)      │──▶│   (run_tools)       │
│                  │   │                     │   │                     │
│ • Wake agents    │   │ • Autonomous AI     │   │ • Portfolio and     │
│   on schedule    │   │   agents reasoning  │   │   trading engine    │
│ • Live market    │   │   on live market    │   │ • Execute and       │
│   price feeds    │   │   data              │   │   settle orders on  │
│ • Dynamic prompt │   │                     │   │   live market       │
│   serving to     │   │                     │   │   prices            │
│   agents         │   │                     │   │ • Individual agent  │
│                  │   │                     │   │   wallets           │
└──────────────────┘   └─────────────────────┘   └─────────────────────┘
         │                      │                          │
         └──────────────────────┴──────────────────────────┘
                         Calfkit Broker

Three independent microservices communicate via Calfkit:

1. Scheduler — wakes agents on schedule, fetches live market prices, and dynamically builds prompts with market context
2. Agent Worker — autonomous AI agents reasoning on live market data to make trading decisions
3. Tool Worker — portfolio and trading tools that execute and settle orders on live market prices, with individual agent wallets

Prerequisites

• Python 3.10+
• uv
• Docker (for the broker)
• An API key for OpenAI and/or Anthropic

Quickstart

1. Install dependencies

git clone https://github.com/ryan-yuuu/polymarket-agents.git
cd polymarket-agents
uv sync

2. Configure environment

Copy the example files and fill in your API keys:

cp .env.example .env
cp agents.example.yaml agents.yaml

Edit .env with your key(s):

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

Edit agents.yaml to configure your agents. The default config runs a single gpt 5 mini agent on 15-minute BTC markets:

broker_url: "localhost:9092"

execution:
  mode: paper

market_data:
  gamma_api_url: "https://gamma-api.polymarket.com"
  clob_api_url: "https://clob.polymarket.com"
  ws_url: "wss://ws-subscriptions-clob.polymarket.com/ws/market"

agents:
  - name: "btc-trader-15m"
    model:
      provider: openai          # "openai", "openai-chat", or "anthropic"
      model_name: "gpt-5-mini"
    timeframe: "15m"            # "5m", "15m", or "4h"
    poll_interval_seconds: 60
    initial_balance: 10000.0

3. Start the Calfkit broker

The broker enables communication between all processes. Clone the calfkit-broker and start it with Docker:

git clone https://github.com/calf-ai/calfkit-broker && cd calfkit-broker && make dev-up

Once the broker is running, open three new terminal tabs in the polymarket-agents directory.

4. Launch the system

Start each process in its own terminal, in the following order:

Terminal 1 — Tool Worker (portfolio, trading tools, and realtime pricing):

uv run python -m scripts.run_tools

Terminal 2 — Agent Worker (autonomous AI agents):

uv run python -m scripts.run_agents

Terminal 3 — Scheduler (wakes agents, fetches prices, builds prompts):

uv run python -m scripts.run_client

To align the first prompt to the start of the next market window (useful when poll_interval_seconds matches the timeframe for one-trade-per-window setups):

uv run python -m scripts.run_client --align-start-to-window

The scheduler will begin discovering active BTC Up/Down markets, fetching prices, and sending prompts to your agents. Agents will analyze the market and execute paper trades via the tool worker. Trade logs are written to data/.

To deploy specific agents, pass --agent <name> ... to the agent worker and scheduler:

# Single agent
uv run python -m scripts.run_agents --agent btc-trader-15m
uv run python -m scripts.run_client --agent btc-trader-15m

# Multiple agents
uv run python -m scripts.run_agents --agent btc-trader-15m claude-trader
uv run python -m scripts.run_client --agent btc-trader-15m claude-trader

Omitting --agent runs all agents defined in agents.yaml. The tool worker does not need an --agent flag — it starts with zero wallets and lazily initializes them when an agent first calls get_portfolio.

Agent Configuration

Each agent in agents.yaml supports:

Field	Default	Description
name	"btc-trader"	Unique agent identifier
model.provider	"openai"	"openai" (Responses API), "openai-chat" (Chat Completions), or "anthropic"
model.model_name	"gpt-5-mini"	Model ID passed to the provider
model.reasoning_effort	—	OpenAI only: "minimal", "low", "medium", or "high"
model.reasoning_summary	—	OpenAI only: "detailed", "concise", or "auto"
model.thinking	false	Anthropic only: enable adaptive extended thinking
model.api_key	—	Per-agent API key override (falls back to .env)
timeframe	"15m"	Market timeframe: "5m", "15m", or "4h"
poll_interval_seconds	60	Seconds between market data prompts
cycle_timeout_seconds	300	Max seconds to wait for an agent response per cycle
initial_balance	10000.0	Starting paper trading balance (omit when resume: true)
resume	false	Resume from the latest saved session instead of starting fresh
system_prompt_file	—	Path to a .md file for the system prompt (defaults to .calfkit_agents/default.md)

Multiple agents can run simultaneously with different models, timeframes, and strategies:

agents:
  - name: "gpt-trader"
    model:
      provider: openai
      model_name: "gpt-5-mini"
    timeframe: "15m"
    initial_balance: 10000.0

  - name: "claude-trader"
    model:
      provider: anthropic
      model_name: "claude-sonnet-4-6"
    timeframe: "15m"
    initial_balance: 10000.0

Agent Tools

Tool	Description
place_order	Buy or sell Up/Down shares at the live market price
get_portfolio	View cash balance, positions, and unrealized P&L
calculator	Evaluate arithmetic expressions

Trade Data

Each session writes trades to a timestamped CSV in data/:

{agent_id}.{epoch}.trades.csv

Columns:

timestamp, agent_id, market_slug, end_date, direction, order_side, size, price, cost, balance_after, initial_balance

Starting a new session (default) creates a fresh CSV, preserving old files. Setting resume: true on an agent finds its latest CSV, reads initial_balance from it, and replays all trades to restore the wallet.

Dashboard

A live Streamlit dashboard for monitoring agent performance. It auto-discovers all trade CSVs in data/, parses agent names and session dates from filenames, and plots account value over time based on resolved (sell) orders.

uv run streamlit run scripts/dashboard.py

Features:

• Sidebar navigation — click between agent sessions, sorted newest-first
• Metrics row — current balance, P&L ($ and %), settled predictions, buy count
• Account value chart — interactive Plotly line chart plotting balance after each sell order, with a dashed reference line at the initial balance
• Auto-refresh — toggle in the sidebar with configurable interval (10/15/30/60s) for live monitoring