---
name: polytape
description: >-
  Read Polymarket trader activity through the PolyTape Data API — a trader's full
  on-chain history, their live stream, and your recorded tapes. Use when you need
  to analyze how a Polymarket trader actually trades, compare two traders, chart a
  market's price-and-fill history, plot a career equity curve, or monitor a wallet's
  new fills. Read-only; works over REST and MCP with one API key.
---

# PolyTape Data API

PolyTape is the trader-intelligence layer for AI agents: every Polymarket trader's
full on-chain history, plus live streams and recorded watch-session "tapes."
This skill is the **read-only data plane** an agent uses to answer questions about
Polymarket traders: their career record, per-market behavior, the price series of a
market, and their recent fills. Everything here is a GET (or an MCP tool call) —
there are no writes and no trading.

## When to use this

- "How does trader X actually trade? What's their edge?" → **crack a trader**
- "Which of these two traders is better / do they overlap?" → **compare traders**
- "What happened in this market — price path and where X got in/out?" → **read a market's tape**
- "Chart this market / show me their career equity curve" → **plot** (`reference/plotting.md`)
- "Has trader X done anything new since I last checked?" → **monitor fills**
- "What are my recorded tapes / what's in one?" → **your tape library**

If the question is about a *live* stream in a browser, that's the PolyTape web app,
not this API. This API serves the recorded and historical read layer.

## Two ways in (same data, same budget)

| Surface | URL | Best for |
|---|---|---|
| **MCP** | `https://api.polytape.io/mcp` | Coding/chat agents (Claude Code, Cursor, claude.ai, opencode). 13 tools + a `crack_this_trader` prompt. |
| **REST** | `https://api.polytape.io/api/agent/v1` | Scripts, cron jobs, anything that curls JSON. |

Both authenticate with the SAME key and draw on the SAME per-user budget. Pick one;
you don't need both. Full schemas: `https://api.polytape.io/api/agent/v1/openapi.json`.

> **After an API update, re-add the connector.** MCP clients cache the tool list, so
> semantic changes to a tool (like `get_market_events` now returning a sampled chart)
> won't reach a client connected before the update until it reconnects.

## Authentication (header only)

    Authorization: Bearer td_live_...

Mint a key in the dashboard → **AI Agents & API → Patch Bay**. The plaintext key is
shown once at mint time. A key is **never** accepted in a query string — header only.
MCP clients may also connect over OAuth (sign in instead of pasting a key) where the
connector supports it. See `reference/auth.md`.

## The tools, and when to reach for each

Start cheap, drill down only when a summary raises a question. The golden path:

1. **whoami** — your plan and remaining budget. Call once at the start.
2. **get_trader_card** (`/traders/{trader}`) — the career line: markets, winrate,
   volume, first/last seen, and the **headline P/L** (see "Reading the numbers").
   Every trader analysis starts here.
3. **get_top_markets** (`/traders/{trader}/top-markets`) — the biggest wins, worst
   losses, most-traded, and top-volume markets in **one scan**. The whale
   drill-down: it answers "biggest win / worst loss" that the recency-only markets
   list can't.
4. **list_trader_markets** (`/traders/{trader}/markets`) — recency-ordered rows, one
   per market. **Pass a small `limit`** (a full page is large). Use it for "what
   have they done lately," not for finding extremes (that's `get_top_markets`).
5. **get_market_summary** (`/traders/{trader}/markets/{cid}/summary`) — the COMPUTED
   read on one market: entry VWAP, buy/sell split, size percentiles, hold time, the
   share of money in the first/last tenth, and a per-token `sides` block. **The
   workhorse** — it answers "how did they trade this?" without any arrays.
6. **get_market_events** (`/traders/{trader}/markets/{cid}`) — one call returns the
   **sampled** price series + the trader's complete fills (each with `token_side` +
   `outcome`). This is the chart in one shot. `raw=1` is the verbatim-tick export.
7. **get_recent_fills** (`/traders/{trader}/fills`) — the monitoring primitive:
   cross-market fills since a timestamp, no live slot held. Poll with `next_cursor`.
8. **get_pnl_series** (`/traders/{trader}/pnl-series`) — Polymarket's cumulative-P/L
   series for the career equity curve (`window=24h|7d|30d|ytd|1y|all`).
9. **get_chart_template** — fetch a ready-made chart template (market, tape, or
   equity) through the connector, for when you can't reach the web files.
10. **list_popular_traders** (`/popular`) — the curated shelf, with wallets + names.
11. **list_tapes / get_tape_summary / get_tape_events** — YOUR recorded tapes.

`{trader}` accepts a **0x wallet**, a **polymarket.com profile URL**, or a **display
name** (e.g. `GoingInsolvent`). Responses always echo the canonical wallet + name.

Full catalog with signatures: `reference/mcp-tools.md`. REST equivalents:
`reference/rest-api.md`. Charts: `reference/plotting.md`.

## Reading the numbers (PnL semantics)

An agent sees three P/L numbers. Quote the right one and label it:

- **`polymarket.pnl` is the HEADLINE.** On the trader card, the `polymarket` block
  carries Polymarket's own model — realized **plus unrealized**, over the trader's
  **full account history including pre-V2**. This is the number the user sees on
  polymarket.com. **Quote it as the trader's profit.** If Polymarket's upstream is
  down the card returns `"polymarket": {"status": "pm_offline"}` and everything else
  still works — fall back to `career_pnl_usd` and say it's the V2-era realized figure.
- **Each market's `pnl_usd` (and the card's `career_pnl_usd`, served only as the
  pm_offline fallback) are realized cash flow only**
  — reconstructed and chain-audited, over the **V2-contract era (~from April 2026)**.
  Use them for per-market analysis and audits. An active trader with a large open
  book reads *more negative* here than the headline, because open money counts as
  spent until resolution.
- **`pnl_marked_usd` is PolyTape's chain-audited approximation** — realized + open
  holdings at the last on-chain trade. Useful as an estimate of a standing position;
  not the headline.
- **The one caveat to state:** the card's counts, winrate, and volume cover the V2
  era until the v1 backfill lands; the headline P/L covers the full account. Say that
  once, then quote the headline with confidence.
- **A handful of arbitrage bots read oddly.** A small class (~dozens) of
  NegRisk-conversion arbitrage accounts have distorted per-token accounting (a
  conversion moves balances without a trade). If a card shows large volume with
  near-zero or nonsensical realized P/L, suspect a conversion-arb bot, not an edge.

Full doctrine (including honest chart labels and the split/merge `roi` caveat):
`reference/plotting.md`. Just don't present any of these as a live account balance.

## Token thrift (read this before you spend)

Payloads vary by three orders of magnitude. Measured, real traders:

| Call | Typical size | Notes |
|---|---|---|
| whoami / card / top-markets / summary | ~70–2k tokens | cheap — lean on these |
| **get_market_events (sampled, ~300 pts)** | **~2.5–3k (REST) / ~5–6k (MCP)** | one call = the whole chart; ask `points=120` for chat |
| get_pnl_series | ~1–2k tokens | the equity curve in one call |
| **list_trader_markets (full 200-row page)** | **~16k (REST) / ~35k (MCP)** | **always pass `limit`** |
| get_recent_fills (full page) | ~10–15k tokens | cap with `limit` |

Two rules that save the most:

- **Prefer summaries over raw arrays.** `get_market_summary` and `get_top_markets`
  already contain sizing, timing, entry pricing, and per-market P/L. Reach for
  `get_market_events` to chart a market or confirm a specific sequence.
- **On MCP, always pass `limit`.** MCP returns each result twice (a text copy and a
  structured copy), so a default `list_trader_markets` page is ~35k tokens. `limit:
  20` turns that into ~2k.

## Budget, rate limits, and the paywall

One budget per user; every key you own draws from it (keys are cables, not extra
quota). Each call pays a token bucket + a per-minute ceiling + a call quota. Basic
Intelligence's quota is DAILY (resets midnight UTC); the paid tiers are MONTHLY:

| Plan | rps | burst | rpm | call quota | history |
|---|---|---|---|---|---|
| Basic Intelligence (free) | 0.5 | 10 | 30 | **50 / day** | 20 most-recent markets |
| Pro Intelligence | 5 | 60 | 300 | **50,000 / month** | full history |
| Max Intelligence | 20 | 200 | 1,200 | **300,000 / month** | full history |

- **Basic Intelligence is a daily taste — 50 calls a day.** A trader "crack" done well
  is ~6–10 calls (a bit more with a chart), so it's enough to try it, not to run a
  workflow. When the quota is spent, the error is written to be **relayed to your
  human**: it names the upgrade and links `https://polytape.io/pricing`. Surface it;
  don't silently retry.
- **History depth is plan-gated.** Basic Intelligence sees a trader's 20 most-recent
  markets; Pro / Max Intelligence see the full record. A market past the window is
  `403 depth_gated` — surface the upgrade, don't retry.
- **On a 429, honor `Retry-After`.** Transient limits (bucket/rpm/`busy`) clear in
  seconds — wait and retry. The daily/monthly cap is the paywall — relay it, don't wait.
- MCP protocol handshakes (connecting, listing tools, fetching a prompt) are **free**.
  Only tool *calls* count. Note: application 4xx errors on real routes *do* burn a
  call, so validate inputs before firing.

Details + etiquette: `reference/budget-and-limits.md`.

## Recipes & charts

Worked, copy-pasteable end-to-end flows with measured call/token costs:
`reference/recipes.md` — crack a trader, compare two traders, read a market's tape,
monitor a wallet, plot a market. The full charting spec + ready-made templates:
`reference/plotting.md`.

## Fast start

MCP (Claude Code):

    claude mcp add --transport http polytape https://api.polytape.io/mcp --header "Authorization: Bearer td_live_..."

Then: *"Use the crack_this_trader prompt on GoingInsolvent."*

REST (curl):

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