> ## 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.
# Plans & limits
> The PolyTape ladder — agent calls, API rate, history depth, daily trader lookups, live slots, storage, and keys — plus what each wall looks like on the wire.
One budget per user. Every key you own and every OAuth session you open draws
from it.
## The ladder
**Free forever.** Kick the tires — every tool, a daily taste of calls, one
live stream with full replay.
| | |
| -------------------- | ---------------------------------- |
| **Agent calls** | **50 / day** (resets midnight UTC) |
| **API rate** | 0.5 RPS · burst 10 · 30 RPM |
| **Historical depth** | 5 markets per trader |
| **Trader lookups** | 3 distinct wallets / day |
| Live streams | 1 slot |
| Watch & replay (DVR) | Included |
| Record a live market | — (Pro+) |
| Library storage | 200 MB |
| API keys | 1 |
**\$29 / month.** The daily driver — unlimited history, auto-saved tapes.
| | |
| -------------------- | --------------------------------------- |
| **Agent calls** | **50,000 / month** (resets month start) |
| **API rate** | 5 RPS · burst 60 · 300 RPM |
| **Historical depth** | Unlimited |
| **Trader lookups** | Unlimited |
| Live streams | 3 slots |
| Watch & replay (DVR) | Included |
| Record a live market | Auto-save |
| Library storage | 2 GB |
| API keys | 3 |
**\$79 / month.** The desk that never sleeps.
| | |
| -------------------- | ---------------------------------------- |
| **Agent calls** | **300,000 / month** (resets month start) |
| **API rate** | 20 RPS · burst 200 · 1,200 RPM |
| **Historical depth** | Unlimited |
| **Trader lookups** | Unlimited |
| Live streams | 5 slots |
| Watch & replay (DVR) | Included |
| Record a live market | Auto-save |
| Library storage | 10 GB |
| API keys | 6 |
Side by side:
| | Basic | Pro | Max |
| -------------------- | ------------ | --------------- | ---------------- |
| Price | \$0 | \$29 / mo | \$79 / mo |
| **Agent calls** | **50 / day** | **50,000 / mo** | **300,000 / mo** |
| **API rate** | 0.5 RPS | 5 RPS | 20 RPS |
| Burst | 10 | 60 | 200 |
| RPM ceiling | 30 | 300 | 1,200 |
| **Historical depth** | 5 / trader | unlimited | unlimited |
| **Trader lookups** | 3 / day | unlimited | unlimited |
| Live streams | 1 | 3 | 5 |
| Watch & replay (DVR) | ✓ | ✓ | ✓ |
| Record a live market | — | ✓ | ✓ |
| Storage | 200 MB | 2 GB | 10 GB |
| API keys | 1 | 3 | 6 |
**Replay is not a paid feature.** Watching a live stream and scrubbing it back —
the DVR — is on **every plan, Basic included**. What Pro and Max add is
**recording a live market**: capturing a session to a tape you keep in your
library.
So a Basic account can watch and replay all it likes; it just doesn't lay down
new tapes.
**`GET /me` is the authoritative answer.** Plans change, grants exist, and a
hand-copied table is a table that goes stale. Call
[`/me`](/rest/overview#get-me) (or the `whoami` tool) once at the start of a
run and read your real numbers off the wire.
## The four gates
Every request passes up to four checks. They are gates over one budget, not
additive allowances.
You can fire `burst` requests instantly, then one every `1/rps` seconds as
the bucket refills. This fits the natural agent shape: a handful of calls,
then idle. Overflow is `429 rate_limited` with a `Retry-After` in seconds.
A rolling 60-second ceiling that **includes** burst spend. Hitting it is the
same `429 rate_limited`. Honor `Retry-After` and continue.
The hard backstop and the upgrade lever. Basic Intelligence resets **daily**
at midnight UTC; Pro and Max reset **monthly**. Exhaustion is `429
daily_limit` / `429 monthly_limit` — see [the paywall](#the-paywall) below.
Heavy reads (tape events, market ticks) also pass a cap on in-flight heavy
queries. Overflow is an instant, honest `429 busy` rather than a queue.
Retry in about a second.
## What counts against the call quota
* Every GET = **1 request**.
* Application errors on real routes **burn a call** — a `400`, a `404`, even
a `304` on a real endpoint charges for the served work. A typo'd
`condition_id` costs a Basic user 1/50th of their day, so validate inputs
before firing.
* `429` rejections (rate limit or paywall) do **not** burn a call.
* Every tool **call** = 1 request, `get_chart_template` included. There are
no exemptions.
* **Connecting, `tools/list`, `prompts/list`, and fetching a prompt cost
nothing.** A Basic user does not spend part of their 50 just to connect,
or to invoke `crack_this_trader`.
The WebSocket plane is **slot-metered, not request-metered**. Holding a live
stream does not draw down your call count. That is a separate budget — see
"Live streams" in the ladder above.
## History depth
Basic Intelligence reaches a trader's **5 most-recent markets**. Pro and Max
reach the full record through cursor paging.
A market past the window is:
```json theme={null}
HTTP 403
{ "error": "depth_gated",
"message": "this market is outside your history window" }
```
Surface the upgrade or treat it as a not-found. Do not retry — depth does not
change on its own. `history_depth` in `/me` is the count (`-1` = unlimited).
Depth is a **recency** window, not a sample. On Basic, `get_top_markets` still
ranks within the visible window — so "biggest win" means "biggest win in the
last 5 markets", and you should say so.
At five deep this matters more than it used to: five recent markets is a
glimpse, not a career. Say what you're looking at rather than generalising
from it.
## Trader lookups (Basic only)
Basic Intelligence can pull **3 distinct wallets per UTC day**. Composed with the
depth window, that reads: *three traders a day, five markets deep*.
* The counter is **distinct wallets**, not requests. Repeat reads of a wallet you
already looked at today are **free** — page it, summarize it, chart it, poll
it, all on the same one of three.
* It is **one shared counter** across the dashboard, REST, and MCP. There is no
agent bypass: a wallet you opened in the web app counts against the same three.
* It resets at midnight UTC.
* Pro and Max are unlimited.
The 4th **new** wallet that day walls on every trader-scoped read — card, market
list, market detail, summary, tape, fills, top-markets, and pnl-series:
```json REST theme={null}
HTTP 403
{ "error": "wallet_quota",
"message": "…names Basic Intelligence, the upgrade, https://polytape.io/pricing, and the midnight-UTC reset…",
"used": 3,
"limit": 3,
"resets_at": "2026-07-29T00:00:00Z" }
```
```text MCP theme={null}
isError: true
```
* `resets_at` is an **ISO 8601 UTC** string (next midnight UTC), not epoch
seconds. This is the one timestamp on the API that is not epoch seconds.
* There is **no `retry_after`** — that field belongs to `429`s. Here `resets_at`
carries the time.
* `message` is written to be **relayed to your human**. Surface it; do not
silently retry.
A wallet you have never read costs one of the three even if the read fails for
another reason. On Basic, resolve the trader you actually want before you spend
a slot on a guess.
## The paywall
Basic Intelligence is **50 calls a day** — enough to try a trader crack once or
twice, not to run a workflow. A well-run crack is about 6–10 calls.
When the quota is spent:
```json theme={null}
HTTP 429
{ "error": "daily_limit",
"message": "You've used all 50 of your Basic Intelligence PolyTape API calls today. Pro Intelligence gives you 50,000 calls a month at https://polytape.io/pricing to keep going.",
"retry_after": 24907 }
```
Pro and Max are the same shape with `monthly_limit` and a next-month reset. On
MCP the same copy comes back as a readable tool result (`isError: true`),
plan-aware — Pro is told about Max, and so on.
**Relay the message; do not silently retry.** `retry_after` on a daily cap
points hours out and on a monthly cap points weeks out. Burning retries against
it helps nobody.
## Reacting to a 429 — the etiquette
| error | class | what to do |
| ------------------------------- | ----------- | ----------------------------------------------------- |
| `rate_limited` | transient | Honor `Retry-After` (seconds) and retry. Clears fast. |
| `busy` | transient | Admission lane full. Retry in \~1s. |
| `daily_limit` / `monthly_limit` | **paywall** | Relay the message and stop. |
| `too_many_auth_failures` | credential | Fix the key, then wait out the window. |
And the two `403` verdicts — `depth_gated` and `wallet_quota` — are **plan
walls, not outages**. Surface the upgrade. Retrying changes nothing.
**Early access — a temporary grant, not a tier.** During the early-access
period, holding a founder seat resolves your account to **Pro Intelligence
limits**. This is a grant riding a server-side switch, not a plan you are on.
At paid go-live the switch flips: founders fall back to their real plan (Basic
unless subscribed) and **keep the founder badge permanently**. The badge is
durable; the limits it currently unlocks are not.
Because of that, do not hard-code a tier for a founder account. Call `/me` and
believe what it says — it is the only surface that knows which side of the
switch you are on.
## Spending well
* Lean on **cards, summaries, and `top-markets`** — tens to \~2k tokens each, and
they already carry sizing, timing, entry pricing, and per-market P/L.
* On **MCP always pass `limit`** to `list_trader_markets` and `get_recent_fills`,
and `points` to `get_market_events`. MCP returns every result twice (text +
structured), so a default markets page is \~35k tokens where `limit: 20` is \~2k.
* **Poll politely.** `get_recent_fills` with a `since` watermark on a minutes
cadence beats a tight loop — freshness is pipeline-bound anyway.
Full detail: [Token thrift](/concepts/token-thrift).