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

# Kalshi Trades

> Retrieve trade history from Kalshi markets, filtered by ticker and time range.

**Platform:** Kalshi\
**Endpoint:** `POST /v2/semantic/retrieve/parameterized`\
**Authentication:** Bearer token

## Query parameters

All requests use `agent_id` `573` (Kalshi Trades). Set filters inside `params` in the playground — all values must be strings.

| Parameter | Type | Description |
| - | - | - |
| `ticker` | String | Market ticker identifying the outcome traded. |
| `start_time` | String | Trades at or after this Unix timestamp in seconds. |
| `end_time` | String | Trades at or before this Unix timestamp in seconds. |

## Example Request

```bash cURL theme={null}
curl --request POST \
  --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "agent_id": 573,
  "params": {
    "ticker": "KXSOL15M-26MAR180730-30",
    "start_time": "1773589812",
    "end_time": "1774021812"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
}'
```

```python Python theme={null}
import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 573,
    "params": {
        "ticker": "KXSOL15M-26MAR180730-30",
        "start_time": "1773589812",
        "end_time": "1774021812"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())
```

```javascript JavaScript theme={null}
const response = await fetch("https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "agent_id": 573,
  "params": {
    "ticker": "KXSOL15M-26MAR180730-30",
    "start_time": "1773589812",
    "end_time": "1774021812"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

const data = await response.json();
```

## Example Response

```json theme={null}
{
  "timestamp": "",
  "params": {
    "end_time": "1774021812",
    "start_time": "1773589812",
    "ticker": "KXSOL15M-26MAR180730-30"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "count": 9,
        "created_time": "2026-03-18T11:29:25.354888Z",
        "no_price": 99.9,
        "taker_side": "yes",
        "ticker": "KXSOL15M-26MAR180730-30",
        "trade_id": "cba52037-21c4-6b04-6544-a2be4124d98e",
        "yes_price": 0.1
      },
      {
        "count": 200,
        "created_time": "2026-03-18T11:29:23.814603Z",
        "no_price": 99.9,
        "taker_side": "no",
        "ticker": "KXSOL15M-26MAR180730-30",
        "trade_id": "4143238d-eb74-75c4-3607-d1b2ea1f0abc",
        "yes_price": 0.1
      }
    ]
  }
}
```

## Response Fields

| Field | Type | Description |
| - | - | - |
| `count` | Integer | Number of shares/contracts traded in this transaction |
| `created_time` | String (ISO 8601) | Timestamp when the trade was executed |
| `no_price` | Integer | Price of the **No** outcome at the time of the trade |
| `taker_side` | String | Side taken by the taker in the trade (`yes` or `no`) |
| `ticker` | String | Ticker symbol identifying the market outcome traded |
| `trade_id` | String (UUID) | Unique identifier for the trade |
| `yes_price` | Integer | Price of the **Yes** outcome at the time of the trade (typically in cents, 0–100) |


## OpenAPI

````yaml /api-reference/kalshi-trades.openapi.json POST /api/v2/semantic/retrieve/parameterized
openapi: 3.1.0
info:
  title: Falcon API — Kalshi Trades
  version: 1.0.0
servers:
  - url: https://narrative.agent.heisenberg.so
    description: Production
security:
  - bearerAuth: []
paths:
  /api/v2/semantic/retrieve/parameterized:
    post:
      tags:
        - Kalshi
      summary: Kalshi Trades
      description: >-
        Retrieve trade history from Kalshi markets, filtered by ticker and time
        range.
      operationId: kalshiTrades
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KalshiTradesRequest'
            examples:
              default:
                summary: Trades for a ticker and time range
                value:
                  agent_id: 573
                  params:
                    ticker: KXSOL15M-26MAR180730-30
                    start_time: '1773589812'
                    end_time: '1774021812'
                  pagination:
                    limit: 10
                    offset: 0
                  formatter_config:
                    format_type: raw
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KalshiTradesResponse'
        '400':
          description: Bad request — check params
        '401':
          description: Unauthorized — check your Bearer token
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST \
              --url https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized \
              --header 'Authorization: Bearer YOUR_TOKEN' \
              --header 'Content-Type: application/json' \
              --data '{
              "agent_id": 573,
              "params": {
                "ticker": "KXSOL15M-26MAR180730-30",
                "start_time": "1773589812",
                "end_time": "1774021812"
              },
              "pagination": { "limit": 10, "offset": 0 },
              "formatter_config": { "format_type": "raw" }
            }'
        - lang: python
          label: Python
          source: |-
            import requests

            response = requests.post(
                "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
                headers={"Authorization": "Bearer YOUR_TOKEN"},
                json={
                    "agent_id": 573,
                    "params": {
                        "ticker": "KXSOL15M-26MAR180730-30",
                        "start_time": "1773589812",
                        "end_time": "1774021812",
                    },
                    "pagination": {"limit": 10, "offset": 0},
                    "formatter_config": {"format_type": "raw"},
                },
            )

            print(response.json())
        - lang: javascript
          label: JavaScript
          source: |-
            const response = await fetch(
              "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
              {
                method: "POST",
                headers: {
                  Authorization: "Bearer YOUR_TOKEN",
                  "Content-Type": "application/json",
                },
                body: JSON.stringify({
                  agent_id: 573,
                  params: {
                    ticker: "KXSOL15M-26MAR180730-30",
                    start_time: "1773589812",
                    end_time: "1774021812",
                  },
                  pagination: { limit: 10, offset: 0 },
                  formatter_config: { format_type: "raw" },
                }),
              }
            );

            const data = await response.json();
components:
  schemas:
    KalshiTradesRequest:
      type: object
      required:
        - params
      properties:
        agent_id:
          type: integer
          enum:
            - 573
          default: 573
          x-default: 573
          description: Kalshi Trades agent ID.
        params:
          $ref: '#/components/schemas/KalshiTradesParams'
        pagination:
          $ref: '#/components/schemas/KalshiTradesPagination'
        formatter_config:
          $ref: '#/components/schemas/KalshiTradesFormatterConfig'
    KalshiTradesResponse:
      type: object
      readOnly: true
      properties:
        timestamp:
          type: string
          readOnly: true
        params:
          $ref: '#/components/schemas/KalshiTradesResponseParams'
        pagination:
          type: object
          readOnly: true
          properties:
            limit:
              type: integer
              readOnly: true
            offset:
              type: integer
              readOnly: true
            has_more:
              type: boolean
              readOnly: true
        data:
          type: object
          readOnly: true
          properties:
            results:
              type: array
              readOnly: true
              items:
                type: object
                readOnly: true
                additionalProperties: true
        request_id:
          type: string
          readOnly: true
    KalshiTradesParams:
      type: object
      description: Filter parameters. All values must be strings.
      additionalProperties: false
      required:
        - ticker
      properties:
        ticker:
          type: string
          default: KXSOL15M-26MAR180730-30
          description: Market ticker identifying the outcome traded.
        start_time:
          type: string
          default: '1773589812'
          description: Trades at or after this Unix timestamp in seconds, inclusive.
        end_time:
          type: string
          default: '1774021812'
          description: Trades at or before this Unix timestamp in seconds, inclusive.
    KalshiTradesPagination:
      type: object
      properties:
        limit:
          type: integer
          minimum: 1
          maximum: 200
          default: 10
          description: Maximum number of records returned per request.
        offset:
          type: integer
          minimum: 0
          default: 0
          description: Number of records to skip before returning results.
    KalshiTradesFormatterConfig:
      type: object
      properties:
        format_type:
          type: string
          enum:
            - raw
          default: raw
          description: Output format. Use "raw" for structured JSON.
    KalshiTradesResponseParams:
      type: object
      readOnly: true
      properties:
        ticker:
          type: string
          readOnly: true
        start_time:
          type: string
          readOnly: true
        end_time:
          type: string
          readOnly: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your Falcon API key from the dashboard

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.