REST overview - PolyTape

https://api.polytape.io/api/agent/v1

Every read is a GET. All responses are JSON. Authenticate every request with a header:

Authorization: Bearer td_live_...

Full machine schema: /api/agent/v1/openapi.json.

Conventions

Identifiers

{trader} accepts a 0x wallet, a polymarket.com profile URL, or a display name (e.g. GoingInsolvent). Responses always echo the canonical wallet and name.A 0x-prefixed string of the wrong hex length is treated as a malformed wallet → 400 invalid_wallet. It never falls through to name resolution.{condition_id} is the 0x… 64-hex market id from the markets list or top-markets.

Units

Timestamps are epoch seconds. Money fields are USD, suffixed _usd. Prices are UP-normalized (0–1) — token 1’s probability.The one exception: resets_at on a wallet_quota verdict is an ISO 8601 UTC string.

Pagination

Cursors are opaque and forward-only. First request: no cursor (optionally since / window to position). Then pass the response’s next_cursor back. When next_cursor is absent or null, you have reached the end.Never hand-craft or mutate a cursor. A malformed one is a clean 400 bad_cursor; a well-formed forged one silently returns page 1 again — safe depth-wise, but you re-pay for data you already have.limit caps a single page and must be ≥ 1 (limit=0 is 400 bad_limit). It is your main token-control knob.

Caching

Resolved market summaries and tapes are immutable and ETag’d — send If-None-Match for a 304.Note that a 304 on a real route still burns a call; it saves you tokens and bandwidth, not quota.The trader card is Cache-Control: no-store.

Plan gates

History depth — Basic Intelligence reaches a trader’s 5 most-recent markets; Pro and Max reach the full record. A market past the window is 403 depth_gated. history_depth in /me is the count (-1 = unlimited).
Trader lookups — Basic Intelligence can pull 3 distinct wallets per UTC day, shared with the dashboard and MCP. The 4th new wallet is 403 wallet_quota.

Both are detailed in Plans & limits.

Orient

`GET /me`

Plan, rate limits, usage this window and this day/month, and which key is calling. Mirrors the MCP whoami tool. Start here. plan is the display name: Basic Intelligence | Pro Intelligence | Max Intelligence.

curl -H "Authorization: Bearer td_live_..." \
  https://api.polytape.io/api/agent/v1/me

{
  "plan": "Pro Intelligence",
  "limits": {
    "rps": 5.0,
    "burst": 60,
    "rpm": 300.0,
    "daily_requests": 0,
    "monthly_requests": 50000,
    "max_keys": 3,
    "live_slots": 3,
    "history_depth": -1
  },
  "usage": {
    "window": { "tokens_remaining": 59.0, "rpm_used": 1 },
    "day":    { "requests": 0,  "cap": 0 },
    "month":  { "requests": 42, "cap": 50000 }
  },
  "key": { "label": "my agent", "last4": "ZLI4" }
}

The call quota has two windows and the governing one is nonzero. A Basic Intelligence caller inverts them: daily_requests: 50, monthly_requests: 0, and usage.day carries the governing count and cap.

`GET /popular`

Curated popular traders with display names and live watching counts. These stream without holding any of your live slots.

{ "traders": [ { "wallet": "0x…", "name": "GoingInsolvent", "watching": 0 } ],
  "count": 2 }

Traders

Cards, markets, summaries, charts, fills, and the equity curve.

Tapes

Your recorded watch sessions.

​Conventions

​Plan gates

​Orient

​GET /me

​GET /popular