> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polytape.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP tools

> All 13 PolyTape MCP tools and the crack_this_trader prompt — signatures, what each returns, and when to reach for it.

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.

<Steps>
  <Step title="whoami">Know your budget before you spend it.</Step>
  <Step title="get_trader_card">The career line. Every trader analysis starts here.</Step>
  <Step title="get_top_markets">The biggest wins, worst losses, most-traded — one scan.</Step>
  <Step title="get_market_summary">The computed read on the 2–3 revealing markets.</Step>
  <Step title="get_market_events">Only if a summary looks strange — or to chart it.</Step>
</Steps>

***

## 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.

<Warning>
  `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](/concepts/pnl#avg-entry-price-two-different-stats-one-name).
</Warning>

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.

<Warning>
  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`.
</Warning>

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:

```json theme={null}
"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).

<Note>
  `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`](/rest/traders#get-traders-trader-markets-condition-id-tape)
  — there is no MCP tool for it.
</Note>

**\~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](/guides/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.

<Note>
  The MCP tool takes **only** `wallet`. The REST endpoint
  [`GET /tapes`](/rest/tapes#get-tapes) additionally accepts `limit` — reach for
  REST if you need to cap a large library.
</Note>

### `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 `StreamEvent`s 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:

```text theme={null}
Use the crack_this_trader prompt on GoingInsolvent.
```

<Tip>
  For a looser, conversational read, use the natural
  [starter prompt](/quickstart#the-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.
</Tip>