hermes-sync/skills/research/polymarket/references/api-endpoints.md

Polymarket API Endpoints Reference

All endpoints are public REST (GET), return JSON, and need no authentication.

Gamma API — gamma-api.polymarket.com

Search Markets

GET /public-search?q=QUERY

Response structure:

{
  "events": [
    {
      "id": "12345",
      "title": "Event title",
      "slug": "event-slug",
      "volume": 1234567.89,
      "markets": [
        {
          "question": "Will X happen?",
          "outcomePrices": "[\"0.65\", \"0.35\"]",
          "outcomes": "[\"Yes\", \"No\"]",
          "clobTokenIds": "[\"TOKEN_YES\", \"TOKEN_NO\"]",
          "conditionId": "0xabc...",
          "volume": 500000
        }
      ]
    }
  ],
  "pagination": {"hasMore": true, "totalResults": 100}
}

List Events

GET /events?limit=N&active=true&closed=false&order=volume&ascending=false

Parameters:

• limit — max results (default varies)
• offset — pagination offset
• active — true/false
• closed — true/false
• order — sort field: volume, createdAt, updatedAt
• ascending — true/false
• tag — filter by tag slug
• slug — get specific event by slug

Response: array of event objects. Each event includes a markets array.

Event fields: id, title, slug, description, volume, liquidity, openInterest, active, closed, category, startDate, endDate, markets (array of market objects).

List Markets

GET /markets?limit=N&active=true&closed=false&order=volume&ascending=false

Same filter parameters as events, plus:

• slug — get specific market by slug

Market fields: id, question, conditionId, slug, description, outcomes, outcomePrices, volume, liquidity, active, closed, marketType, clobTokenIds, endDate, category, createdAt.

Important: outcomePrices, outcomes, and clobTokenIds are JSON strings (double-encoded). Parse with json.loads() in Python.

List Tags

GET /tags

Returns array of tag objects: id, label, slug. Use the slug value when filtering events/markets by tag.

---

CLOB API — clob.polymarket.com

All CLOB price endpoints use token_id from the market's clobTokenIds field. Index 0 = Yes outcome, Index 1 = No outcome.

Current Price

GET /price?token_id=TOKEN_ID&side=buy

Response: {"price": "0.650"}

The side parameter: buy or sell.

Midpoint Price

GET /midpoint?token_id=TOKEN_ID

Response: {"mid": "0.645"}

Spread

GET /spread?token_id=TOKEN_ID

Response: {"spread": "0.02"}

Orderbook

GET /book?token_id=TOKEN_ID

Response:

{
  "market": "condition_id",
  "asset_id": "token_id",
  "bids": [{"price": "0.64", "size": "500"}, ...],
  "asks": [{"price": "0.66", "size": "300"}, ...],
  "min_order_size": "5",
  "tick_size": "0.01",
  "last_trade_price": "0.65"
}

Bids and asks are sorted by price. Size is in shares (USDC-denominated).

Price History

GET /prices-history?market=CONDITION_ID&interval=INTERVAL&fidelity=N

Parameters:

• market — the conditionId (hex string with 0x prefix)
• interval — time range: all, 1d, 1w, 1m, 3m, 6m, 1y
• fidelity — number of data points to return

Response:

{
  "history": [
    {"t": 1709000000, "p": "0.55"},
    {"t": 1709100000, "p": "0.58"}
  ]
}

t is Unix timestamp, p is price (probability).

Note: Very new markets may return empty history.

CLOB Markets List

GET /markets?limit=N

Response:

{
  "data": [
    {
      "condition_id": "0xabc...",
      "question": "Will X?",
      "tokens": [
        {"token_id": "123...", "outcome": "Yes", "price": 0.65},
        {"token_id": "456...", "outcome": "No", "price": 0.35}
      ],
      "active": true,
      "closed": false
    }
  ],
  "next_cursor": "cursor_string",
  "limit": 100,
  "count": 1000
}

---

Data API — data-api.polymarket.com

Recent Trades

GET /trades?limit=N
GET /trades?market=CONDITION_ID&limit=N

Trade fields: side (BUY/SELL), size, price, timestamp, title, slug, outcome, transactionHash, conditionId.

Open Interest

GET /oi?market=CONDITION_ID

---

Field Cross-Reference

To go from a Gamma market to CLOB data:

1. Get market from Gamma: has clobTokenIds and conditionId
2. Parse clobTokenIds (JSON string): ["YES_TOKEN", "NO_TOKEN"]
3. Use YES_TOKEN with /price, /book, /midpoint, /spread
4. Use conditionId with /prices-history and Data API endpoints