# Polymarket (/docs/polymarket)



Polymarket [#polymarket]

Search Polymarket prediction markets via the public Gamma API — a server-side multi-query research endpoint that ranks results by topic relevance.

Base URL: `/v1/polymarket/...`

What you get [#what-you-get]

Polymarket events surface real-money prediction-market signals: who's favoured to win the next US election, will Bitcoin hit $200k, will OpenAI ship GPT-5 by year-end. Each event carries:

* Outcome prices (`Yes` / `No` or per-candidate, normalised 0–1)
* 24h / 1w / 1m volume and liquidity in USD
* Day / week / month price changes
* Market end dates
* "Competitiveness" — how close to 50/50 the market is

The research endpoint [#the-research-endpoint]

<PlatformEndpoints platform="polymarket" />

`GET /v1/polymarket/research` is the whole platform. It takes a free-text `query` and does
the fan-out for you: it expands the topic into up to six search queries (the core subject
plus its individual informative words), issues them in parallel, de-duplicates events by
id, drops matches that share no informative word with your topic, and ranks what is left
by topic-to-title similarity. Framing prefixes like "last 30 days" or "what are people
saying about" are stripped before expansion, so natural-language topics work as written.

`limit` (default 10) caps results per result type on each fan-out call, which is how you
bound the response size.

<Callout>
  `/v1/polymarket/search`

  , the raw single-query lookup, was withdrawn on 2026-06-06
  when the Gamma API began returning 

  `502`

   on consecutive probes. It is disabled and returns
  a 

  `503`

   at no charge. 

  `research`

   covers the same ground with multi-query expansion, so
  there is nothing to migrate beyond the path.
</Callout>

Getting started [#getting-started]

```bash
curl "https://www.socialcrawl.dev/v1/polymarket/research?query=bitcoin%20halving&limit=20" \
  -H "x-api-key: sc_your_api_key_here"
```

Response shape [#response-shape]

The research endpoint normalises to the unified `SearchResult` archetype:

```json
{
  "success": true,
  "platform": "polymarket",
  "endpoint": "/v1/polymarket/research",
  "data": {
    "items": [
      {
        "id": "evt-...",
        "title": "Will Trump win the 2028 election?",
        "slug": "trump-2028",
        "markets": [
          {
            "question": "Will Trump win the 2028 election?",
            "outcomes": "[\"Yes\",\"No\"]",
            "outcomePrices": "[\"0.32\",\"0.68\"]",
            "liquidity": 10000,
            "volume": 50000,
            "endDate": "2028-11-07T00:00:00Z",
            "oneDayPriceChange": 0.01,
            "oneWeekPriceChange": -0.02,
            "oneMonthPriceChange": 0.05
          }
        ],
        "tags": [{ "label": "Politics" }]
      }
    ]
  },
  "credits_used": 5,
  "credits_remaining": 95,
  "request_id": "req-...",
  "cached": false
}
```

Polymarket is a passthrough — fields under `data.items[]` are exactly what the Gamma API returns. There is **no** field map and **no** computed-field layer (no `engagement_rate`, `language`, etc.) because prediction-market events don't have authors or text content the way a TikTok post does.

Notes [#notes]

* `GET` with query parameters.
* Authentication via `x-api-key` on the SocialCrawl side. Polymarket's upstream is no-auth, but you still authenticate to us.
* Responses cache for 2 minutes. Markets move fast, so send `Cache-Control: no-cache` when you need a billed fresh read.
* The `research` endpoint costs **5 credits** because one request makes six or more upstream calls (multi-query expansion, parallel fan-out, then ranking). That is the price whichever `limit` you pass.
* There is no pagination: the upstream returns a single non-cursored result set, and `limit` is the only size control.