> 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/polymarket-trades.md).

# Polymarket Trades

### Request Body (JSON)

```json
{
    "agent_id": 556,
    "params": {
        "proxy_wallet": "ALL",
        "condition_id": "ALL",
        "market_slug": "bitcoin-up-or-down-january-9-10am-et",
        "side": "BUY",
        "start_time": "1767973812",
        "end_time": "1767973860"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
```

***

### Available Filters

| Parameter      | Type                    | Description                              | Example                                  |
| -------------- | ----------------------- | ---------------------------------------- | ---------------------------------------- |
| `market_slug`  | String                  | Filter trades by specific market         | `"bitcoin-up-or-down-january-9-10am-et"` |
| `proxy_wallet` | String                  | Wallet address executing the trade       | `"0xabc123..."`                          |
| `condition_id` | String                  | Ethereum condition ID for the market     | `"0x..."`                                |
| `start_time`   | String (Unix timestamp) | Trades after this timestamp (inclusive)  | `"1700000000"`                           |
| `end_time`     | String (Unix timestamp) | Trades before this timestamp (inclusive) | `"1705000000"`                           |
| `side`         | String                  | Trade direction (BUY or SELL)            | `"SELL"`                                 |

<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": 556,
    "params": {
        "proxy_wallet": "ALL",
        "condition_id": "ALL",
        "market_slug": "bitcoin-up-or-down-january-9-10am-et",
        "side": "BUY",
        "start_time": "1767973812",
        "end_time": "1767973860"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}'
```

</details>

***

### Response Fields

| Field             | Type              | Description                          |
| ----------------- | ----------------- | ------------------------------------ |
| id                | String            | Unique trade identifier              |
| condition\_id     | String            | Ethereum condition ID for the market |
| price             | Float             | Price per share (0–1 range)          |
| side              | String            | Trade direction (BUY or SELL)        |
| size              | Float             | Number of shares traded              |
| timestamp         | String (ISO 8601) | Timestamp of trade execution         |
| transaction\_hash | String            | Ethereum transaction hash            |
| slug              | String            | Market identifier                    |
| outcome           | String            | Trade outcome (e.g., "Yes", "No")    |
| proxy\_wallet     | String            | Wallet address executing the trade   |

<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 Unix timestamps (as strings) for `start_time` and `end_time` filtering
* Combine `market_slug` and time filters for focused analysis
* Use `side` parameter to filter by trade direction ("BUY" or "SELL")
* Use pagination for large datasets to avoid timeouts
* Transaction hashes can be used to verify trades on-chain
* Combine multiple filters for sophisticated queries