# Polymarket Markets API

Polymarket prediction markets: each market is a yes/no or multi-outcome question people bet on, with live odds, trading volume and end date. Browse a category such as Politics or Crypto, search by keyword (e.g. bitcoin, election), or paste polymarket.com event links.

**Pricing:** $0.0005 per market

**Endpoint:** `POST /v1/data/polymarket/markets/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `category` | string | No | Browse: one of Polymarket's categories (e.g. Politics, Crypto, Sports). Returns the markets in it, biggest first. No search term needed. |
| `query` | string | No | Keyword search: a topic, person, asset or event to find markets about (e.g. bitcoin, election, Fed rates). |
| `urls` | array | No | By URL: polymarket.com/event/... links (or just the event slug, e.g. what-price-will-bitcoin-hit-before-2027). Returns every market in each event; a link that ends in a market slug returns just that market. |
| `status` | string | No | Open markets you can still trade (active, the default) or finished ones with a known outcome (resolved). |
| `sortBy` | string | No | How markets are ordered. Defaults to total volume (most-traded first). |
| `maxResults` | integer | No | How many markets to return in total. Defaults to 100; use 0 for all. |

## Example

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/polymarket/markets/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/polymarket/markets/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display name | Type |
|-------|--------------|------|
| `marketId` | Market ID | text |
| `question` | Question | text |
| `url` | URL | url |
| `groupLabel` | Group Label | text |
| `eventId` | Event ID | text |
| `eventTitle` | Event Title | text |
| `status` | Status | text |
| `outcomes` | Outcomes | object_array |
| `pricing` | Pricing | object |
| `volume` | Volume | currency |
| `volume24h` | Volume 24h | currency |
| `volume1w` | Volume 1w | currency |
| `liquidity` | Liquidity | currency |
| `eventVolume` | Event Volume | currency |
| `priceChange24h` | Price Change 24h | number |
| `priceChanges` | Price Changes | object |
| `startDate` | Start Date | datetime |
| `endDate` | End Date | datetime |
| `tags` | Tags | array |
| `rules` | Rules | text |
| `resolutionSource` | Resolution Source | url |
| `conditionId` | Condition ID | text |
| `image` | Image | image |