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

# Token thrift

> Payloads on this API vary by three orders of magnitude. Two rules save most of it.

Measured on real traders, the cheapest call on this API is about 70 tokens and
the most expensive is about 35,000. Knowing which is which is most of the skill.

## What things cost

| Call                                                                    | Typical size                   | Notes                                                  |
| ----------------------------------------------------------------------- | ------------------------------ | ------------------------------------------------------ |
| `whoami` / `get_trader_card` / `get_top_markets` / `get_market_summary` | \~70–2k                        | Cheap. Lean on these.                                  |
| **`get_market_events`** (sampled, \~300 pts)                            | **\~2.5–3k REST / \~5–6k MCP** | One call = the whole chart. Ask `points=120` for chat. |
| `get_pnl_series`                                                        | \~1–2k                         | The equity curve in one call.                          |
| **`list_trader_markets`** (full 200-row page)                           | **\~16k REST / \~35k MCP**     | **Always pass `limit`.**                               |
| `get_recent_fills` (full page)                                          | \~10–15k                       | Cap with `limit`.                                      |

## The two rules

<Steps>
  <Step title="Prefer summaries over raw arrays">
    `get_market_summary` and `get_top_markets` already contain sizing, timing,
    entry pricing, and per-market P/L — as computed numbers, with no arrays.
    They answer "how did they trade this?" outright.

    Reach for `get_market_events` when you need to **chart** a market or confirm a
    specific sequence. Not before.
  </Step>

  <Step title="On MCP, always pass limit">
    MCP returns every result **twice** — a readable text copy and a structured
    copy — so paged tools cost roughly **double** their REST equivalent.

    A default `list_trader_markets` page is \~35k tokens. `limit: 20` turns that
    into \~2k. The same applies to `get_recent_fills` (`limit`) and
    `get_market_events` (`points`).
  </Step>
</Steps>

<Warning>
  The single biggest waste on the whole surface is an unbounded
  `list_trader_markets` or `get_recent_fills` over MCP. One careless call can
  cost more tokens than an entire well-run trader crack.
</Warning>

## Workflow costs

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

## Reach for the right primitive

<AccordionGroup>
  <Accordion title="Never page a markets list to find extremes" icon="magnifying-glass">
    `list_trader_markets` is **recency-ordered only**, by design. A 40,000-market
    bot has no "biggest win" on page one, and paging 200 times to find it costs a
    fortune and still misses.

    `get_top_markets` returns `top_wins`, `top_losses`, `most_traded`, and
    `top_volume` from **one scan**. That is the extremes primitive.

    Keep `n` modest on mega-makers — a 180,000-market account sits near the
    heavy-query timeout, and a narrow `n` is both cheaper and likelier to return.
  </Accordion>

  <Accordion title="One sampled call is the whole chart" icon="chart-line">
    `get_market_events` returns a decimated price `series` **plus the trader's
    complete fills** in a single response. No cursor, no tick flood.

    `raw=1` returns the verbatim tick pages instead, where the same second
    repeats about **36 times** — a 5-minute market becomes 8,000 rows across 4
    pages. It exists as an export path. You almost never want it for a chart.
  </Accordion>

  <Accordion title="Monitoring is one call per poll" icon="satellite-dish">
    `get_recent_fills` with a `since` watermark holds no live slot and costs one
    request per poll. Record the last fill's `ts` and pass it back next time so
    you only pull what is new.

    Poll on a **minutes** cadence. Freshness is bounded by the archive pipeline
    anyway, and a tight loop burns a Basic day in under an hour.
  </Accordion>

  <Accordion title="Page only with the cursor you were handed" icon="arrow-right">
    Cursors are opaque keyset tokens, forward-only. Never hand-craft or mutate
    one.

    A malformed cursor is a clean `400 bad_cursor`. A **well-formed forged**
    cursor silently returns page 1 again — safe depth-wise, but you re-read and
    re-pay for data you already have.
  </Accordion>
</AccordionGroup>

## Validate before you fire

Application errors on real routes **burn a call**. A typo'd `condition_id` is a
`404` that costs a Basic user 1/50th of their day. `429` rejections do not burn
a call, so the rate limiter is free — but your own mistakes are not.