Live API · v0.5.0

Build on Polymarket
prediction data

Real-time markets, trader intelligence, order books, webhooks, Claude/OpenClaw MCP, and the Falcon signal client — through REST or agents.

Get API Key ↗ API Reference Quick Start MCP (Claude & OpenClaw) Agent client (PyPI) OpenClaw skill Download YAML
Capabilities

Everything you need to build on Polymarket

35,000+ indexed markets · 500,000+ trades · 77,000+ wallets tracked

📈

Live Markets

Browse all indexed Polymarket markets with real-time YES/NO prices, 24h volume, liquidity, OHLCV candles, token IDs, and resolution fields.

⚡

Trade Feed

Paginate through 500k+ trade events filtered by market, wallet, side, size, or date range. Per-market tape and platform volume timeseries included.

👤

Trader Intelligence

Leaderboard, wallet search, category PnL, daily equity curves, holders, open interest, and topic-based copy picks.

📊

Order Book Depth

Live L2 order book (top 20 bid/ask levels) for any market with indexed token IDs. Spread in basis points included.

💼

Wallet Positions

Open positions with average entry price and unrealized PnL — Tier 2. Updated every 10 minutes.

💰

Fee Quoting

Quote and settle copy-trading bot fees in credits, $FAI, USDC, or SOL. Full ledger history and on-chain payment confirmation.

🤖

Claude MCP

Connect Claude Desktop to markets, leaderboard, trader stats, and order books via @falconai/mcp-server — no custom prompts required.

🦅

OpenClaw

Install the falcon-polymarket skill (ClawHub or zip from the agent hub). Pair with the local Falcon client for signal execution.

📱

Telegram copy & dry-run

Link the Falcon bot for wallet copy alerts, autonomous dry-run paper trading (/mode dry, /sim, /dryrun), Strategy Studio auto-trade, multi-profile paper accounts, and CSV export — plus live Safe execution when funded.

🔔

Signed Webhooks

Subscribe via API key to trade, price, volume, resolution, copy-trade, and Strategy Studio events (copy.executed, risk.blocked, strategy.signal). HMAC-verified delivery with retries.


Quick Start

Make your first call in 60 seconds

Generate a free key in seconds — no approval required.

1

Get your API key

Keys start with aif_. Generate one instantly on the Developer Keys page.

2

Make your first request

Pass your key in the Authorization header. The /health endpoint works with any valid key and requires no tier.

3

Paginate with cursors

Take the pagination.next_cursor from any list response and pass it as ?cursor=… on the next request.

4

Import into Postman

Postman → Import → paste /api/openapi.yaml URL or download the file — all endpoints are pre-configured.

# 0. Register sandbox agent (no API key required)
curl -sX POST https://api.falconai.pro/api/v1/external/polymarket/agents/register \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'

# 0-win. Same on Windows PowerShell (single line)
$r = Invoke-RestMethod -Method POST -Uri "https://api.falconai.pro/api/v1/external/polymarket/agents/register" -ContentType "application/json" -Body '{"name":"my-agent"}'
$r.data | ConvertTo-Json -Depth 5

# 0b. Agent heartbeat (use api_key from register)
curl https://api.falconai.pro/api/v1/external/polymarket/briefing \
  -H "Authorization: Bearer aif_your_key"

# 1. Health check — any valid API key
curl https://api.falconai.pro/api/v1/external/polymarket/health \
  -H "Authorization: Bearer aif_your_key"

# 2. List top 10 active markets
curl "https://api.falconai.pro/api/v1/external/polymarket/markets\
?status=active&limit=10" \
  -H "Authorization: Bearer aif_your_key"

# 3. Paginate with next_cursor
curl "https://api.falconai.pro/api/v1/external/polymarket/markets\
?status=active&limit=10&cursor=eyJ0cyI6Ij..." \
  -H "Authorization: Bearer aif_your_key"

# 4. Trader profile (Tier 2)
curl "https://api.falconai.pro/api/v1/external/polymarket\
/traders/0x1b673458d10556f5..." \
  -H "Authorization: Bearer aif_your_key"

# Response envelope (all endpoints)
{
  "success": true,
  "data": [ /* ... */ ],
  "pagination": {
    "limit": 10,
    "has_more": true,
    "next_cursor": "eyJ0cyI6Ij..."
  }
}

Access Tiers

Tier-gated endpoints

Your tier is determined by your $FAI token balance, or credits as a fallback. Call /pricing/access to see your current tier.

Tier Requirement Endpoints unlocked
Sandbox POST /agents/register (self-serve) /agents/me  /briefing  /paper/*  + Tier 1 analytics
Tier 1 Any valid API key /health  /usage  /pricing/access  /events  /series  /markets  /markets/:id  /markets/:id/ohlcv  /markets/:id/orderbook  /markets/:id/price/ticks  /volume/timeseries  /fees/*
Tier 2 Tier 1 + $FAI balance or credits Tier 1 + /trades  /markets/:id/trades  /markets/:id/holders  /markets/:id/oi  /traders/*  /positions/:wallet  /leaderboard  /copy-picks  /orderbook/history  /backtest
Tier 3 Higher $FAI balance Everything in Tier 2 (legacy token-gated extras)

Errors

Standard error codes

All errors use the same envelope — check the code field for machine-readable classification.

HTTPcodeWhen it happens
400BAD_REQUESTInvalid query params, bad wallet format, missing required field
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENYour key's tier is too low for this endpoint
404NOT_FOUNDMarket, trader, or fee ledger entry not found
402PAYMENT_REQUIREDPlan quota exceeded without PAYG credits, or Tier 2/3 access requires a paid plan / $FAI / credits
409CONFLICTFee already charged or in an invalid state
500INTERNAL_ERRORServer-side failure — contact support

Ready to start building?

Explore the reference, connect Claude via MCP, or download the OpenAPI spec.

Get API Key ↗ Open API Reference Claude MCP Setup SDK Examples Download YAML