`skills/polymtrx/references/api.md`

67 lines
# Polymarket public API reference (as used by polymtrx)

All endpoints below are **public and key-less**. `polymtrx` is **read-only** —
it only issues GETs. No auth, no wallet, no order placement.

## Gamma API — `https://gamma-api.polymarket.com`

Market + event metadata. This is the primary source.

### `GET /public-search?q=<topic>&limit_per_type=<n>&events_status=active`
Full-text search. Returns `{ "events": [ { ..., "markets": [ ... ] } ], ... }`.
Used by `scan`. Each event carries child `markets`; we flatten them.

### `GET /markets?active=true&closed=false&archived=false&order=volume24hr&ascending=false&limit=<n>`
List markets, orderable. Used by `trending` (ordered by 24h volume). Returns a
JSON array (sometimes an object with a `markets` key — the engine handles both).

### `GET /markets?slug=<market-slug>` · `GET /markets/<numeric-id>`
Single-market lookup. Used by `market`. If the slug matches no market, the
engine falls back to `GET /events?slug=<event-slug>` and returns that event's
markets.

### Key fields on a market object
| Field | Notes |
| --- | --- |
| `question` / `groupItemTitle` | the market's headline |
| `slug`, and parent event `slug` | build `polymarket.com/event/<event-slug>` |
| `outcomePrices` | **often a JSON-encoded string** like `"[\"0.62\", \"0.38\"]"` — must be `json.loads`-ed; index 0 = YES price |
| `outcomes` | same JSON-encoded-string gotcha |
| `lastTradePrice` | fallback when `outcomePrices` absent |
| `volume`, `liquidity` | **may be strings** — coerce to float; may live on the event, not the market |
| `spread` | Gamma's own spread estimate (0..1); refined by CLOB when available |
| `oneDayPriceChange` | signed 24h change (0..1) → `movement` signal |
| `endDate` | ISO8601, may end in `Z` → resolution timing |
| `clobTokenIds` | JSON-encoded string array of CLOB token ids; index 0 = YES token |
| `active`, `closed` | filter out `closed` markets |

## CLOB API — `https://clob.polymarket.com`

Live order book. Used **best-effort** to refine `spread` + `liquidity` for the
top-ranked markets only (one round-trip each, threaded). Never core — if the
shape shifts, the engine degrades gracefully (`clob_ok: false`) and keeps the
Gamma-derived numbers.

### `GET /ok`
Health ping (used by `doctor`).

### `GET /book?token_id=<clob-token-id>`
Returns `{ "bids": [ {price,size}, ... ], "asks": [ ... ] }`.
- best bid / best ask → spread = `|best_ask - best_bid|`
- Σ(price × size) across both sides → a depth proxy blended into `liquidity`

## Field-coercion gotchas (why `_parse_float` exists)
Polymarket mixes types freely across and within endpoints:
- prices arrive as `float`, `"0.62"` (string), or `"[\"0.62\",\"0.38\"]"` (JSON string).
- `volume` / `liquidity` arrive as numbers **or** strings.
- token ids arrive as a JSON-encoded string array.

`_parse_float` and the JSON-string unwrapping in `_normalize_market` absorb all
of these. If Polymarket adds a new encoding, extend those two spots.

## Endpoints deliberately NOT used
- **Data API** (`data-api.polymarket.com`) — user positions / trade history.
  Out of scope: `polymtrx` scans *markets*, not accounts.
- **Any authenticated / order-placement endpoint** — forbidden by the read-only
  hard rail.