Turn your words into trades with Polyman’s MCP Server
Ask. Analyze. Simulate. Execute. All inside your favorite AI interface, powered by Polyman’s Agent API and attributed to your builder code on-chain.
Free · read-only MCP works without an account · orders carry our builder code
Cursor
Claude
ChatGPT
VS CodeI'll check the last hour of whale flow on that market first.
Whales are net +$482K YES in the last hour. Placing the order:
Research, decide, and trade in one flow
Ask your agent to scan whale signals, check a trader’s record, and place an order — all in one interface. No tab-hopping, no scripts.
Full visibility into every AI-driven trade
Every order simulates by default and returns the full fill preview — price, shares, slippage — before anything touches the book.
Natural-language market intelligence
Live CLOB prices, whale trades rebuilt every 60 seconds from realtime on-chain fills, and AI-scored profiles with per-category grades for thousands of traders.
You set the limits, we enforce them
Trade keys carry hard per-order and daily USD caps checked server-side before execution — and there are no withdrawal or transfer endpoints at all.
Prefer raw REST?
The same surface behind the MCP server — versioned JSON, no SDK. Every request carries your API key; orders simulate by default and are hard-capped per key.
View API reference# whale signals (key required)curl -H "Authorization: Bearer pm_live_…" \ https://api.polyman.fun/v1/signals # simulated order (default)curl -X POST https://api.polyman.fun/v1/orders \ -d '{"token_id":"402884…","side":"BUY","amount_usd":25}'API reference
Seven endpoints — the whole read + trade surface. Open one, then toggle the 200 / error response.
GETList markets/v1/markets?category=&sort=&limit=
Active Polymarket markets with parsed outcomes, prices (0–1 scale), 24h volume and liquidity. Filter by category (politics, sports, crypto, finance, culture, weather); sort by volume or ending-soon. ~60s server cache.
curl -H "Authorization: Bearer pm_live_YOUR_KEY" \ "https://api.polyman.fun/v1/markets?category=finance&limit=20"
// example response
{
"markets": [
{
"condition_id": "0xbf57190d…597f2ed",
"slug": "will-the-fed-cut-rates-in-september",
"question": "Will the Fed cut rates in September?",
"yes_price": 0.658,
"no_price": 0.342,
"total_volume": 4821034.22,
"liquidity": 218500.0,
"expiry_date": "2026-09-18T00:00:00Z",
"outcomes": [
{ "outcome": "Yes", "token_id": "402884…8930", "price": 0.658 },
{ "outcome": "No", "token_id": "715509…1123", "price": 0.342 }
],
"is_binary": true
}
],
"total": 20
}GETWhale signals/v1/signals?category=&limit=
What top traders just bought — pre-built from realtime on-chain fill data, rebuilt every 60s. Only profitable positions ≥ $500 appear. Each signal carries the trader, market, entry/current value in USD, and a 0–100 trending score.
curl -H "Authorization: Bearer pm_live_YOUR_KEY" \ "https://api.polyman.fun/v1/signals?category=finance&limit=10"
// example response
{
"signals": [
{
"trader_address": "0x204f…5e14",
"trader_name": "swisstony",
"ai_score": 100,
"market_question": "Will the Fed cut rates in September?",
"market_id": "0xbf57190d…597f2ed",
"token_id": "402884…8930",
"outcome": "Yes",
"entry_value": 448200.0,
"position_value": 482000.0,
"entry_price": 0.598,
"current_price": 0.658,
"trending_score": 98.7,
"category": "finance"
}
],
"has_more": true
}GETTrader intel/v1/traders/{address}?period=
Full trader profile by proxy-wallet address: PnL that matches the Polymarket profile display, win rate, AI score, per-category grades, and open positions. Cached ~5min.
curl -H "Authorization: Bearer pm_live_YOUR_KEY" \ "https://api.polyman.fun/v1/traders/0x204f…5e14?period=MONTH"
// example response
{
"address": "0x204f…5e14",
"name": "swisstony",
"rank": 3,
"pnl": 528410.22,
"win_rate": 99,
"ai_score": 100,
"ai_decision": "TRADE",
"volume": 27840119.0,
"category_scores": { "sports": 96, "finance": 88 },
"best_category": "sports",
"open_positions": [ /* … */ ]
}GETTop traders/v1/traders?period=&category=
AI-scored leaderboard (rebuilt every 2h). period = DAY | WEEK | MONTH | ALL. Filter/rank by category grade. Each trader has an ai_score, ai_decision (TRADE/CAUTION/AVOID) and per-category grades.
curl -H "Authorization: Bearer pm_live_YOUR_KEY" \ "https://api.polyman.fun/v1/traders?period=MONTH&category=sports"
// example response
{
"traders": [
{
"rank": 1,
"address": "0xf031…c80c",
"name": "BreakTheBank",
"pnl": 510600.0,
"volume": 18200000.0,
"win_rate": 94,
"ai_score": 100,
"ai_decision": "TRADE",
"best_category": "sports"
}
],
"total": 100
}GETBatch prices/v1/prices?token_ids=a,b
Live CLOB midpoint prices for up to 100 outcome token IDs (comma-separated). Prices are 0–1 probability scale; multiply by 100 for cents. ~1s cache — safe to poll.
curl -H "Authorization: Bearer pm_live_YOUR_KEY" \ "https://api.polyman.fun/v1/prices?token_ids=402884…8930,715509…1123"
// example response
{
"prices": {
"402884…8930": "0.659",
"715509…1123": "0.341"
}
}POSTPlace order/v1/orders
Places a builder-attributed market BUY. SIMULATES by default and returns a fill preview; pass "simulate": false to execute live. Requires the trade scope; per-order and daily USD caps are enforced server-side, and idempotency_key makes retries safe.
curl -X POST https://api.polyman.fun/v1/orders \
-H "Authorization: Bearer pm_live_YOUR_KEY" \
-d '{"token_id":"402884…8930",
"condition_id":"0xbf57190d…597f2ed",
"side":"BUY","amount_usd":25,
"idempotency_key":"a1b2c3"}'// example response (simulate=default)
{
"simulated": true,
"status": "simulated",
"side": "BUY",
"token_id": "402884…8930",
"condition_id": "0xbf57190d…597f2ed",
"amount_usd": 25.0,
"estimated_shares": 38.0,
"avg_fill_price": 0.658,
"slippage_pct": 0.1,
"unfilled_amount": 0.0,
"note": "Pass simulate=false to execute live."
}GETPortfolio/v1/portfolio
Cash balance, total position value and open positions for the key owner — sourced from the Polymarket Data API and on-chain reads, never local bookkeeping.
curl -H "Authorization: Bearer pm_live_YOUR_KEY" \ "https://api.polyman.fun/v1/portfolio"
// example response
{
"balance": 12482.10,
"total_value": 13271.70,
"positions": [
{
"market_title": "Will the Fed cut rates in September?",
"outcome": "Yes",
"shares": 1200,
"currentValue": 789.6,
"cashPnl": 186.40
}
]
}Also available: GET /v1/me, GET /v1/positions, POST /v1/orders/sell, POST /v1/orders/preview. Full machine-readable spec at /v1/openapi.json.
Connect the AI tool you use
Pick your client — each shows the exact, working setup. Read-only tools run anonymously; add a key to trade.
Claude CodeTerminal commandAdd --header "Authorization: Bearer pm_live_YOUR_KEY" for 120 req/min and trading.
claude mcp add --transport http polyman https://api.polyman.fun/mcp
Set up in under a minute
Fastest path is Claude Code — one command. For any other client, pick it in Connect above to get the exact config. Read-only works anonymously; add a key when your agent should trade.
claude mcp add --transport http polyman https://api.polyman.fun/mcp # higher limits + trading: --header "Authorization: Bearer pm_live_YOUR_KEY"Frequently asked questions
What is Polyman’s MCP Server?
A hosted Model Context Protocol endpoint at api.polyman.fun/mcp. It lets AI chat apps, CLIs and IDEs read Polyman’s market data and place capped trades using natural language instead of code — nothing to install or run yourself.
How does it work?
The server exposes markets, whale signals, trader intelligence, prices and order tools. Your AI client calls a tool, Polyman runs it against the Agent API, and returns compact JSON your client can display — with prices in both 0–1 and cents so agents never make unit mistakes.
Do I need an account to start?
No, to explore. The MCP read tools — markets, whale signals, trader intelligence, prices — work anonymously at 30 requests/minute per IP. You need a free Polyman account only to mint an API key, which unlocks 120 req/min and, with the trade scope, order placement.
Can my agent lose more than its cap?
No. Per-order and daily USD caps are enforced server-side before an order reaches the book, and there are no margin, transfer or withdrawal endpoints — the maximum loss is the cash the key is allowed to spend, which never leaves your wallet except through the human app with 2FA.
Is it free? How does Polyman make money?
The API is free. Orders carry the Polyman builder code in the signed CLOB order struct, so Polymarket pays a standard builder fee at match time — the same economics as trading in the Polyman app. There is no separate API charge.