Polymarket Trading

The Polymarket system gives AI agents the ability to trade prediction markets on Polymarket — the world's largest prediction market platform. It combines:

• 112 specialized tools across 10 skills — trading, on-chain analysis, social intelligence, event feeds, advanced analytics, smart execution, counter-intelligence, portfolio management, and quantitative modeling
• Real-time on-chain intelligence — whale tracking, orderbook depth, net flow analysis, wallet profiling, liquidity mapping
• Social sentiment analysis — Twitter, Reddit, Telegram, Polymarket comments, cross-platform velocity detection
• Smart execution — sniper orders, TWAP/VWAP scale-in, correlation hedging, automated exit strategies
• Counter-intelligence — manipulation detection, resolution risk scoring, counterparty analysis
• 14 quant tools — Kelly criterion, Black-Scholes, Bayesian inference, Monte Carlo simulation, regime detection
• Self-improving agents — prediction journaling, calibration tracking, strategy performance, P&L attribution
• Proactive trading engine — automatic agent waking with balance gating, mandatory analysis sequence, and token-efficient sessions
• Token-optimized responses — tool outputs trimmed 60-75% to reduce session costs from $3-5 to $0.50-1.50
• Full dashboard — 22 tabs across 6 groups (Trading, Automation, Orders, Intelligence, Analytics, Journal) with Buy Position modal
• Auto-SDK install — the Polymarket CLOB SDK installs automatically, zero manual setup
• DB persistence — 25+ tables for config, trades, signals, whales, events, predictions, calibration
• Dedicated system prompt — 6-phase trading loop, 10 risk commandments, tool choreography

Everything goes through the standard enterprise permission pipeline — risk levels, side-effect checks, approval queues, guardrails, and audit logging.

1. Create a Polymarket Agent

Go to Agents → Create Agent and select the "Polymarket Trader" template from the Finance category. This pre-assigns all 9 skills (108 tools). Or assign skills individually:

2. Connect a Wallet

The agent needs an Ethereum wallet with USDC on Polygon. Two options:

• Create: Use the Wallet section on the dashboard to generate or import a wallet
• Import: Use the dashboard to import an existing private key from MetaMask, Rabby, etc.

3. Configure Risk Limits

Use the Config tab on the dashboard or poly_set_config. Set trading mode, max position, daily loss limit, drawdown threshold.

4. Fund & Start

Send USDC to the wallet on Polygon. Start with paper trading mode to test strategies risk-free.

┌─────────────────────────────────────────────────────────────────────┐
│                        POLYMARKET TRADING SYSTEM                     │
│                         108 tools · 9 skills                         │
├─────────────┬──────────────┬──────────────┬──────────────────────────┤
│  INTELLIGENCE               │   EXECUTION                 │ LEARNING │
│                             │                             │          │
│  On-Chain (6)               │  Trading (63)               │ Journal  │
│  · Whale tracking           │  · Orders, positions        │ Calibr.  │
│  · Orderbook depth          │  · Risk controls            │ Strategy │
│  · Net flow analysis        │  · Wallet management        │ Lessons  │
│  · Wallet profiling         │                             │ P&L Attr │
│  · Liquidity mapping        │  Execution Edge (4)         │          │
│  · TX decoding              │  · Sniper orders            │          │
│                             │  · TWAP/VWAP scale-in       │          │
│  Social (5)                 │  · Hedging                  │          │
│  · Twitter sentiment        │  · Exit strategies          │          │
│  · Reddit pulse             │                             │          │
│  · Telegram monitor         │  Portfolio (3)              │          │
│  · Polymarket comments      │  · Optimizer                │          │
│  · Velocity tracking        │  · Drawdown monitor         │          │
│                             │  · P&L attribution          │          │
│  Feeds (5)                  │                             │          │
│  · Event calendar           │  Counter-Intel (3)          │          │
│  · Official sources         │  · Manipulation detector    │          │
│  · Odds aggregator          │  · Resolution risk          │          │
│  · Breaking news            │  · Counterparty analysis    │          │
│  · Resolution tracking      │                             │          │
│                             │  Quant Engine (14)          │          │
│  Analytics (5)              │  · Kelly, Black-Scholes     │          │
│  · Correlation detection    │  · Monte Carlo, Bayesian    │          │
│  · Arbitrage scanning       │  · RSI, MACD, Bollinger     │          │
│  · Regime detection         │  · VaR, Entropy, Hurst      │          │
│  · Smart money index        │  · Signal generator         │          │
│  · Microstructure           │                             │          │
└─────────────┴──────────────┴──────────────┴──────────────────────────┘

Data Flow

Breaking News ──→ Social Velocity ──→ Sentiment Analysis ──→ ┐
Official Sources ──→ Event Calendar ──→ Resolution Track ──→ ├→ Smart Money Index ──→ Signal Generation
Whale Tracker ──→ Orderbook Depth ──→ On-Chain Flow ─────→ ┘        │
                                                                     ↓
Manipulation Check ──→ Resolution Risk ──→ Counterparty ──→ Risk Gate
                                                                     ↓
Kelly Criterion ──→ Position Sizing ──→ Execution (Sniper/TWAP) ──→ Trade
                                                                     ↓
Exit Strategy ──→ Drawdown Monitor ──→ Portfolio Optimizer       Record Prediction
                                                                     ↓
                            Resolve → Review → Lesson → Calibrate → Improve

Performance

• Shared response cache — all external API calls cached with configurable TTL (15s–60s)
• Rate limiting — 30 requests/minute per domain to prevent API bans
• Parallel fetches — Promise.all for multi-token analysis, cross-platform sentiment
• Retry logic — automatic retry with exponential backoff for transient failures
• Config reads from DB — no stale in-memory state; dashboard config changes take effect on next tool call

The Learning Loop

1. Recall: poly_recall_lessons — check past lessons for this market type
2. Predict: poly_record_prediction — journal prediction with reasoning BEFORE trading
3. Execute: poly_place_order + poly_exit_strategy
4. Resolve: poly_resolve_prediction — log outcome → auto-updates calibration
5. Review: poly_trade_review → poly_record_lesson — extract insights
6. Calibrate: poly_calibration — "Am I overconfident at 80%?"
7. Rank: poly_strategy_performance — which signals make money?
8. Attribute: poly_pnl_attribution — P&L by strategy/category/signal

Every trade goes through a 9-step permission pipeline, plus Polymarket-specific risk checks:

1. Sandbox → Working hours → IP check → Tool blocks → Skill membership → Risk level → Side effects → Approval → Guardrails

Plus: circuit breaker, daily trade/loss limits, position size caps, category restrictions, manipulation screening, resolution risk check, liquidity verification, slippage estimation.

The wallet system implements a 7-layer security model for managing funds. All features are accessible from the Wallet tab on the dashboard.

Wallet Management

Withdrawal Whitelist

Agents can only transfer funds to pre-registered addresses. This is the primary defense against prompt injection, hallucination, and social engineering attacks.

Transfer Flow

1. Owner adds address — Dashboard → Wallet tab → "Add Address" → set label, address, limits, cooling period
2. Cooling period elapses — address badge changes from "Cooling: Xh left" to "Active"
3. User instructs agent — Chat: "Transfer $50 USDC to My MetaMask"
4. Agent calls poly_transfer_funds — validates whitelist, cooling, limits → creates pending request
5. Owner approves — Dashboard → Wallet tab → Pending Transfers → Approve button
6. On-chain execution — Backend sends USDC/MATIC via ethers.js on Polygon → TX hash logged

The watcher engine provides continuous market surveillance using a configurable background LLM for real-time analysis. It runs a demand-driven architecture — zero CPU/network when idle.

Engine Architecture

• Demand-driven: 60s idle poller checks for active watchers. Only starts the 15s fast tick loop when watchers exist. Auto-stops when none remain.
• Agent wake system: Critical events → immediate agent session spawn. 3+ warnings → also spawn. Info → queued for next session.
• Rate limited: 5-minute cooldown per agent to prevent spawn storms.

Watcher Types

AI Configuration

Background AI analysis uses a separate, configurable LLM (not the main agent model). Configure via the Monitors tab → "Configure" button:

• Provider & Model: Pulls from your configured providers in Settings → Models & API Keys. Uses org API key by default.
• Daily Budget: Max LLM API calls per day (default 100). Prevents runaway costs. Resets at midnight.
• Max Spawns/hr: Max agent session spawns per hour from critical signals (default 6).
• Recommended models: Grok (real-time X/Twitter), GPT-4o-mini (cheap), Groq (free tier), DeepSeek (cheap).

Database Tables

Layout

Two-column layout: vertical navigation sidebar (280px) on the left with grouped tabs, content pane on the right. The P&L line chart is sticky at the top and always visible regardless of scroll position.

Key UI Features

• Sticky P&L Chart: Multi-agent profitability line chart pinned to top of page. Catmull-Rom smooth curves with distinct colors per agent.
• Org Switcher: Organization dropdown in header — filters agents and all data by selected org.
• Agent Dropdown: Select which Polymarket agent to view. Only shows agents with Polymarket skills.
• Universal Detail Modal: Click any table row to view full details in a modal.
• Pagination + Search + Filters: All 22+ tables have search, column filters, and pagination.
• HelpButton per section: Every tab and subsection has a (?) help button with detailed documentation.
• Real-time SSE: Live price streaming, dashboard updates, and wallet balance auto-refresh.
• Buy Position Modal: Search and buy markets directly from the Wallet tab. Shows composite scores, pipeline signals, Kelly sizing, liquidity grades, and regime detection for each result. One-click buy with outcome selection.
• Sell Position: Click any live position to open a sell modal with size input and one-click execution.
• Overview Stats Grid: 16 stat cards showing wallet status, mode, pending trades, live positions, total trades, win rate, P&L, whales tracked, active snipers, active hedges, exit rules, arbitrage opportunities, lessons, drawdown, social signals, and events — all at a glance.
• Config Modal: Trading configuration (mode, limits) via modal — changes take effect immediately.
• AI Config Modal: Background analysis model config — provider/model from org settings, budget, spawn limits.

All data loads in parallel via Promise.all (23+ API calls batched). SSE streams provide real-time price and dashboard updates.

The Polymarket page is fully organization-aware:

• Org Switcher: Filters agents by selected organization. Client org users only see their org's agents and data.
• Page Access Control: Polymarket is not visible to client orgs by default. Grant access via Organizations → Org Detail → Visible Pages tab → toggle "Polymarket" on.
• Data Isolation: All API routes filter by agent ID, which is org-scoped. No cross-org data leakage.
• Role Restrictions: Wallet export and whitelist management require owner role. Viewing data requires admin.

Agents with Polymarket skills get an injected system prompt (buildPolymarketPrompt()) containing:

• 6-phase trading loop: Scan → Analyze → Decide → Execute → Monitor → Learn
• 10 risk commandments: Never risk >5% on one market, never trade without checking liquidity, always set exit rules, etc.
• Anti-patterns: Don't revenge trade, don't chase, don't anchor to entry price
• Tool choreography: Which tools to use together for each strategy type
• Category-specific edge sources: What signals work for politics, sports, crypto, economics, legal, science

polymarket (64 tools)

Market Discovery (11) · Wallet & Account (6) · Funds (2) · Fund Transfers (1) · Portfolio (4) · Order Management (8) · Analytics (6) · Config (4) · Alerts (3) · Approval Queue (4) · Social (3) · Paper (2) · System (2) · Learning (8)

polymarket-quant (14 tools)

Kelly · Black-Scholes · Bayesian · Monte Carlo · RSI/MACD/Bollinger · Volatility/Hurst · Stat Arb · VaR · Entropy · News Feed · Sentiment · Signal Generator · Correlation Matrix

polymarket-onchain (6 tools)

Whale Tracker · Orderbook Depth · On-Chain Flow · Wallet Profiler · Liquidity Map · Transaction Decoder

polymarket-social (5 tools)

Twitter Sentiment · Polymarket Comments · Reddit Pulse · Telegram Monitor · Social Velocity

polymarket-feeds (5 tools)

Event Calendar · Official Sources · Odds Aggregator · Resolution Tracker · Breaking News

polymarket-analytics (5 tools)

Market Correlation · Arbitrage Scanner · Regime Detector · Smart Money Index · Market Microstructure

polymarket-execution (4 tools)

Sniper Order · Scale In (TWAP/VWAP) · Hedge Position · Exit Strategy

polymarket-counterintel (3 tools)

Manipulation Detector · Resolution Risk · Counterparty Analysis

polymarket-portfolio (3 tools)

Portfolio Optimizer · Drawdown Monitor · P&L Attribution

polymarket-watcher (4 tools)

Setup Monitors · List Monitors · Manage Monitor · AI Watcher Config

Dashboard & Data

Wallet & Transfers

Watchers & AI

SSE Streams

• Start with paper trading — test strategies before real money
• Always run pre-trade checks — resolution_risk + manipulation_detector + microstructure + recall_lessons
• Use scale-in for large orders — $500+ in thin markets should use TWAP/VWAP
• Set exit rules immediately — every position needs take-profit, stop-loss, or trailing stop
• Check calibration weekly — if overconfident, reduce position sizes
• Review P&L attribution monthly — kill strategies with <45% win rate over 20+ trades
• Track whale wallets — add consistently profitable wallets to your watchlist
• Monitor social velocity — spikes of 3x+ acceleration precede market moves
• Use hedges for large positions — reduce directional risk via correlated markets
• Record every prediction — the learning system only works with data

The watcher engine includes a proactive trading loop that automatically wakes the trading agent when it's behind on daily trade goals. This ensures consistent market engagement without manual intervention.

How It Works

1. Every 15 minutes, the watcher checks today's trade count vs the min_trades_daily goal
2. Balance gate — before waking the agent, checks USDC balance on-chain. If < $5, the wake is skipped entirely (prevents burning API tokens when there's nothing to trade with)
3. Spawn cooldown — 5-minute minimum between agent wakes to prevent spam
4. Mandatory analysis sequence — the wake message forces the agent through an 8-step analysis before placing any trades

Mandatory Pre-Trade Sequence

Every proactive wake requires the agent to complete these steps in order before placing any trades:

Only after completing all 8 steps does the agent proceed to market screening and trade placement. This ensures quality over quantity — no blind trading.

Smart Execution Requirements

• Every candidate market must pass: poly_quick_analysis + poly_resolution_risk + poly_manipulation_detector
• Position sizing via poly_kelly_criterion — no arbitrary $5 bets
• Orders > $50 must use poly_scale_in (TWAP/VWAP) to minimize slippage
• Time-sensitive opportunities use poly_sniper with trailing limits
• Correlated positions should use poly_hedge

AI trading sessions can be expensive — a single proactive wake can consume 100K+ input tokens ($3-5) if not optimized. The system implements several token-saving measures:

Response Trimming

Tool responses are automatically trimmed to reduce token consumption while preserving essential information:

Agent Behavioral Rules

The system prompt enforces strict token efficiency rules:

• Balance first — poly_get_balance must be called before any analysis. If <$5 available, stop immediately.
• No duplicate calls — same tool with same parameters must not be called twice in one session
• No retry on rate limit — if a tool returns "Rate limited", skip it and move on (don't call it 5x)
• Session caps — max 2 screen calls, max 2 search calls, max 1 sentiment call per session
• Stop on negative Kelly — if poly_kelly_criterion returns capped=0 (no edge), skip that market immediately
• Stop when done — once 2-3 tradeable opportunities are found and executed, end the session

Expected Savings

These optimizations reduce proactive session cost from $3-5 per wake to $0.50-1.50 per wake — a 60-75% reduction in token usage.