Polymarket Mock Trading API

REST quickstart

Live market prices are public — no key required:

# Live CLOB price — public, no key required
curl "https://polytrackers.com/api/clob/price?conditionId=<CONDITION_ID>&outcome=YES"

Direct REST signal reads authenticate with a paid Agent API Key. Free Agent API Keys use MCP read tools instead of the REST bearer endpoint for anomaly signals:

# Paid REST signal read (Pro/Elite Agent API Key, signals:read scope)
curl "https://polytrackers.com/api/anomalies?limit=50" \
  -H "Authorization: Bearer ptk_..."

Generate a typed client from the machine-readable contract at /api/openapi.json.

// Node 18+ (global fetch). Paid Agent API Key, signals:read scope.
const res = await fetch(
  "https://polytrackers.com/api/anomalies?limit=50",
  { headers: { Authorization: `Bearer ${process.env.POLYTRACKERS_API_KEY}` } },
);
if (!res.ok) throw new Error(`PolyTrackers ${res.status}`);
const { data } = await res.json();
console.log(data); // Paid REST response; tier shaping still applies after auth.

# Python 3 (requests). Paid Agent API Key, signals:read scope.
import os, requests

res = requests.get(
    "https://polytrackers.com/api/anomalies",
    params={"limit": 50},
    headers={"Authorization": f"Bearer {os.environ['POLYTRACKERS_API_KEY']}"},
    timeout=15,
)
res.raise_for_status()
print(res.json()["data"])  # Paid REST response; tier shaping still applies after auth.

The programmatic mock-trade flow (MCP)

Placing a simulated order is an agent action, so it runs over the MCP server at https://polytrackers.com/api/mcp rather than a REST body. See the MCP server setup guide for client config. The tool sequence:

1. pt_mock_wallet_create (Elite (agent:full))
   Create a fresh virtual wallet. Elite agent:full keys can call this committed mock-write tool. (Free accounts get one $10,000 mock wallet, created in the browser at /mock-trading; Free and Pro agent keys cannot call this write tool.)
2. pt_mock_price_get (Free (signals:read))
   Fetch the live YES/NO price for the market you want to test against, sourced from Polymarket's own data.
3. pt_mock_trade_place (Elite (agent:full))
   Place a simulated order sized by notional cost in USD/USDC against the live price. No real capital moves; this committed mock write needs an Elite agent:full key.
4. pt_mock_analytics_get (Free (signals:read))
   Read the wallet's realized/unrealized P&L summary to score the strategy.
5. pt_mock_wallets_list (Free (signals:read))
   Enumerate the caller's mock wallets to compare separate strategies over time.

The mock write tools (pt_mock_wallet_create, pt_mock_trade_place) require the agent:full scope, which generated Agent API Keys currently provide only on Elite. On the Free tier the read tools work with your key, and you place mock trades in the browser at /mock-trading.

The free-tier path

• Register at /register — free, no card required.
• One $10,000 virtual mock wallet per free account.
• One Agent API Key scoped to signals:read, rate-limited to 10 requests/min per tool and 200 requests/day shared across all tools.
• Public price reads over REST and authenticated read tools over MCP; place mock trades in the app. Free ptk_ keys do not call the paid REST /api/anomalies bearer endpoint directly. Upgrade to Elite for agent-driven committed mock writes (agent:full).

Why mock-first for copy trading

Before you mirror a whale with real funds, validate them on paper. Pull a trader or whale profile, mirror their positions into a mock wallet, and let the strategy play out against live odds. If the simulated P&L holds up across enough resolved markets, you have evidence — not a hunch — before switching the same roster to live copying. Poly-alternatives that copy with real funds from the first fill give you no such dry run.

Rate limits

REST and MCP request-level throttles include a Retry-After header and a structured JSON body. MCP tool-level throttles return JSON-RPC retry metadata such as retry_after_seconds and _meta.rate_limit instead; back off from the signal your client receives. The full contract lives in the API docs.

Going live

Mock trading is free. When a strategy earns real capital, you can flip the same tracked roster to live copying, which mirrors trades with real funds from your connected wallet. Live copies carry a 0.25% PolyTrackers fee per trade, applied through Polymarket's builder-fee mechanism and separate from any fees Polymarket itself charges. Paper (mock) copy trading remains free. Real execution over the API additionally requires a trade:execute key, or an Elite agent:full key, and passes through a bound pt_trade_preflight token before pt_trade_execute.

Frequently asked questions

Related guides

• Polymarket paper trading (browser walkthrough)
• Connect AI agents with the Polymarket MCP server
• Build with the Polymarket API
• PolyTrackers API docs