Real-time markets, trader intelligence, order books, webhooks, Claude/OpenClaw MCP, and the Falcon signal client — through REST or agents.
35,000+ indexed markets · 500,000+ trades · 77,000+ wallets tracked
Browse all indexed Polymarket markets with real-time YES/NO prices, 24h volume, and liquidity — enriched from the CLOB API every 5 minutes.
Paginate through 500k+ trade events filtered by market, wallet, side, or date range. Updated every ~1 minute on production from the Data API.
Leaderboard, full wallet stats (PnL, win rate, categories), and topic-based copy picks — risk-adjusted rankings included.
Live L2 order book (top 20 bid/ask levels) for any market with indexed token IDs. Spread in basis points included.
Open positions with average entry price and unrealized PnL derived from the full trade history — updated every 10 minutes.
Quote and settle copy-trading bot fees in credits, $FAI, USDC, or SOL. Full ledger history and on-chain payment confirmation.
Connect Claude Desktop to markets, leaderboard, trader stats, and order books via @falconai/mcp-server — no custom prompts required.
Install the falcon-polymarket skill (ClawHub or zip from the agent client page). Pair with the local Falcon client for signal execution.
Subscribe via API key to trade, price, volume, resolution, and copy-trade events (copy.executed, risk.blocked). HMAC-verified delivery with retries.
Generate a free key in seconds — no approval required.
Keys start with aif_. Generate one instantly on the Developer Keys page.
Pass your key in the Authorization header. The /health endpoint works with any valid key and requires no tier.
Take the pagination.next_cursor from any list response and pass it as ?cursor=… on the next request.
Postman → Import → paste /api/openapi.yaml URL or download the file — all endpoints are pre-configured.
# 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..." } }
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 |
|---|---|---|
| Tier 1 | Any valid API key | /health /usage /pricing/access /events /series /markets /markets/:id /markets/:id/orderbook /markets/:id/price/ticks /fees/* |
| Tier 2 | Tier 1 + $FAI balance or credits | Tier 1 + /trades /traders/* /leaderboard /copy-picks /orderbook/history /backtest |
| Tier 3 | Higher $FAI balance | Everything in Tier 2 + /positions/:wallet |
All errors use the same envelope — check the code field for machine-readable classification.
| HTTP | code | When it happens |
|---|---|---|
| 400 | BAD_REQUEST | Invalid query params, bad wallet format, missing required field |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | Your key's tier is too low for this endpoint |
| 404 | NOT_FOUND | Market, trader, or fee ledger entry not found |
| 402 | PAYMENT_REQUIRED | Insufficient credits to charge a fee |
| 409 | CONFLICT | Fee already charged or in an invalid state |
| 500 | INTERNAL_ERROR | Server-side failure — contact support |
Explore the reference, connect Claude via MCP, or download the OpenAPI spec.