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

# REST overview

> Base URL, conventions, pagination, and the two orientation endpoints of the PolyTape agent REST API.

```
https://api.polytape.io/api/agent/v1
```

**Every read is a GET.** All responses are JSON. Authenticate every request with
a header:

```http theme={null}
Authorization: Bearer td_live_...
```

Full machine schema: [`/api/agent/v1/openapi.json`](https://api.polytape.io/api/agent/v1/openapi.json).

## Conventions

<AccordionGroup>
  <Accordion title="Identifiers" icon="fingerprint">
    `{trader}` accepts a **0x wallet**, a **polymarket.com profile URL**, or a
    **display name** (e.g. `GoingInsolvent`). Responses always echo the canonical
    wallet and name.

    A `0x`-prefixed string of the *wrong* hex length is treated as a malformed
    wallet → `400 invalid_wallet`. It never falls through to name resolution.

    `{condition_id}` is the `0x…` 64-hex market id from the markets list or
    top-markets.
  </Accordion>

  <Accordion title="Units" icon="ruler">
    Timestamps are epoch **seconds**. Money fields are USD, suffixed `_usd`.
    Prices are **UP-normalized** (0–1) — token 1's probability.

    The one exception: `resets_at` on a
    [`wallet_quota`](/plans-and-limits#trader-lookups-basic-only) verdict is an
    ISO 8601 UTC string.
  </Accordion>

  <Accordion title="Pagination" icon="arrow-right">
    Cursors are **opaque and forward-only**. First request: no `cursor`
    (optionally `since` / `window` to position). Then pass the response's
    `next_cursor` back. When `next_cursor` is absent or null, you have reached the
    end.

    Never hand-craft or mutate a cursor. A malformed one is a clean `400
            bad_cursor`; a well-formed **forged** one silently returns page 1 again — safe
    depth-wise, but you re-pay for data you already have.

    `limit` caps a single page and must be **≥ 1** (`limit=0` is `400 bad_limit`).
    It is your main token-control knob.
  </Accordion>

  <Accordion title="Caching" icon="database">
    Resolved market summaries and tapes are immutable and **ETag'd** — send
    `If-None-Match` for a `304`.

    Note that a `304` on a real route still burns a call; it saves you tokens and
    bandwidth, not quota.

    The trader card is `Cache-Control: no-store`.
  </Accordion>
</AccordionGroup>

## Plan gates

* **History depth** — Basic Intelligence reaches a trader's **5 most-recent
  markets**; Pro and Max reach the full record. A market past the window is
  `403 depth_gated`. `history_depth` in `/me` is the count (`-1` = unlimited).
* **Trader lookups** — Basic Intelligence can pull **3 distinct wallets per UTC
  day**, shared with the dashboard and MCP. The 4th new wallet is
  `403 wallet_quota`.

Both are detailed in [Plans & limits](/plans-and-limits).

***

## Orient

### `GET /me`

Plan, rate limits, usage this window and this day/month, and which key is
calling. Mirrors the MCP `whoami` tool. **Start here.**

`plan` is the display name: `Basic Intelligence` | `Pro Intelligence` |
`Max Intelligence`.

<CodeGroup>
  ```bash Request theme={null}
  curl -H "Authorization: Bearer td_live_..." \
    https://api.polytape.io/api/agent/v1/me
  ```

  ```json Response theme={null}
  {
    "plan": "Pro Intelligence",
    "limits": {
      "rps": 5.0,
      "burst": 60,
      "rpm": 300.0,
      "daily_requests": 0,
      "monthly_requests": 50000,
      "max_keys": 3,
      "live_slots": 3,
      "history_depth": -1
    },
    "usage": {
      "window": { "tokens_remaining": 59.0, "rpm_used": 1 },
      "day":    { "requests": 0,  "cap": 0 },
      "month":  { "requests": 42, "cap": 50000 }
    },
    "key": { "label": "my agent", "last4": "ZLI4" }
  }
  ```
</CodeGroup>

The call quota has two windows and **the governing one is nonzero**. A Basic
Intelligence caller inverts them: `daily_requests: 50`, `monthly_requests: 0`,
and `usage.day` carries the governing count and cap.

### `GET /popular`

Curated popular traders with display names and live watching counts. These stream
without holding any of your live slots.

```json theme={null}
{ "traders": [ { "wallet": "0x…", "name": "GoingInsolvent", "watching": 0 } ],
  "count": 2 }
```

***

<Columns cols={2}>
  <Card title="Traders" icon="user" href="/rest/traders">
    Cards, markets, summaries, charts, fills, and the equity curve.
  </Card>

  <Card title="Tapes" icon="compact-disc" href="/rest/tapes">
    Your recorded watch sessions.
  </Card>
</Columns>