> 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/trade-data/trades/kalshi-trades.md).

# Kalshi Trades

### Request Body (JSON)

```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"
    }
}
```

***

### Available Filters

| Parameter    | Type                    | Description                                                                   | Example                     |
| ------------ | ----------------------- | ----------------------------------------------------------------------------- | --------------------------- |
| `ticker`     | String                  | Value of market ticker. This is an exact match.                               | `"KXBTC15M-26FEB030730-30"` |
| `start_time` | String (Unix timestamp) | Filter trades in which the created time is after this timestamp (inclusive).  | `"1770121317"`              |
| `end_time`   | String (Unix timestamp) | Filter trades in which the created time is before this timestamp (inclusive). | `"1770121748"`              |

<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": 573,
    "params": {
        "ticker": "KXSOL15M-26MAR180730-30",
        "start_time": "1773589812",
        "end_time": "1774021812"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

</details>

***

### Response Fields

#### 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) |

<details>

<summary>Example Response</summary>

```bash
{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "end_time": "1767973860",
    "market_slug": "bitcoin-up-or-down-january-9-10am-et",
    "proxy_wallet": "ALL",
    "side": "BUY",
    "start_time": "1767973812",
    "wallet_proxy": "ALL"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0x1e30835026c910cd5f676a504ce8c39666917f402dfe93bb46c19adf6b152c13",
        "outcome": "Down",
        "price": 0.001,
        "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed",
        "side": "BUY",
        "size": 225.23,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:51:00Z",
        "transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7_0xb07225fa95a2b5dd0f15b3f41f07657d9eb9e928268d4e5ae9fdf7e178049ac7",
        "outcome": "Down",
        "price": 0.001,
        "proxy_wallet": "0x11514fb5ef1e3fe110691243714fcf2182db1fed",
        "side": "BUY",
        "size": 14.99,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:51:00Z",
        "transaction_hash": "0x19320a9cfc47d70e2ac56c25b3555a34f402484a236267a8c220fa060eba74c7"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x828175e5fe3c6688e81bbcd09ac9fb9e4a7b2c135b33cc5311e768d673e09804_0xf47df1130870ac2c859a9719c01e79ecb0f41c1bab1de1d2fc085c7731ebc718",
        "outcome": "Up",
        "price": 0.993,
        "proxy_wallet": "0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e",
        "side": "BUY",
        "size": 69,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:50:40Z",
        "transaction_hash": "0x828175e5fe3c6688e81bbcd09ac9fb9e4a7b2c135b33cc5311e768d673e09804"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0xcd72b1e52c1c74d30f182a2cf5cfed2c6e9d324ffd093b4e1da669efe21b767e_0x99b851adb0c517abd4b5817b291daacfe2219856f491b724daa7f86637a32753",
        "outcome": "Up",
        "price": 0.99299999872234,
        "proxy_wallet": "0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e",
        "side": "BUY",
        "size": 302.114802,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:50:34Z",
        "transaction_hash": "0xcd72b1e52c1c74d30f182a2cf5cfed2c6e9d324ffd093b4e1da669efe21b767e"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x5a9fa64c0013b0aa553e15fcf730ba2e8a99b5d11cb880d18dbce8a8896ca9c3_0xae59422ee3f3209fa45dc6a9b7867e7e5a6754ceba4c383f1c210f157cbc5e3e",
        "outcome": "Up",
        "price": 0.9920000000000001,
        "proxy_wallet": "0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e",
        "side": "BUY",
        "size": 0.62,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:50:20Z",
        "transaction_hash": "0x5a9fa64c0013b0aa553e15fcf730ba2e8a99b5d11cb880d18dbce8a8896ca9c3"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0x5a9fa64c0013b0aa553e15fcf730ba2e8a99b5d11cb880d18dbce8a8896ca9c3_0xc32bb50de6ced5930857d78ce9d0fd8d11d848f898a6cbd246e9d50303dbfd13",
        "outcome": "Down",
        "price": 0.008,
        "proxy_wallet": "0x320691173909ec013a2e88b081e6188d7a2a11f9",
        "side": "BUY",
        "size": 0.62,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:50:20Z",
        "transaction_hash": "0x5a9fa64c0013b0aa553e15fcf730ba2e8a99b5d11cb880d18dbce8a8896ca9c3"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0xf7e628356e42bed95c100b673f15e8e43688955a802b1e282e85bcbb4bcd3275_0x73417193595744a08ad5e16639047825c68076cd0d84e312c768a98bc71a8097",
        "outcome": "Up",
        "price": 0.992,
        "proxy_wallet": "0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e",
        "side": "BUY",
        "size": 2.5,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:50:18Z",
        "transaction_hash": "0xf7e628356e42bed95c100b673f15e8e43688955a802b1e282e85bcbb4bcd3275"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0xf7e628356e42bed95c100b673f15e8e43688955a802b1e282e85bcbb4bcd3275_0xc32bb50de6ced5930857d78ce9d0fd8d11d848f898a6cbd246e9d50303dbfd13",
        "outcome": "Down",
        "price": 0.008,
        "proxy_wallet": "0x32526c1de010a670eed9a5fbddacccb551c17830",
        "side": "BUY",
        "size": 2.5,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:50:18Z",
        "transaction_hash": "0xf7e628356e42bed95c100b673f15e8e43688955a802b1e282e85bcbb4bcd3275"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0xa53c0c802a1cd0c2a43b52246c287e845f7389f63991ccb007d052cf644e63ba_0xc32bb50de6ced5930857d78ce9d0fd8d11d848f898a6cbd246e9d50303dbfd13",
        "outcome": "Down",
        "price": 0.008,
        "proxy_wallet": "0x8c573be6f79a6207b895eb726c3cf408db50cf0e",
        "side": "BUY",
        "size": 1.875,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:50:14Z",
        "transaction_hash": "0xa53c0c802a1cd0c2a43b52246c287e845f7389f63991ccb007d052cf644e63ba"
      },
      {
        "condition_id": "0x584654c869a3f1868f3ad1248e11ea988f3c4e332002839c6cac0e6db94485ee",
        "id": "0xa53c0c802a1cd0c2a43b52246c287e845f7389f63991ccb007d052cf644e63ba_0xe8cfd4de40487184f81a675df9ea6c42901349f6743c22a4e99379279f05d537",
        "outcome": "Up",
        "price": 0.9920000000000001,
        "proxy_wallet": "0x4bfb41d5b3570defd03c39a9a4d8de6bd8b8982e",
        "side": "BUY",
        "size": 1.875,
        "slug": "bitcoin-up-or-down-january-9-10am-et",
        "timestamp": "2026-01-09T15:50:14Z",
        "transaction_hash": "0xa53c0c802a1cd0c2a43b52246c287e845f7389f63991ccb007d052cf644e63ba"
      }
    ]
  }
}
```

</details>

***

### Notes

* Use `ticker` to retrieve **trade history for a specific contract**, which is useful for analyzing price behavior and execution patterns.
* Combine `start_time` and `end_time` to retrieve trades within a **specific time window**, such as a trading session or volatility event.
* Use smaller time ranges when querying **high-volume markets** to avoid extremely large result sets.
* Compare `yes_price` and `no_price` across trades to observe **price discovery and probability shifts** over time.
* Monitor `count` together with timestamps to identify **large trades or bursts of trading activity**.
* Use `taker_side` to analyze **market sentiment**, since it indicates whether the trade executed on the Yes or No side.