# Polyman Agent API — Full Reference

Polyman (polyman.fun) is a copy-trading platform for Polymarket prediction markets. This file is the expanded machine-readable reference for the Polyman Agent API (REST) and the hosted MCP server.

Base URL: https://api.polyman.fun
OpenAPI spec: https://api.polyman.fun/v1/openapi.json
MCP endpoint (Streamable HTTP): https://api.polyman.fun/mcp
Human docs: https://www.polyman.fun/developers

## Authentication

- Header: `Authorization: Bearer pm_live_...` (fallback: `X-API-Key`).
- Keys are created at polyman.fun → Portfolio → Developer. The raw key is shown once; only its SHA-256 hash is stored.
- Scopes: `read` (all GET endpoints), `trade` (order placement, 2FA-gated at creation, mandatory caps), `trade:paper` (simulated orders only).
- Rate limits: read 120/min/key, orders 20/min/key, unauthenticated MCP 30/min/IP. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; 429s carry `Retry-After`.
- Errors are machine-readable everywhere: `{"error": {"code": "...", "message": "...", "retryable": true|false}}`. Branch on `code`.

## Units

- All prices are 0-1 probability scale (0.65 = 65¢ = 65% implied probability). MCP tools also return `*_cents` companions.
- All values (`entry_value`, `position_value`, `pnl`, `volume`, caps) are USD.
- Timestamps are Unix seconds unless a field says otherwise.

## REST endpoints (scope: read)

GET /v1/markets?category=&sort=&limit=
  Active Polymarket markets. category: politics|sports|crypto|finance|culture|weather. sort: volume|ending_soon. limit ≤ 100.
  Returns {markets: [{question, slug, condition_id, yes_price, no_price, outcomes: [{outcome, token_id, price}], total_volume, liquidity, expiry_date, is_binary}]}.

GET /v1/markets/{slug}
  One market by slug (slug is the canonical lookup key). Same market shape as above.

GET /v1/signals?category=&limit=
  Whale signals — pre-built from realtime on-chain fill data, rebuilt every 60s. Only profitable positions ≥ $500 appear.
  Returns {signals: [{trader_address, trader_name, ai_score, market_question, market_id, token_id, outcome, outcome_index, entry_value, position_value, entry_price, current_price, trending_score, category, ...}]}. NOTE: market_id IS the conditionId — pass it as condition_id when placing orders.

GET /v1/traders?period=&category=&limit=
  AI-scored trader leaderboard (rebuilt every 2h). period: DAY|WEEK|MONTH|ALL. category: overall|politics|sports|crypto|finance|culture.
  Returns {traders: [{address, name, rank, pnl, volume, win_rate, ai_score, ai_decision, category_scores, best_category, ...}]}.

GET /v1/traders/{address}?period=
  Full trader profile. PnL matches Polymarket's own profile display (the public leaderboard API does not). Includes AI score breakdown, category grades, open + closed positions.

GET /v1/prices?token_ids=id1,id2
  Batch CLOB midpoints, ≤ 100 token IDs. Returns {prices: {token_id: "0.65"}}. ~1s server cache — safe to poll.

GET /v1/me
  Key introspection: scopes, caps {max_order_usd, daily_cap_usd, daily_spent_usd, daily_remaining_usd}, rate limits, wallet address. Call once at startup to self-configure.

## Order endpoints (scope: trade)

POST /v1/orders — body {token_id, condition_id, side, amount_usd, outcome_index, simulate (default true), idempotency_key}.
  Simulate-by-default: live execution only with explicit simulate=false. Hard caps enforced server-side before execution (per-order and rolling daily). Idempotent: replaying the same idempotency_key returns the stored response and never double-executes.
POST /v1/orders/sell — mirror of the sell path with the same caps and idempotency.
POST /v1/orders/preview — 3-layer price estimate (orderbook walk for > $25), no trade scope needed.

There are NO withdrawal, transfer, key-export, or settings endpoints on the Agent API — by design. Funds can only leave via the human app with 2FA.

## MCP tools

Read-only (work unauthenticated at 30/min/IP; 120/min with a key):
- search_markets(query, limit) — full-text market search
- list_markets(category, sort, limit)
- get_market(slug) — includes outcome token_ids for get_prices/orders
- get_prices(token_ids) — {prices, prices_cents}
- list_whale_signals(category, limit) — the 60s whale feed
- list_top_traders(period, category, limit) — AI scores + category grades
- get_trader(address, period)
- get_api_status() — call first: auth state, scopes, caps, rate limits

Trade-scoped (require a `trade` key; confirm=false returns a simulation):
- preview_order, place_order, sell_position, get_portfolio, list_positions

## Webhooks

Configure per key: PUT /agent/keys/{id}/webhook {webhook_url} (JWT-authed, human app) — returns a whsec_ signing secret once.
Events pushed as JSON POST {event, data}:
- order.filled — after a live agent order (buy/sell) executes, sent to the key that placed it.
- whale.signal — new whale signals as the 60s feed rebuild discovers them.
Verify with the X-Polyman-Signature header: "sha256=" + hex(HMAC-SHA256(secret, raw_body)). X-Polyman-Event carries the type.

## MCP client config

{
  "mcpServers": {
    "polyman": {
      "type": "http",
      "url": "https://api.polyman.fun/mcp",
      "headers": {"Authorization": "Bearer pm_live_YOUR_KEY"}
    }
  }
}

Claude Code: claude mcp add --transport http polyman https://api.polyman.fun/mcp

## Safety model

1. Trade keys are 2FA-gated at creation and carry mandatory caps: ≤ $1,000/order, ≤ $5,000/day (launch ceilings).
2. Orders simulate by default.
3. Daily spend enforced in Redis before execution; order writes idempotent.
4. No fund-egress endpoints exist on this API surface.
5. Keys are revocable at any time at polyman.fun.

## Revenue model

Free API. Orders carry the Polyman builder code (bytes32 `builder` field in the signed CLOB v2 order struct); Polymarket collects a standard builder fee at match time. No separate API charge.