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

# Recipes

> Five worked end-to-end flows with measured call and token costs — crack a trader, compare two, read a market, monitor a wallet, plot the tape.

Five flows, measured. Tool names are the MCP form; the REST path in parentheses
is identical data. Costs assume you follow [token thrift](/concepts/token-thrift)
— a small `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).

<Steps>
  <Step title="whoami — know your budget">
    \~70 tokens. Call it once at the start of a run so you know what you have.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="If your interface renders charts, finish with the flagship market's chart">
    See [Plot the tape](#plot-the-tape) below. This is the closing step in the
    `crack_this_trader` prompt.
  </Step>
</Steps>

Then write the verdict. A real example — a trader's biggest market read straight
off one summary (*buy 361k / sell 179k, avg entry 0.54, size p50 $19 vs max
$48.5k, 57% of money in the final tenth, +\$234k / 65% ROI*):

```text theme={null}
ACROSS 5,154 MARKETS: $10.2M volume, +$1.1M (Polymarket) — a grinder in the black.
ENTRY:  buys around even odds (VWAP ~0.54), not chasing extremes.
SIZE:   steady ~$19 clips with occasional conviction lumps up to ~$48k.
TIMING: near-zero early, ~57% of capital in the last tenth — a late piler.
EDGE:   size + timing pays on the winners (this one +$234k at 65% ROI).
LEAK:   winrate 41% — the late-pile conviction loses more markets than it wins.
VERDICT: fade the aggregate, but the late conviction lumps are worth watching.
```

<Tip>
  **The `crack_this_trader` prompt does exactly this** — invoke it instead of
  scripting the steps by hand. Fetching it is free.
</Tip>

Every claim should trace to a number a tool returned. If the record looks
incomplete — counts, winrate, and volume cover the V2 era until the v1 backfill —
say so rather than guessing.

***

## Compare two traders

**Goal:** which of two is better, and do they overlap?
**Cost:** \~4–6 calls, \~1–2k tokens.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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_id`s
    mean correlated books.
  </Step>

  <Step title="Optional: get_market_summary on a market they both traded">
    To see who entered better, or earlier.
  </Step>
</Steps>

<Note>
  Card-only comparison is the cheapest high-signal move on the whole API. Two
  \~90-token calls settle most "who's better" questions.
</Note>

<Warning>
  On **Basic Intelligence**, comparing two traders spends **two of your three
  daily wallet lookups**. Repeat reads of either wallet that day are free — so do
  the whole comparison in one session rather than coming back tomorrow.
</Warning>

***

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

<Steps>
  <Step title="get_market_summary(trader, market)">
    The shape first: entry VWAP, the per-token `sides` block, hold time, outcome,
    P/L. Usually the whole answer.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Want the whole thing plotted? Go to the plotting recipe.">
    See below.
  </Step>
</Steps>

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

<Tip>
  For **"what happened at the end?"**, pass a tight `from_ts` / `to_ts` window
  near the market's close. There is no descending or `until` tick paging — it is a
  forward keyset cursor — so a narrow end-window *is* the endgame view.
</Tip>

***

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

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

This is the cheapest way to "watch" a trader: it holds **no live slot**, and each
poll is one request. A quiet trader costs a few hundred tokens per poll; cap busy
ones with `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).

<Steps>
  <Step title="get_market_summary(trader, market) first, if you haven't">
    It tells you whether the market resolved, and its window.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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`](https://polytape.io/skill/reference/templates/chart-market-tape.html).

    Replace the single `"__DATA__"` placeholder with your JSON. The templates draw
    the house grammar for you.
  </Step>

  <Step title="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¢".
  </Step>
</Steps>

Full spec, palette, and the templates: [Plotting](/guides/plotting).

***

## Cost cheat sheet

| Workflow                           | Calls | Tokens (thrifty)  |
| ---------------------------------- | ----- | ----------------- |
| Compare two traders (cards only)   | 2     | \~180             |
| Read one market (summary only)     | 1–2   | \~250–2k          |
| Crack a trader (full)              | 6–10  | \~3–5k            |
| Plot a market (sampled + template) | 1–2   | \~3–6k            |
| Monitor poll (quiet / busy)        | 1     | \~0.3k / \~10–15k |

The single biggest waste is an unbounded `list_trader_markets` or
`get_recent_fills` over MCP (\~35k / \~15k tokens). Always pass `limit`.