> 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/kalshi-markets.md).

# Kalshi Markets

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

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

### Request Body (JSON)

```bash
{
    "agent_id": 565,
    "params": {
        "ticker": "KXSOL15M-26MAR180800-00",
        "event_ticker": "KXSOL15M-26MAR180800",
        "title": "SOL price",
        "status": "finalized",
        "close_time_min": "1773589812",
        "close_time_max": "1774021812"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

***

### Available Filters

| Parameter        | Type   | Description                           | Example                    |
| ---------------- | ------ | ------------------------------------- | -------------------------- |
| `ticker`         | String | Exact Kalshi market ticker            | `"KXSL15M-26MAR180730-S0"` |
| `event_ticker`   | String | Exact Kalshi event ticker             | `"KXSL15M-26MAR180730"`    |
| `title`          | String | Search markets by title               | `"SOJ price"`              |
| `status`         | String | Market status (`active`, `finalized`) | `"finalized"`              |
| `close_time_min` | String | Minimum close time (Unix timestamp)   | `"1773589812"`             |
| `close_time_max` | String | Maximum close time (Unix timestamp)   | `"1774021812"`             |

<details>

<summary>Example Request <strong>(cURL)</strong></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": 565,
    "params": {
        "ticker": "KXSOL15M-26MAR180800-00",
        "event_ticker": "KXSOL15M-26MAR180800",
        "title": "SOL price",
        "status": "finalized",
        "close_time_min": "1773589812",
        "close_time_max": "1774021812"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

</details>

***

### Response Fields

| Field             | Type              | Description                               |
| ----------------- | ----------------- | ----------------------------------------- |
| `close_time`      | String (ISO 8601) | Timestamp when the market stopped trading |
| `created_time`    | String (ISO 8601) | Timestamp when the market was created     |
| `event_ticker`    | String            | Event ticker associated with the market   |
| `expiration_time` | String (ISO 8601) | Time when the market expires              |
| `last_price`      | Integer           | Last traded price                         |
| `open_time`       | String (ISO 8601) | Timestamp when trading opened             |
| `status`          | String            | Current market status                     |
| `ticker`          | String            | Market ticker                             |
| `title`           | String            | Market question                           |
| `volume`          | Integer           | Total trading volume                      |
| `volume_24h`      | Integer           | Trading volume in the last 24 hours       |
| `result`          | String            | Final outcome of the market               |

<details>

<summary>Example Response</summary>

```bash
{
  "timestamp": "",
  "params": {
    "close_time_max": "1774021812",
    "close_time_min": "1773589812",
    "event_ticker": "KXSOL15M-26MAR180800",
    "status": "finalized",
    "ticker": "KXSOL15M-26MAR180800-00",
    "title": "SOL price"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "close_time": "2026-03-18T12:00:00Z",
        "created_time": "2026-03-18T00:01:21.613032Z",
        "event_ticker": "KXSOL15M-26MAR180800",
        "expiration_time": "2026-03-25T12:00:00Z",
        "last_price": 0.8,
        "open_time": "2026-03-18T11:45:00Z",
        "result": "no",
        "status": "finalized",
        "ticker": "KXSOL15M-26MAR180800-00",
        "title": "SOL price up in next 15 mins?",
        "volume": 4422,
        "volume_24h": 4422
      }
    ]
  }
}
```

</details>

***

### Notes

* Use `status: "active"` to retrieve only **currently tradable markets**, excluding finalized or expired contracts.
* Search using `event_ticker` whenever you want to **retrieve all markets under a specific event**, such as a multi-contract prediction series.
* Use `title` with partial keywords to quickly locate **markets related to a specific topic or event**.
* Combine `close_time_min` and `close_time_max` to filter markets within a **specific expiration window**, which is useful for identifying short-term or long-term contracts.
* Compare `volume` and `volume_24h` to evaluate **overall market activity versus recent trading momentum**.
* Use `ticker` for **exact market lookups**, especially when retrieving data for a specific contract or building automated trading systems.