Traders - PolyTape

Base: https://api.polytape.io/api/agent/v1 {trader} accepts a 0x wallet, a polymarket.com profile URL, or a display name.

Depth is plan-gated. Basic Intelligence reaches a trader’s 5 most-recent markets; Pro and Max reach the full record. Basic is additionally capped at 3 distinct wallets per UTC day. See Plans & limits.

`GET /traders/{trader}`

The career card, blending the on-chain archive with Polymarket’s own profile. Cache-Control: no-store.

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

{
  "trader": { "wallet": "0x…", "name": "GoingInsolvent" },
  "card": {
    "markets_total": 8305,
    "resolved_total": 8305,
    "winrate": 0.5624,
    "volume_usd": 5780817.7,
    "first_seen": 1778776327,
    "last_seen": 1783189768,
    "avg_entry_price": 0.49,
    "avg_win_usd": 5.6,
    "avg_loss_usd": -10.0,
    "open_value_usd": 0.0,
    "open_markets": 0,
    "unmarked_markets": 0,
    "marked_at": null
  },
  "polymarket": {
    "pnl": 61240.0,
    "pnl_realized": 55010.0,
    "pnl_unrealized": 6230.0,
    "portfolio_value": 12400.0,
    "peak": 71000.0,
    "low": -3400.0,
    "max_drawdown": 42000.0,
    "profile_image": "https://…",
    "as_of": 1783200000
  }
}

polymarket.pnl is THE P/L — Polymarket’s model, realized + unrealized, full account history including pre-V2. If the upstream is down, polymarket becomes {"status": "pm_offline"}, the card still serves, and only then does it carry the archive’s realized career_pnl_usd / pnl_marked_usd as the fallback voice. card.avg_entry_price is the average cost per token across all buys — the trader’s break-even winrate, token-weighted. It is not the price they usually click. avg_win_usd / avg_loss_usd are per-resolved-market averages, and one blowup skews them.

avg_entry_price, avg_win_usd, and avg_loss_usd are absent or null until the career-stats rollup has populated a trader. Treat missing as “unavailable”, never as zero.winrate is null when nothing has resolved. An unknown-but-valid wallet returns an honest zeroed card, not a 404.

Full doctrine: Reading the numbers.

`GET /traders/{trader}/top-markets`

The trader’s standout markets in one scan — the whale drill-down the recency-only markets list cannot do.

Query	Type	Default	Notes
`n`	int	`5`	per slice; clamps 1–20

{ "trader": {…},
  "top_wins":    [ <market row>, … ],
  "top_losses":  [ … ],
  "most_traded": [ … ],
  "top_volume":  [ … ],
  "note": "wins/losses rank realized pnl over RESOLVED markets only" }

Each row uses the markets-list shape below. Uncached, since open markets shift. Keep n modest on 100k-market makers — they sit near the heavy-query timeout (504 query_timeout).

`GET /traders/{trader}/markets`

Recency-ordered markets, one row each.

Query	Type	Notes
`cursor`	string	opaque; pass back `next_cursor`
`limit`	int	caps the page (default ~200) — pass a smaller one

Each row: condition_id, title, outcome, resolved, winner, last_traded_at, trader_last_action (BUY/SELL), last_price, fills_count, pnl_usd, open, volume_usd. Open rows also carry market_value_usd and pnl_marked_usd.

For extremes use /top-markets, never paging. This list is recency-ordered only by design — a 40,000-market bot has no “biggest win” on page one.

`GET /traders/{trader}/markets/{condition_id}/summary`

The computed stat block. Prefer this over raw events. No arrays.

{
  "market": { "condition_id": "0x…", "title": "…", "outcome": "Up", "outcome2": "Down",
              "resolved": true, "winner": "Down", "pnl_usd": -21.96, "open": false },
  "summary": {
    "fills_count": 148, "buy_count": 148, "sell_count": 0,
    "buy_usd": 360.85, "sell_usd": 0.0, "avg_entry_price": 0.3302,
    "size_p50_usd": 2.5, "size_p90_usd": 4.15, "size_max_usd": 4.85,
    "first_fill_ts": 1783188908, "last_fill_ts": 1783189141, "hold_seconds": 233,
    "usd_share_first_tenth": 0.0, "usd_share_last_tenth": 0.4145,
    "pnl_usd": -21.96, "roi": -0.0609, "open": false, "won": false,
    "sides": [
      { "token_side": 1, "outcome": "Up", "buy_count": 89, "sell_count": 0,
        "buy_usd": 1820.0, "sell_usd": 0.0, "avg_entry": 0.48, "net_tokens": 3790.0 },
      { "token_side": 2, "outcome": "Down", "avg_entry": 0.55 }
    ]
  },
  "trader": { "wallet": "0x…", "name": "GoingInsolvent" }
}

Field	Meaning
`avg_entry_price`	UP-space VWAP of the trader’s buys in this market
`sides[].avg_entry`	the same idea in the token’s own frame — what they paid
`usd_share_first_tenth` / `_last_tenth`	fraction of their USD placed in the first / last 10% of the market’s whole traded window. Near-zero first + high last = a late piler.
`roi`	pnl ÷ buy notional — meaningless for split-sellers

Resolved markets are immutable and ETag’d — send If-None-Match for a 304.

`GET /traders/{trader}/markets/{condition_id}`

The sampled market chart in one call — no cursor, no tick flood.

Query	Type	Default	Notes
`points`	int	`300`	target count; clamps 20–600, snapped to the fidelity ladder
`from_ts` / `to_ts`	int	—	epoch seconds; zoom a window
`resolution`	int	—	force a bucket size in seconds (snapped)
`raw`	bool	`false`	verbatim keyset tick paging instead

{
  "market": { "condition_id": "0x…", "title": "…", "outcome": "Up", "outcome2": "Down",
              "resolved": true, "winner": "Up", "pnl_usd": 81.08, "open": false },
  "trader": { "wallet": "0x…", "name": "GoingInsolvent" },
  "series": { "from_ts": 1783189500, "to_ts": 1783189800, "fidelity": 1,
              "points": [ [1783189500, 0.5088, 0.47, 0.51], … ] },
  "fills":  [ { "ts": 1783189505, "side": "BUY", "price": 0.48, "token_side": 2,
                "outcome": "Down", "size_tokens": 5.0, "usd": 2.6 }, … ]
}

points are [ts, last, lo, hi], UP-normalized. Draw (lo + hi) / 2 — every value is a real traded level; the server never emits a computed price.
Omit from_ts / to_ts for the title-anchored default window (a “2:25–2:30PM ET” market opens at the title’s start).
fills is the trader’s complete fill set, always present, each carrying token_side and outcome.

raw=1 returns the old verbatim contract instead: ticks: [{ts, price}] plus window / cursor / limit keyset paging. Raw ticks duplicate about 36×, so this is the export path. For a chart you want the sampled default.

`GET /traders/{trader}/markets/{condition_id}/tape`

The whole market as a change-compressed per-second tape in one gzipped response (Content-Encoding: gzip), uncapped — for the interactive TradingView template.

{ "market": {…}, "trader": {…}, "tape": [ [ts, last, lo, hi], … ] }

Rows are UP-normalized and emitted only when a second’s (last, lo, hi) differs from the previously emitted second. A 53-day market is roughly 27,000 rows / ~150KB gzipped, not millions. Do all bucketing and the band-mid walk client-side.

Fine for a file or a browser; too big for a chat artifact. For chat, use the sampled endpoint above with points=120.

There is no MCP tool for this endpoint — it is REST-only.

`GET /traders/{trader}/pnl-series`

Polymarket’s cumulative-P/L series for the career equity curve.

Query	Values	Default
`window`	`24h` \| `7d` \| `30d` \| `ytd` \| `1y` \| `all`	`all`

{ "trader": {…}, "window": "all", "model": "polymarket_profile",
  "series": [ [1733000000, 0.0], [1733086400, 152.4], … ],
  "peak": 231000.5, "low": -12400.2, "max_drawdown": 88211.0,
  "as_of": 1752710000 }

Drawdown is a one-line derivation the equity template does for you: dd[i] = p[i] − running_max. Degrades to {"status": "pm_offline"} if the upstream is down.

`GET /traders/{trader}/fills`

Cross-market fills since a timestamp — the monitoring primitive. Any wallet, no live-slot cost, freshness bounded by the archive pipeline (minutes).

Query	Type	Notes
`since`	int	epoch seconds
`cursor`	string	pass back `next_cursor`
`limit`	int	cap it — a full page is ~10–15k tokens

Each fill: {ts, condition_id, title, side, price, token_side, outcome, size_tokens, usd}. Record the last fill’s ts and pass it back as since next poll, so you only pull what is new. Poll on a minutes cadence — see Monitor a wallet.

​GET /traders/{trader}

​GET /traders/{trader}/top-markets

​GET /traders/{trader}/markets

​GET /traders/{trader}/markets/{condition_id}/summary

​GET /traders/{trader}/markets/{condition_id}

​GET /traders/{trader}/markets/{condition_id}/tape

​GET /traders/{trader}/pnl-series

​GET /traders/{trader}/fills

`GET /traders/{trader}`

`GET /traders/{trader}/top-markets`

`GET /traders/{trader}/markets`

`GET /traders/{trader}/markets/{condition_id}/summary`

`GET /traders/{trader}/markets/{condition_id}`

`GET /traders/{trader}/markets/{condition_id}/tape`

`GET /traders/{trader}/pnl-series`

`GET /traders/{trader}/fills`