> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polyhistorical.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Markets

> List all markets with filtering and pagination

# List Markets

Returns markets sorted by `start_time` descending (newest first).

## Request

```
https://api.polyhistorical.com/v1/markets
```

### Headers

<ParamField header="X-API-Key" type="string" required>
  Your API key. See [Authentication](/api-reference/overview#authentication).
</ParamField>

### Query parameters

<ParamField query="coin" type="string" required>
  Cryptocurrency to query. Supported: `BTC`, `ETH`, `SOL`
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Number of results to return (1-100)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Pagination offset
</ParamField>

<ParamField query="market_type" type="string">
  Filter by market type: `5m`, `15m`, `1hr` (all coins), `4hr`, `24hr` (BTC only)
</ParamField>

<ParamField query="resolved" type="boolean">
  Filter by resolution status. `false` for active markets, `true` for resolved.
</ParamField>

<ParamField query="start_time" type="string">
  Filter markets starting after this time. Accepts epoch milliseconds or ISO 8601.
</ParamField>

<ParamField query="end_time" type="string">
  Filter markets starting before this time. Accepts epoch milliseconds or ISO 8601.
</ParamField>

## Response

<ResponseField name="markets" type="array">
  Array of market objects
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of markets matching the filter
</ResponseField>

<ResponseField name="limit" type="integer">
  Number of results returned
</ResponseField>

<ResponseField name="offset" type="integer">
  Current pagination offset
</ResponseField>

<ResponseField name="warning" type="string">
  Warning message if applicable (null otherwise)
</ResponseField>

### Market object fields

<ResponseField name="slug" type="string">Market slug identifier</ResponseField>
<ResponseField name="market_id" type="string">External market ID</ResponseField>
<ResponseField name="event_id" type="string">External event ID</ResponseField>
<ResponseField name="market_type" type="string">Market interval — 5m, 15m, 1hr (all coins), 4hr, 24hr (BTC only)</ResponseField>
<ResponseField name="start_time" type="string">Market start time (ISO 8601)</ResponseField>
<ResponseField name="end_time" type="string">Market end time (ISO 8601)</ResponseField>
<ResponseField name="coin_price_start" type="number">Coin price at market start (null if not yet recorded)</ResponseField>
<ResponseField name="coin_price_end" type="number">Coin price at market end (null if unresolved)</ResponseField>
<ResponseField name="condition_id" type="string">Polymarket condition ID</ResponseField>
<ResponseField name="clob_token_up" type="string">CLOB token ID for the "Up" outcome</ResponseField>
<ResponseField name="clob_token_down" type="string">CLOB token ID for the "Down" outcome</ResponseField>
<ResponseField name="winner" type="string">Winning outcome (null if unresolved)</ResponseField>
<ResponseField name="final_volume" type="number">Final trading volume (null if unresolved)</ResponseField>
<ResponseField name="final_liquidity" type="number">Final liquidity (null if unresolved)</ResponseField>
<ResponseField name="resolved_at" type="string">Resolution timestamp (null if unresolved)</ResponseField>
<ResponseField name="created_at" type="string">Record creation timestamp</ResponseField>
<ResponseField name="updated_at" type="string">Record last updated timestamp</ResponseField>

## Examples

### Get active 5-minute BTC markets

<CodeGroup>
  ```bash cURL theme={null}
  curl -H "X-API-Key: YOUR_API_KEY" \
    "https://api.polyhistorical.com/v1/markets?coin=BTC&market_type=5m&resolved=false&limit=10"
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.polyhistorical.com/v1/markets",
      params={"coin": "BTC", "market_type": "5m", "resolved": False, "limit": 10},
      headers={"X-API-Key": API_KEY}
  )
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "markets": [
    {
      "slug": "btc-updown-5m-1774975800",
      "winner": "Down",
      "market_id": "1793728",
      "event_id": "325933",
      "market_type": "5m",
      "start_time": "2026-03-31T16:50:00Z",
      "end_time": "2026-03-31T16:55:00Z",
      "coin_price_start": 67701.82777476,
      "condition_id": "0x740cfdbafa8d1b1d51729da79b05e641158d3a7c889175dab1eab20a2c92b5cc",
      "clob_token_up": "83511279567738325562016865404511480598726292757090195771777541218161914729159",
      "clob_token_down": "66091509674921971407227514952521456996907573303653223323107401767726760115252",
      "final_volume": 202849.44,
      "final_liquidity": 12435.04,
      "coin_price_end": 67611.61304387,
      "resolved_at": "2026-03-31T16:55:25Z",
      "created_at": "2026-03-31T16:50:00.943587Z",
      "updated_at": "2026-03-31T17:21:20.768590Z"
    }
  ],
  "total": 2289,
  "limit": 50,
  "offset": 0,
  "warning": null
}
```

### Data access limits by plan

| Plan           | BTC 5m & 15m | BTC 1h & 4h | BTC 24h | ETH/SOL Polymarket | Binance Spot | Binance Futures |
| -------------- | ------------ | ----------- | ------- | ------------------ | ------------ | --------------- |
| Starter (Free) | Last 50      | Last 24     | Last 5  | --                 | --           | --              |
| Pro            | 31 days      | 31 days     | 31 days | 31 days            | 31 days      | 31 days         |
| Suite          | 31 days      | 31 days     | 31 days | 31 days            | 31 days      | 31 days         |