limit on lists, summaries before raw events.
Crack a trader
Goal: decode how a trader actually trades and deliver a verdict. Cost: ~6–10 calls, ~3–5k tokens (add ~1 call and ~3–6k for a chart).1
whoami — know your budget
~70 tokens. Call it once at the start of a run so you know what you have.
2
get_trader_card(trader)
(
GET /traders/{trader}) — the career line. Quote polymarket.pnl as
the headline profit.Note anything lopsided: big volume with thin P/L, a winrate far from 50%, or a
career avg_entry_price far from the winrate. That last one is the
break-even winrate — “63% winrate at a 0.47 average entry is an edge; 72% at
0.63 is too.” ~90 tokens.3
get_top_markets(trader, n=5)
(
…/top-markets) — the biggest wins, worst losses, most-traded, and
top-volume markets in one scan. This is where the technique shows, and it
works on a 40,000-market whale that the recency-ordered markets list cannot
sort. Pick the 2–3 most revealing. ~1–2k tokens.Only need recent activity instead? list_trader_markets(trader, limit=25)
(…/markets?limit=25). Pass the limit.4
get_market_summary(trader, market) on each pick
(
…/markets/{cid}/summary) — read avg_entry_price against the outcome,
the size distribution (size_p50_usd vs size_max_usd — steady clips or
conviction lumps?), hold_seconds, the first/last-tenth timing shares (early
opener or late sniper?), and the per-token sides block (two-sided?).
~250 tokens each.5
Only if a summary looks strange: get_market_events(trader, market, points=120)
On that one market — read the sampled price path against the fills. Each
fill carries
token_side and outcome, so two-sided flow is explicit.
~2–3k tokens.6
If your interface renders charts, finish with the flagship market's chart
See Plot the tape below. This is the closing step in the
crack_this_trader prompt.Compare two traders
Goal: which of two is better, and do they overlap? Cost: ~4–6 calls, ~1–2k tokens.1
get_trader_card(A) and get_trader_card(B)
Line up the headlines (
polymarket.pnl), winrate, avg_entry_price, volume,
and tenure. This alone answers “who’s better” at the portfolio level for about
180 tokens.2
get_top_markets(A, n=3) and get_top_markets(B, n=3)
Compare shape: one big winner carrying the record versus many small edges.
And check whether their biggest markets overlap — the same
condition_ids
mean correlated books.3
Optional: get_market_summary on a market they both traded
To see who entered better, or earlier.
Card-only comparison is the cheapest high-signal move on the whole API. Two
~90-token calls settle most “who’s better” questions.
Read one market’s tape
Goal: what happened in a market — the price path, and where a trader got in and out? Cost: ~2–3 calls, ~1–3k tokens.1
get_market_summary(trader, market)
The shape first: entry VWAP, the per-token
sides block, hold time, outcome,
P/L. Usually the whole answer.2
get_market_events(trader, market, points=…)
(
GET /traders/{trader}/markets/{condition_id}) — the sampled
UP-normalized price series plus the trader’s fills, each with token_side
and outcome, so you can place entries on the curve and say which token.Pass from_ts / to_ts to zoom a window; points (default 300) to size the
series.3
Want the whole thing plotted? Go to the plotting recipe.
See below.
series.points are [ts, last, lo, hi] in UP space (0–1); draw (lo + hi) / 2.
A fill’s side is BUY/SELL, usd its notional, and token_side / outcome
name the token.
Monitor a wallet
Goal: follow a trader’s new activity without holding a live stream. Cost: 1 call per poll, ~0.3–15k tokens depending on activity.1
First poll
get_recent_fills(trader, since=<epoch_seconds>, limit=100)
(…/fills?since=…&limit=100).Each fill carries condition_id, title, side, price, size_tokens,
usd, token_side, and outcome — enough to fingerprint a trader (a
two-sided BTC scalper versus a directional bettor) in one call.2
Record the watermark
Save the last fill’s
ts. Next poll, pass it back as since — or page via
next_cursor — so you only pull what is new.3
Poll on a minutes cadence
Not a tight loop. Freshness is bounded by the archive pipeline anyway
(minutes), and a slow poll respects both the rate limits and your call quota.
A Basic Intelligence day of 50 calls burns fast under a tight loop.
limit.
Plot the tape
Goal: a price chart of one market with the trader’s fills in context. Cost: 1 sampled call (~2.5–3k tokens REST / ~5–6k MCP) plus an optional template fetch (1 call).1
get_market_summary(trader, market) first, if you haven't
It tells you whether the market resolved, and its window.
2
One sampled call gives you the whole chart
get_market_events(trader, market, points=300)
(GET /traders/{trader}/markets/{condition_id}) returns market,
trader, a decimated series, and the trader’s complete fills. No
cursor, no tick flood. Ask for points=120 for a chat-sized chart.Deep interactive zoom in a file? Fetch the whole change-compressed tape
from GET /traders/{trader}/markets/{condition_id}/tape — one gzip response,
[[ts, last, lo, hi]] per traded second — and use the tape template.3
Pour it into a template — do not hand-draw
- Chat / connector context → the self-contained SVG:
get_chart_template(kind="market", format="html"). - File / browser context → the TradingView flavor:
chart-market-tape.html.
"__DATA__" placeholder with your JSON. The templates draw
the house grammar for you.4
Label honestly
A resolved market’s
pnl_usd is a result. An open market’s is cash
flow — quote pnl_marked_usd, say “marked”, never “won $X”. Split/merge legs
live inside pnl_usd and never show as fills, so do not reconstruct P/L from
the visible buys and sells, and do not quote roi on a split-seller. Name the
token so a “0.94” reads as “UP at 94¢”.Cost cheat sheet
The single biggest waste is an unbounded
list_trader_markets or
get_recent_fills over MCP (~35k / ~15k tokens). Always pass limit.