# Polymarket (/docs/polymarket)

Search Polymarket prediction markets via the public Gamma API. Events, market questions, outcome prices, volume, liquidity, and price movement.

Polymarket events carry real-money prediction-market signals: who is favoured to win the next US election, whether Bitcoin hits $200k, whether a model ships by year-end. One endpoint searches them, and it does the multi-query fan-out for you.

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

  `/v1/polymarket/search`, the raw single-query lookup, was withdrawn on
  06/06/2026 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.

## Quickstart

### 1. Research a topic

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

### 2. Read the outcome prices

Each event carries its markets, and each market its outcomes and prices. Prices are normalised 0 to 1, so `0.32` reads as a 32% implied probability.

```json title="Response"
{
  "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
}
```

## Research prediction markets

| Endpoint                      | Credits | What it returns                                                                                                       | Key parameters   |
| ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- | ---------------- |
| `GET /v1/polymarket/research` | 5       | Ranked events, each with its market questions, outcome prices, volume, liquidity, price movement, end dates, and tags | `query`, `limit` |

`research` 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.

Each event carries outcome prices (`Yes`/`No` or per-candidate, normalised 0 to 1), 24h/1w/1m volume and liquidity in USD, day/week/month price changes, market end dates, and a competitiveness reading of how close to 50/50 the market is.

## All endpoints

## Platform notes

- **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.
- **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`, and so on), because prediction-market events have no author and no text content the way a social post does.
- **There is no pagination.** The upstream returns a single non-cursored result set, and `limit` is the only size control.
- Responses cache for 2 minutes. Markets move fast, so send `Cache-Control: no-cache` when you need a billed fresh read.
- Authentication is your SocialCrawl `x-api-key`. Polymarket's upstream is no-auth, but you still authenticate to us.

## Next steps

- [Google Finance](/docs/google_finance.md): Quotes and fundamentals for the instruments these markets track.
- [Universal search](/docs/search/everywhere.md): Polymarket is one of its fan-out sources.
- [Credits](/docs/credits.md): How billing, caching, and refunds work.