developer api · v1.1

Copy-trade Polymarket from any agent, script, or app.

PolyZig exposes a full REST API and a first-party Model Context Protocol server. Mint a scoped pzk_* key from your dashboard, point Claude Desktop or Cursor at /api/mcp, and your agent can discover top traders, start copy configs, monitor PnL, and place orders — with sub-500ms execution.

Mint an API key Open Swagger UI openapi.json AGENTS.md

Built for autonomous agents

Scoped, revocable credentials

Mint API keys from the dashboard with explicit scopes (read:positions, trade:execute, …). Deny-by-default — a handler that lacks scope coverage is unreachable. Revoke any key independently of your account password.

Idempotency on trading writes

Set Idempotency-Key on a trading POST (claim, sell, market order, withdraw, copy-config changes) and we cache the response for 24h — a retried claim or sell on a network blip never double-fires. Two routes deliberately opt out: POST /keys (the one-time secret must not be cached) and POST /mcp (JSON-RPC errors travel in 200 envelopes). See AGENTS.md for the full contract.

Machine-first contracts

Every error has a stable code. Pagination metadata in response headers. Money serialized as decimal strings (*_dec mirror fields). OpenAPI 3.1 spec published at /openapi.json and Swagger UI at /api/docs.

Quick start

1. Mint a key

2. Verify with curl

bash

curl https://api.polyzig.com/api/users/me \
  -H "Authorization: Bearer pzk_live_..."

3. Start mirroring a trader

Always set paper_trading: true on the first run for any new target — watch a session, check PnL, then promote.

bash

# Create a paper-trading copy config for a target wallet
curl -X POST https://api.polyzig.com/api/configs \
  -H "Authorization: Bearer pzk_live_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "target_address": "0xWHALE_ADDRESS",
    "target_name":    "polymarket-whale",
    "size_multiplier": "0.1",
    "paper_trading":   true
  }'

Or skip curl — use MCP

Drop this into Claude Desktop's claude_desktop_config.json (or Cursor's equivalent). Your agent gets the full tool catalogue, scoped to what your key allows.

claude_desktop_config.json

{
  "mcpServers": {
    "polyzig": {
      "type": "http",
      "url": "https://api.polyzig.com/api/mcp",
      "headers": {
        "Authorization": "Bearer pzk_live_..."
      }
    }
  }
}

Auto-discovery

Clients that consult /.well-known/mcp.json pick up the endpoint, transport, and scope list automatically.

Scopes

Default to the minimum scopes your agent needs. A monitoring agent should not have trade:execute; a copy-trading agent should not have wallet:write.

Scope	Grants
`read:account`	Profile, balance, PnL summary
`read:positions`	Open + paper positions
`read:trades`	Trade history and fills
`read:markets`	Market search, open orders, leaderboard data
`trade:execute`	Place orders; create + start + stop copy configs
`trade:cancel`	Cancel resting CLOB orders
`wallet:write`	Claim resolved positions, withdraw, wrap-to-pUSD

MCP tool catalogue

19 first-party tools. The MCP server returns only the subset your key's scopes permit — so an agent doing read-only monitoring doesn't even see the write tools.