Orderbook

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": 572,
  "params": {
    "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
    "start_time": "1769902905868",
    "end_time": "1770034843377"
  },
  "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": 572,
        "params": {
            "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
            "start_time": "1769902905868",
            "end_time": "1770034843377",
        },
        "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: 572,
      params: {
        token_id: "69435545313357346912686520645149775930858973121193492847015767460308803044235",
        start_time: "1769902905868",
        end_time: "1770034843377",
      },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" },
    }),
  }
);

const data = await response.json();

{
  "timestamp": "<string>",
  "params": {
    "token_id": "<string>",
    "start_time": "<string>",
    "end_time": "<string>"
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "token_id": "<string>",
        "timestamp": "<string>",
        "best_bid": "<string>",
        "best_ask": "<string>",
        "spread": "<string>",
        "bid_depth": "<string>",
        "ask_depth": "<string>"
      }
    ]
  },
  "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": 572,
  "params": {
    "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
    "start_time": "1769902905868",
    "end_time": "1770034843377"
  },
  "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": 572,
        "params": {
            "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
            "start_time": "1769902905868",
            "end_time": "1770034843377",
        },
        "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: 572,
      params: {
        token_id: "69435545313357346912686520645149775930858973121193492847015767460308803044235",
        start_time: "1769902905868",
        end_time: "1770034843377",
      },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" },
    }),
  }
);

const data = await response.json();

{
  "timestamp": "<string>",
  "params": {
    "token_id": "<string>",
    "start_time": "<string>",
    "end_time": "<string>"
  },
  "pagination": {
    "limit": 123,
    "offset": 123,
    "has_more": true
  },
  "data": {
    "results": [
      {
        "token_id": "<string>",
        "timestamp": "<string>",
        "best_bid": "<string>",
        "best_ask": "<string>",
        "spread": "<string>",
        "bid_depth": "<string>",
        "ask_depth": "<string>"
      }
    ]
  },
  "request_id": "<string>"
}

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

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": 572,
  "params": {
    "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
    "start_time": "1769902905868",
    "end_time": "1770034843377"
  },
  "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": 572,
    "params": {
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
        "start_time": "1769902905868",
        "end_time": "1770034843377"
    },
    "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": 572,
  "params": {
    "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
    "start_time": "1769902905868",
    "end_time": "1770034843377"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

const data = await response.json();

Available filters

String

required

Token ID of the market outcome to retrieve orderbook snapshots for.

String

Return snapshots at or after this Unix timestamp in milliseconds (as a string).

String

Return snapshots at or before this Unix timestamp in milliseconds (as a string).

Example Response

{
  "timestamp": "",
  "params": {
    "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
    "start_time": "1769902905868",
    "end_time": "1770034843377"
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "token_id": "69435545313357346912686520645149775930858973121193492847015767460308803044235",
        "timestamp": "2026-04-10T18:00:00Z",
        "best_bid": "0.5750",
        "best_ask": "0.5850",
        "spread": "0.0100",
        "bid_depth": "125400.30",
        "ask_depth": "98200.15"
      }
    ]
  }
}

Response Fields

Field	Type	Description
`token_id`	String	Token ID
`timestamp`	String (ISO 8601)	Snapshot time
`best_bid`	String (Decimal)	Highest bid price
`best_ask`	String (Decimal)	Lowest ask price
`spread`	String (Decimal)	Bid-ask spread
`bid_depth`	String (Decimal)	Total bid side liquidity (USD)
`ask_depth`	String (Decimal)	Total ask side liquidity (USD)

Notes

Wide spreads indicate illiquid markets — beware of slippage.

Compare bid/ask depth to assess which side has more support.

Track spread over time to detect liquidity drying up before game start

Authorizations

Authorization

string

header

required

Your Falcon API key from the dashboard

Body

application/json

params

object

required

Filter parameters. All values must be strings.

Hide child attributes

params.token_id

string

required

Token ID of the market outcome.

params.start_time

string

Return snapshots at or after this Unix timestamp in milliseconds, as a string.

params.end_time

string

Return snapshots at or before this Unix timestamp in milliseconds, as a string.

agent_id

enum<integer>

default:572

Orderbook agent ID.

Available options:

572

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

Hide child attributes

params.token_id

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

Hide child attributes

data.results.token_id

string

read-only

Token ID

data.results.timestamp

string

read-only

Snapshot time (ISO 8601)

data.results.best_bid

string

read-only

Highest bid price

data.results.best_ask

string

read-only

Lowest ask price

data.results.spread

string

read-only

Bid-ask spread

data.results.bid_depth

string

read-only

Total bid side liquidity (USD)

data.results.ask_depth

string

read-only

Total ask side liquidity (USD)

request_id

string

read-only

Overview

Composite workflows

Polymarket

Kalshi

Social Intelligence

Example Request

Available filters

Example Response

Response Fields

Notes

Authorizations

Body

Response

​Example Request

​Available filters

​Example Response

​Response Fields

​Notes

Authorizations

Body

Response

Example Request

Available filters

Example Response

Response Fields

Notes