> For the complete documentation index, see [llms.txt](https://falcon-bot.gitbook.io/falcon-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://falcon-bot.gitbook.io/falcon-api/market-data/markets/polymarket-markets.md).

# Polymarket Markets

Access comprehensive Polymarket prediction market data and trade history through the Falcon API. This documentation covers all available endpoints, parameters, and use cases for Polymarket data.

**Platform:** Polymarket\
**Base URL:** `https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized`\
**Authentication:** Bearer token

### Request Body (JSON)

```json
{
    "agent_id": 574,
    "params": {
        "min_volume": "100",
        "condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
        "market_slug": "bitcoin-up-or-down-january-17-3pm-et",
        "event_slug": "bitcoin-up-or-down-january-17-3pm-et",
        "end_date_min": "1768467703",
        "end_date_max": "1769213303",
        "closed": "True"
    },
    "pagination": {
        "limit": 100,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

{% hint style="info" %}
`agent_id: 574` corresponds to Polymarket market data.
{% endhint %}

***

### Available Filters

| Parameter      | Type                    | Description                                                                                                 | Example        |
| -------------- | ----------------------- | ----------------------------------------------------------------------------------------------------------- | -------------- |
| `closed`       | String (Boolean)        | Market status - "False" for open, "True" for closed. If not set, both open and closed markets are returned. | `"False"`      |
| `min_volume`   | String                  | Minimum trading volume filter                                                                               | `"1000"`       |
| `market_slug`  | String                  | Market identifier or keyword search                                                                         | `"bitcoin"`    |
| `end_date_min` | String (Unix timestamp) | Filter markets ending after this timestamp (inclusive)                                                      | `"1701388800"` |
| `end_date_max` | String (Unix timestamp) | Filter markets ending before this timestamp (inclusive)                                                     | `"1704067199"` |

<details>

<summary>Example Request (cURL)</summary>

```bash
curl --location 'https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "agent_id": 574,
    "params": {
        "min_volume": "100",
        "condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
        "market_slug": "bitcoin-up-or-down-january-17-3pm-et",
        "event_slug": "bitcoin-up-or-down-january-17-3pm-et",
        "end_date_min": "1768467703",
        "end_date_max": "1769213303",
        "closed": "True"
    },
    "pagination": {
        "limit": 100,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

</details>

***

### Response Fields

| Field             | Type              | Description                                 |
| ----------------- | ----------------- | ------------------------------------------- |
| `condition_id`    | String            | Ethereum condition ID for the market        |
| `question`        | String            | Market question/title                       |
| `slug`            | String            | URL-friendly market identifier              |
| `event_slug`      | String            | URL-friendly event identifier               |
| `closed`          | Boolean           | Market status (false = open, true = closed) |
| `volume_total`    | Float             | Total trading volume                        |
| `start_date`      | String (ISO 8601) | Market start timestamp                      |
| `end_date`        | String (ISO 8601) | Market end/resolution timestamp             |
| `close_date`      | String (ISO 8601) | Market close timestamp                      |
| `side_a_token_id` | String            | Token ID of the first side of the market    |
| `side_b_token_id` | String            | Token ID of the second side of the market   |
| `side_a_outcome`  | String            | Outcome of the first side of the market     |
| `side_b_outcome`  | String            | Outcome of the second side of the market    |
| `winning_outcome` | String            | Winning outcome of the market               |

<details>

<summary>Example Response</summary>

```bash
{
  "timestamp": "",
  "params": {
    "closed": "True",
    "condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
    "end_date_max": "1769213303",
    "end_date_min": "1768467703",
    "event_slug": "bitcoin-up-or-down-january-17-3pm-et",
    "market_slug": "bitcoin-up-or-down-january-17-3pm-et",
    "min_volume": "100"
  },
  "pagination": {
    "limit": 100,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "closed": true,
        "closed_date": "2026-01-17T22:07:24Z",
        "condition_id": "0xeaff81adbcd9dcd88a73a41402cb4a6b87234213a6b3ecaa0441126cde6d5b7f",
        "end_date": "2026-01-17T21:00:00Z",
        "event_slug": "bitcoin-up-or-down-january-17-3pm-et",
        "question": "Bitcoin Up or Down - January 17, 3PM ET",
        "side_a_outcome": "Up",
        "side_a_token_id": "54962395221233298907357564706944806093710338832907683007646483576474886134345",
        "side_b_outcome": "Down",
        "side_b_token_id": "99436386356623686771311452414494038846982778884699006473918967429453507432222",
        "slug": "bitcoin-up-or-down-january-17-3pm-et",
        "start_date": "2026-01-15T20:01:06.506385Z",
        "volume_total": 104456.760687,
        "winning_outcome": "Up"
      }
    ]
  }
}
```

</details>

***

### Notes

* Use `closed: "False"` to get only tradeable (open) markets
* Combine `min_volume` with `closed` to find liquid, active markets
* Use partial slugs for broad searches (e.g., "nba" finds all NBA-related markets)
* Use `offset` for pagination through large result sets
* The `has_more` field indicates if additional pages exist
* Use `end_date_min` and `end_date_max` with Unix timestamps (as strings) to filter by market end dates