# Polymarket endpoint catalog

Every documented endpoint mapped to a client method in `scripts/polymarket.py`.
Source of truth: https://docs.polymarket.com/api-reference (and `/llms.txt`).
Paths marked ⚠ are internal/best-effort — verify against the live docs if a call
fails, and adjust the method body in `polymarket.py`.

## Gamma API — `GammaClient` (gamma-api.polymarket.com)

| Capability | Method | Path | Key params |
|---|---|---|---|
| List markets | `list_markets()` | GET /markets | limit, offset, order, ascending, id, slug, clob_token_ids, condition_ids, tag_id, closed, liquidity_num_min/max, volume_num_min/max, start_date_min/max, end_date_min/max |
| Market by id | `get_market(id)` | GET /markets/{id} | |
| Market tags | `get_market_tags(id)` | GET /markets/{id}/tags | |
| List events | `list_events()` | GET /events | limit, offset, order, ascending, slug, tag_id, closed, active |
| Events (keyset) | `list_events_paginated()` | GET /events/pagination | |
| Event by id | `get_event(id)` | GET /events/{id} | |
| Event by slug | `get_event_by_slug(slug)` | GET /events/slug/{slug} | |
| Event tags | `get_event_tags(id)` | GET /events/{id}/tags | |
| List tags | `list_tags()` | GET /tags | limit, offset |
| Tag by id / slug | `get_tag(id)` / `get_tag_by_slug(slug)` | GET /tags/{id}, /tags/slug/{slug} | |
| Related tags | `get_related_tags_by_id/slug`, `get_tags_related_to_id/slug` | GET /tags/{id}/related-tags[/tags] | |
| List / get series | `list_series()` / `get_series(id)` | GET /series, /series/{id} | |
| List comments | `list_comments()` | GET /comments | limit, offset, parent_entity_type, parent_entity_id |
| Comments by id | `get_comments_by_id(id)` | GET /comments/{id} | |
| Comments by user | `get_comments_by_user(addr)` | GET /comments/user_address/{addr} | |
| Search | `search(q)` | GET /public-search | q, limit_per_type, events_status |
| Sports metadata | `get_sports_metadata()` | GET /sports | |
| Sports market types | `get_sports_market_types()` | GET /sports/market-types | |
| List teams | `list_teams()` | GET /teams | league, name |
| Public profile | `get_public_profile(addr)` | GET /public-profile/{addr} | |

## Data API — `DataClient` (data-api.polymarket.com)

| Capability | Method | Path | Key params |
|---|---|---|---|
| Current positions | `positions(user)` | GET /positions | user, market, eventId, sizeThreshold, redeemable, mergeable, limit(≤500), offset, sortBy, sortDirection, title |
| Closed positions | `closed_positions(user)` | GET /closed-positions | user, limit, offset |
| Positions in a market | `market_positions(market)` | GET /positions | market=conditionIds |
| Total value | `value(user)` | GET /value | user, market |
| User activity | `activity(user)` | GET /activity | user, limit, offset, market, type, side, start, end |
| Combo activity | `combo_activity(user)` | GET /combo-activity | user |
| Combo positions | `combo_positions(user)` | GET /combo-positions | user |
| Trades | `trades()` | GET /trades | user, market, limit, offset, takerOnly, side |
| Top holders | `holders(market)` | GET /holders | market, limit |
| Leaderboard | `leaderboard()` | GET /v1/leaderboard | category, timePeriod, orderBy(Pnl/Vol), limit(≤50), offset, user, userName |
| Markets traded count | `traded(user)` | GET /traded | user |
| Open interest | `open_interest()` | GET /oi | market |
| Live event volume | `live_volume_event(id)` | GET /live-volume | id |
| Builder leaderboard | `builder_leaderboard()` | GET /v1/builders/leaderboard | timePeriod(DAY/WEEK/MONTH/ALL), limit(≤50), offset |
| Builder volume series | `builder_volume()` | GET /v1/builders/volume | timePeriod |
| Accounting snapshot (ZIP) | `accounting_snapshot(user)` | GET /v1/accounting/snapshot | user — saves positions.csv+equity.csv to disk |

## CLOB public — `ClobPublicClient` (clob.polymarket.com)

| Capability | Method | Path |
|---|---|---|
| Order book (single) | `order_book(token_id)` | GET /book |
| Order books (batch) | `order_books([token_ids])` | POST /books |
| Price (one side) | `price(token_id, side)` | GET /price |
| Prices (batch) | `prices([{token_id,side}])` | POST /prices |
| Midpoint / midpoints | `midpoint`, `midpoints` | GET /midpoint, POST /midpoints |
| Spread / spreads | `spread`, `spreads` | GET /spread, POST /spreads |
| Last trade price(s) | `last_trade_price`, `last_trade_prices` | GET /last-trade-price, POST /last-trades-prices |
| Tick size | `tick_size(token_id)` | GET /tick-size |
| Fee rate | `fee_rate_bps()` | GET /fee-rate-bps |
| Price history | `prices_history(market)` | GET /prices-history — params: interval(1m/1h/6h/1d/1w/max), startTs, endTs, fidelity |
| Market by condition id | `get_market(condition_id)` | GET /markets/{condition_id} |
| List markets | `list_markets(next_cursor)` | GET /markets |
| Simplified markets | `simplified_markets(next_cursor)` | GET /simplified-markets |
| Sampling (reward) markets | `sampling_markets`, `sampling_simplified_markets` | GET /sampling-markets, /sampling-simplified-markets |
| Server time | `server_time()` | GET /time |
| Rewards: active configs | `rewards_markets_current()` | GET /rewards/markets/current — sponsored, next_cursor |
| Rewards: markets w/ rewards | `rewards_markets_multi()` | GET /rewards/markets/multi — q, tag_slug, event_id, order_by, min/max_volume_24hr, min/max_spread, min/max_price, page_size |
| Rewards: raw for a market | `rewards_market(condition_id)` | GET /rewards/markets/{condition_id} — sponsored |
| Builder-attributed trades | `builder_trades(builder_code)` | GET /builder/trades — id, market, asset_id, before, after |

## CLOB authenticated trade — `TradingClient` (via py-clob-client)

Backed by the official **v2** SDK `py_clob_client_v2`.

| Capability | Method | Notes |
|---|---|---|
| Create / derive API key | `create_or_derive_api_key(nonce=None)` | L1 EIP-712 |
| Post limit order | `create_and_post_order(token_id, price, size, side, order_type)` | order_type GTC/FOK/FAK |
| Post market order | `create_and_post_market_order(token_id, amount, side, order_type)` | FOK/FAK |
| Cancel one | `cancel_order(payload)` | order hash/id |
| Cancel many/all/market | `cancel_orders(hashes)`, `cancel_all()`, `cancel_market_orders(payload)` | |
| Get order | `get_order(order_id)` | L2 |
| Get open orders | `get_open_orders(market=, asset_id=, id=)` | L2; filters optional, else all pages. Fresh orders may lag indexing |
| Get trades | `get_trades(market=, asset_id=, maker_address=, before=, after=)` | L2 |
| Order scoring | `is_order_scoring(order_id)`, `are_orders_scoring(order_ids)` | reward eligibility |
| Balance/allowance | `get_balance_allowance(params)`, `update_balance_allowance(params)` | |

### L2-authenticated rewards / rebates (signed by the skill, not the SDK)

| Capability | Method | Path |
|---|---|---|
| User earnings by date | `rewards_user_earnings(date)` | GET /rewards/user |
| User total earnings by date | `rewards_user_total(date)` | GET /rewards/user/total |
| User reward percentages | `rewards_user_percentages()` | GET /rewards/user/percentages |
| User earnings + markets config | `rewards_user_markets()` | GET /rewards/user/markets |
| Maker rebated fees | `rebates_current(date, maker_address)` | GET /rebates/current |

All accept `signature_type`, `maker_address`, `sponsored`, `next_cursor` etc. as
kwargs. They use `_l2_get`, which builds the HMAC-SHA256 `POLY_*` headers from
the derived creds.

Maker (RFQ) quote endpoints — submit_quote / cancel_quote / confirm last-look —
live on the underlying `TradingClient().client` when your account is enabled for
the maker program; see the py_clob_client_v2 docs.

## Bridge — `BridgeClient` (bridge.polymarket.com)

`supported_assets()`, `get_quote(body)`, `create_bridge_addresses(body)`,
`create_withdrawal_addresses(body)`, `transaction_status(tx_id)`.

## Relayer — `RelayerClient` (relayer-v2.polymarket.com) ⚠ host/paths internal

`is_deployed(addr)`, `nonce(addr)`, `relayer_address(addr)`,
`transaction(id)`, `recent_transactions(addr)`, `submit(body)`.

## Combo markets — `ComboClient` (combos-rfq-api.polymarket.com)

| Capability | Method | Path | Params |
|---|---|---|---|
| Get combo markets | `combo_markets()` | GET /v1/rfq/combo-markets | limit(1-100), cursor, exclude |

## Anything still missing

These tools hit internal APIs that change. If a path 404s, look it up on the
relevant doc page under https://docs.polymarket.com/api-reference and either fix
the method body in `polymarket.py` or call the generic helper directly:

```python
from polymarket import _request, CLOB, DATA
_request("GET", f"{CLOB}/some/new/path", params={"next_cursor": ""})
```