MCP tools - PolyTape

Thirteen tools and one prompt. Every tool call spends 1 request; tools/list and fetching the prompt spend nothing. The golden path: start cheap, drill down only when a summary raises a question.

whoami

Know your budget before you spend it.

get_trader_card

The career line. Every trader analysis starts here.

get_top_markets

The biggest wins, worst losses, most-traded — one scan.

get_market_summary

The computed read on the 2–3 revealing markets.

get_market_events

Only if a summary looks strange — or to chart it.

Orientation

`whoami()`

Your plan (Basic Intelligence | Pro Intelligence | Max Intelligence), rate limits, usage this window and this day/month, and which key is calling. Call it first. ~70 tokens.

`list_popular_traders()`

The curated popular-trader shelf: wallets, display names, and how many people are watching each right now. Good for “who should I look at?” These stream without holding any of your live slots. ~50–200 tokens.

Trader analysis

`get_trader_card(trader)`

Career stats from the on-chain archive, blended with Polymarket’s own profile stats. Start every trader analysis here. ~120 tokens.

Argument	Type	Notes
`trader`	string	0x wallet, polymarket.com profile URL, or display name

The headline is polymarket.pnl — Polymarket’s own model (realized + unrealized, full account history including pre-V2): {pnl, pnl_realized, pnl_unrealized, portfolio_value, peak, low, max_drawdown, profile_image, as_of}. Quote it as the trader’s profit. The archive card block carries what Polymarket’s API does not: markets_total, resolved_total, winrate, volume_usd, first_seen, last_seen; the career averages avg_entry_price, avg_win_usd, avg_loss_usd; and the position facts open_value_usd, open_markets, unmarked_markets, marked_at. These cover the V2 era until the v1 backfill.

card.avg_entry_price is the average cost per token across all buys — i.e. the trader’s break-even winrate, not “the price they usually pay”. It is token-weighted, so cheap-token volume drags it well below their typical displayed entry. Compare it against winrate to price the edge. See Reading the numbers.

If Polymarket’s upstream is down, the block degrades to {"status": "pm_offline"} and the rest of the card still serves — and only then does the card carry the archive’s realized career_pnl_usd / pnl_marked_usd as the fallback voice. An unknown-but-valid wallet returns an honest zeroed card.

`get_top_markets(trader, n=5)`

The trader’s standout markets in one scan: top_wins and top_losses (realized P/L, resolved markets only), most_traded (by fills), and top_volume. Each is a list of market rows. ~1–2k tokens.

Argument	Type	Default	Notes
`trader`	string	—	wallet, URL, or name
`n`	int	`5`	per slice; clamps 1–20

This is the whale drill-down. The recency-ordered markets list cannot sort, so this is how you find a 40,000-market bot’s biggest win. Keep n modest on mega-makers — they sit near the heavy-query timeout.

`list_trader_markets(trader, cursor=None, limit=None)`

The trader’s markets, most recent first, one row per market with pnl/outcome/last-action/fill count. No arrays. Paged.

Argument	Type	Notes
`trader`	string	wallet, URL, or name
`cursor`	string	opaque; pass back the response’s `next_cursor`
`limit`	int	pass a small one (e.g. 20)

Open (unresolved) rows also carry market_value_usd and pnl_marked_usd; resolved rows are final.

A full page is ~35k tokens over MCP. limit: 20 is ~2k. Always pass it.Use this for recent activity, never for finding extremes — that is get_top_markets.

Depth is plan-gated: Basic Intelligence sees the 5 most-recent markets, Pro and Max the full history.

`get_market_summary(trader, market)`

The workhorse. The computed read on one trader + market, with no arrays. ~250 tokens.

Argument	Type	Notes
`trader`	string	wallet, URL, or name
`market`	string	`0x…` 64-hex condition id

Returns fill/buy/sell counts and notionals, avg_entry_price (the UP-space VWAP of buys within this market), the size distribution (size_p50_usd / size_p90_usd / size_max_usd), hold_seconds, the share of money placed in the first and last tenth of the market’s traded window (early opener vs late sniper), pnl_usd / roi / won when resolved, and a per-token sides block:

"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 }
]

avg_entry inside sides is in the token’s own frame — what they paid — unlike the UP-space top-level number. The sides block is how you see a two-sided scalper at a glance. Reach for this before raw events.

`get_market_events(trader, market, ...)`

One call returns the whole chart, sampled.

Argument	Type	Default	Notes
`trader`	string	—	wallet, URL, or name
`market`	string	—	condition id
`points`	int	`300`	target point count; clamps 20–600. Ask 120 for chat.
`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
`window` / `cursor` / `limit`	—	—	only meaningful with `raw=true`

Response: market (with outcome, outcome2, pnl_usd, open, winner), trader, a decimated series ({from_ts, to_ts, fidelity, points: [[ts, last, lo, hi], …]}, UP-normalized), and the trader’s complete fills ({ts, side, price, token_side, outcome, size_tokens, usd}). Draw the line at (lo + hi) / 2 — every one of those values is a real traded level. Overlay fills as BUY-up / SELL-down markers colored by token_side, sized by usd. If resolved, winner pins the end (token-1 win → 1.00, else 0.00).

raw=1 returns the old verbatim tick pages (ticks + cursor). Raw ticks duplicate about 36×, so this is the export path, not the chart path.For a full-tape interactive chart, fetch the whole change-compressed tape from the REST endpoint GET /traders/{trader}/markets/{condition_id}/tape — there is no MCP tool for it.

~2.5–3k tokens REST / ~5–6k MCP at 300 points.

`get_pnl_series(trader, window="all")`

Polymarket’s cumulative-P/L series for the career equity curve. ~1–2k tokens.

Argument	Type	Default	Notes
`trader`	string	—	wallet, URL, or name
`window`	string	`"all"`	`24h` \| `7d` \| `30d` \| `ytd` \| `1y` \| `all`

Returns {trader, window, model, series: [[ts, pnl_usd], …], peak, low, max_drawdown, as_of}. Drawdown is a one-line derivation the equity template does for you: dd[i] = p[i] − running_max. Degrades to a pm_offline message if the upstream is down.

`get_recent_fills(trader, since=None, cursor=None, limit=None)`

The monitoring primitive. The trader’s fills across all their visible markets since a timestamp, chronological, paged — and it holds no live slot.

Argument	Type	Notes
`trader`	string	wallet, URL, or name
`since`	int	epoch seconds
`cursor`	string	pass back `next_cursor`
`limit`	int	cap it — a full page is ~10–15k tokens

Each fill carries condition_id, title, side, price, size_tokens, usd, token_side, and outcome — enough to fingerprint a trader in one call. Freshness tracks the archive pipeline (minutes).

Charts

`get_chart_template(kind="market", format="html", theme="night")`

A ready-to-fill PolyTape chart template, returned as file text. This exists because a connector cannot always fetch the skill’s web files.

Argument	Values	Notes
`kind`	`market` \| `market-tape` \| `equity`	see below
`format`	`html` \| `python`	python = matplotlib (`market`, `equity` only)
`theme`	`night` \| `day`	day flips the room; the tube stays dark

market — the self-contained SVG template. No CDN, no external fonts, no fetches. The default a connector agent should use — it renders inside a chat artifact or a strict CSP.
market-tape — the TradingView full-tape template (html only). Needs the unpkg CDN and ~200KB, so file or browser contexts only.
equity — the career equity-curve template.

Returns {kind, format, theme, content}. Costs 1 request — it is a normal tool call, no exemptions. Fetching the same template from the web instead is free. Full spec: Plotting.

Your tapes

Recorded watch sessions from the PolyTape web app. These are yours — scoped to your account.

`list_tapes(wallet=None)`

Your cassette library: recorded market sessions with observed PnL (PNL · AS TAPED), outcome, duration, and tick/fill counts. wallet narrows to one trader’s folder.

The MCP tool takes only wallet. The REST endpoint GET /tapes additionally accepts limit — reach for REST if you need to cap a large library.

`get_tape_summary(tape_id)`

One tape’s metadata: market, grade, PNL AS TAPED, duration, tick and fill counts. Cheap — prefer it over raw events.

`get_tape_events(tape_id, cursor=None, types=None, limit=None)`

Raw StreamEvents from a tape, paged.

Argument	Type	Notes
`tape_id`	string	—
`cursor`	string	pass back `next_cursor`
`types`	string[]	e.g. `["fill"]`
`limit`	int	events per page — pass a small one

Expensive relative to the summary; page deliberately. Oversized tapes are pointed at a download URL instead.

Prompt

`crack_this_trader(trader)`

Not a tool — a prompt template, and fetching it spends no budget. It scripts the full analyst workflow — whoami → card → top-markets → the revealing few → summaries → verdict, closing with a chart if your interface renders one — and asks for a terse, numbers-only verdict in the PolyTape voice. Invoke it from your client’s prompt picker, or paste it. In Claude Code:

Use the crack_this_trader prompt on GoingInsolvent.

For a looser, conversational read, use the natural starter prompt instead. It steers the agent toward the card and the biggest markets, then lets it roam the tools and ends the turn open rather than on a fixed verdict format.

​Orientation

​whoami()

​list_popular_traders()

​Trader analysis

​get_trader_card(trader)

​get_top_markets(trader, n=5)

​list_trader_markets(trader, cursor=None, limit=None)

​get_market_summary(trader, market)

​get_market_events(trader, market, ...)

​get_pnl_series(trader, window="all")

​get_recent_fills(trader, since=None, cursor=None, limit=None)

​Charts

​get_chart_template(kind="market", format="html", theme="night")

​Your tapes

​list_tapes(wallet=None)

​get_tape_summary(tape_id)

​get_tape_events(tape_id, cursor=None, types=None, limit=None)

​Prompt

​crack_this_trader(trader)

Orientation

`whoami()`

`list_popular_traders()`

Trader analysis

`get_trader_card(trader)`

`get_top_markets(trader, n=5)`

`list_trader_markets(trader, cursor=None, limit=None)`

`get_market_summary(trader, market)`

`get_market_events(trader, market, ...)`

`get_pnl_series(trader, window="all")`

`get_recent_fills(trader, since=None, cursor=None, limit=None)`

Charts

`get_chart_template(kind="market", format="html", theme="night")`

Your tapes

`list_tapes(wallet=None)`

`get_tape_summary(tape_id)`

`get_tape_events(tape_id, cursor=None, types=None, limit=None)`

Prompt

`crack_this_trader(trader)`