Polymarket Trades

cURL

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

import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 556,
    "params": {
        "proxy_wallet": "ALL",
        "condition_id": "ALL",
        "market_slug": "bitcoin-up-or-down-january-9-10am-et",
        "start_time": "1767973812",
        "end_time": "1767973860"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())

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

const data = await response.json();

{
  "timestamp": "<string>",
  "params": {
    "proxy_wallet": "<string>",
    "condition_id": "<string>",
    "market_slug": "<string>",
    "start_time": "<string>",
    "end_time": "<string>"
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "has_more": true
  },
  "data": {
    "results": [
      {}
    ]
  },
  "request_id": "<string>"
}

POST

api

semantic

retrieve

parameterized

cURL

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

import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 556,
    "params": {
        "proxy_wallet": "ALL",
        "condition_id": "ALL",
        "market_slug": "bitcoin-up-or-down-january-9-10am-et",
        "start_time": "1767973812",
        "end_time": "1767973860"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())

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

const data = await response.json();

{
  "timestamp": "<string>",
  "params": {
    "proxy_wallet": "<string>",
    "condition_id": "<string>",
    "market_slug": "<string>",
    "start_time": "<string>",
    "end_time": "<string>"
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "has_more": true
  },
  "data": {
    "results": [
      {}
    ]
  },
  "request_id": "<string>"
}

Platform: Polymarket
Endpoint: POST /v2/semantic/retrieve/parameterized
Authentication: Bearer token

Query parameters

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

Parameter	Type	Description
`proxy_wallet`	String	Filter by wallet address. Use `"ALL"` for every wallet.
`condition_id`	String	Market condition ID. Use `"ALL"` for every market.
`market_slug`	String	Filter by market slug (for example, `"bitcoin-up-or-down-january-9-10am-et"`).
`start_time`	String	Earliest trade time: Unix timestamp in seconds.
`end_time`	String	Latest trade time: Unix timestamp in seconds.

Example Request

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

import requests

response = requests.post(
    "https://narrative.agent.heisenberg.so/api/v2/semantic/retrieve/parameterized",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
    "agent_id": 556,
    "params": {
        "proxy_wallet": "ALL",
        "condition_id": "ALL",
        "market_slug": "bitcoin-up-or-down-january-9-10am-et",
        "start_time": "1767973812",
        "end_time": "1767973860"
    },
    "pagination": {
        "limit": 10,
        "offset": 0
    },
    "formatter_config": {
        "format_type": "raw"
    }
}
)

print(response.json())

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

const data = await response.json();

Example Response

{
  "timestamp": "",
  "params": {
    "condition_id": "ALL",
    "end_time": "1767973860",
    "market_slug": "bitcoin-up-or-down-january-9-10am-et",
    "proxy_wallet": "ALL",
    "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"
      }
    ]
  }
}

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 (for example, `"Yes"`, `"No"`)
`proxy_wallet`	String	Trader’s wallet address

Notes

Use Unix timestamps as strings for start_time and end_time. Combine them with market_slug for focused, time-bounded queries.

Use pagination for large datasets to avoid timeouts. The transaction_hash field can be used to verify any trade directly on-chain.

Combine multiple filters for sophisticated queries

Authorizations

Authorization

string

header

required

Your Falcon API key from the dashboard

Body

application/json

params

object

required

Query filter parameters. All values must be strings.

Hide child attributes

params.proxy_wallet

string

default:ALL

Filter by wallet address. Use "ALL" to include trades from every wallet.

params.condition_id

string

default:ALL

Ethereum condition ID for the market. Use "ALL" to include trades from every market.

params.market_slug

string

default:bitcoin-up-or-down-january-9-10am-et

Filter trades by a specific market (for example, "bitcoin-up-or-down-january-9-10am-et").

params.start_time

string

default:1767973812

Trades at or after this Unix timestamp in seconds, inclusive, as a string (for example, "1767973812").

params.end_time

string

default:1767973860

Trades at or before this Unix timestamp in seconds, inclusive, as a string (for example, "1767973860").

agent_id

enum<integer>

default:556

Polymarket Trades agent ID.

Available options:

556

pagination

object

Hide child attributes

pagination.limit

integer

default:10

Maximum number of records returned per request.

Required range: 1 <= x <= 200

pagination.offset

integer

default:0

Number of records to skip before returning results.

Required range: x >= 0

formatter_config

object

Hide child attributes

formatter_config.format_type

enum<string>

default:raw

Output format. Use "raw" for structured JSON.

Available options:

raw

Response

Success

timestamp

string

read-only

params

object

read-only

Echo of request filter parameters returned in the response.

Hide child attributes

params.proxy_wallet

string

read-only

params.condition_id

string

read-only

params.market_slug

string

read-only

params.start_time

string

read-only

params.end_time

string

read-only

pagination

object

read-only

Hide child attributes

pagination.limit

integer

read-only

pagination.offset

integer

read-only

pagination.has_more

boolean

read-only

data

object

read-only

Hide child attributes

data.results

object[]

read-only

request_id

string

read-only

Overview

Composite workflows

Polymarket

Kalshi

Social Intelligence

Polymarket Trades

Query parameters

Example Request

Example Response

Response Fields

Notes

Authorizations

Body

Response

​Query parameters

​Example Request

​Example Response

​Response Fields

​Notes

Authorizations

Body

Response

Query parameters

Example Request

Example Response

Response Fields

Notes