Polymarket Price Jumps

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": 596,
  "params": {
    "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
    "resolution": "15m",
    "min_change_pct": "10",
    "lookback_hours": "24"
  },
  "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": 596,
        "params": {
            "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
            "resolution": "15m",
            "min_change_pct": "10",
            "lookback_hours": "24",
        },
        "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: 596,
      params: {
        token_id:
          "99787107393065498256888522570939526464960671564345515510320748534859284179297",
        resolution: "15m",
        min_change_pct: "10",
        lookback_hours: "24",
      },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" },
    }),
  }
);

const data = await response.json();

{
  "timestamp": "<string>",
  "params": {
    "token_id": "<string>",
    "resolution": "<string>",
    "min_change_pct": "<string>",
    "lookback_hours": "<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": 596,
  "params": {
    "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
    "resolution": "15m",
    "min_change_pct": "10",
    "lookback_hours": "24"
  },
  "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": 596,
        "params": {
            "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
            "resolution": "15m",
            "min_change_pct": "10",
            "lookback_hours": "24",
        },
        "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: 596,
      params: {
        token_id:
          "99787107393065498256888522570939526464960671564345515510320748534859284179297",
        resolution: "15m",
        min_change_pct: "10",
        lookback_hours: "24",
      },
      pagination: { limit: 10, offset: 0 },
      formatter_config: { format_type: "raw" },
    }),
  }
);

const data = await response.json();

{
  "timestamp": "<string>",
  "params": {
    "token_id": "<string>",
    "resolution": "<string>",
    "min_change_pct": "<string>",
    "lookback_hours": "<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 596 (Price Jumps). Set filters inside params in the playground — all values must be strings.

Parameter	Type	Description
`token_id`	String	Token ID of the market outcome. Get this from Polymarket Markets (`side_a_token_id` / `side_b_token_id`).
`resolution`	String	Candle bucket size: `1m`, `5m`, `15m`, `1h`, `4h`, or `1d`.
`min_change_pct`	String	Minimum absolute percent price change to qualify as a jump (for example, `"10"`).
`lookback_hours`	String	Hours to scan back from now (for example, `"24"`).

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": 596,
  "params": {
    "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
    "resolution": "15m",
    "min_change_pct": "10",
    "lookback_hours": "24"
  },
  "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": 596,
    "params": {
        "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
        "resolution": "15m",
        "min_change_pct": "10",
        "lookback_hours": "24"
    },
    "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": 596,
  "params": {
    "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
    "resolution": "15m",
    "min_change_pct": "10",
    "lookback_hours": "24"
  },
  "pagination": {
    "limit": 10,
    "offset": 0
  },
  "formatter_config": {
    "format_type": "raw"
  }
})
});

const data = await response.json();

Example Response

{
  "timestamp": "",
  "params": {
    "lookback_hours": "24",
    "min_change_pct": "10",
    "resolution": "15m",
    "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297"
  },
  "pagination": {
    "limit": 10,
    "offset": 0,
    "has_more": false
  },
  "data": {
    "results": [
      {
        "change_pct": "-16.67",
        "condition_id": "0xbcacd5a055f5a9ced6f69f122216c073dd6987d08253fc07bbcc168fa5b81d55",
        "direction": "down",
        "jump_time": "2026-04-06T02:00:00Z",
        "outcome": "Yes",
        "price_after": "0.1500",
        "price_before": "0.1800",
        "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
        "trade_count": 28,
        "volume": "7350.07"
      },
      {
        "change_pct": "14.29",
        "condition_id": "0xbcacd5a055f5a9ced6f69f122216c073dd6987d08253fc07bbcc168fa5b81d55",
        "direction": "up",
        "jump_time": "2026-04-05T19:30:00Z",
        "outcome": "Yes",
        "price_after": "0.1600",
        "price_before": "0.1400",
        "token_id": "99787107393065498256888522570939526464960671564345515510320748534859284179297",
        "trade_count": 3,
        "volume": "264.35"
      }
    ]
  },
  "request_id": ""
}

Response fields

Each object in data.results describes one qualifying candle-to-candle move.

Field	Type	Description
`jump_time`	String (ISO 8601)	Timestamp of the candle where the jump occurred
`condition_id`	String	Hex condition ID of the market
`token_id`	String	Token ID of the outcome
`outcome`	String	Outcome label
`price_before`	String (Decimal)	Price at the start of the candle
`price_after`	String (Decimal)	Price at the end of the candle
`change_pct`	String (Decimal)	Percentage change (negative = price dropped)
`direction`	String	`up` or `down`
`volume`	String (Decimal)	Volume during the candle
`trade_count`	Integer	Number of trades during the candle

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

default:99787107393065498256888522570939526464960671564345515510320748534859284179297

required

Token ID of the market outcome. Get this from Polymarket Markets (side_a_token_id / side_b_token_id).

params.resolution

enum<string>

default:15m

required

Candle bucket size (for example, "15m").

Available options:

1m,

5m,

15m,

1h,

4h,

1d

params.min_change_pct

string

default:10

required

Minimum absolute percent price change to qualify as a jump (for example, "10").

params.lookback_hours

string

default:24

required

Hours to scan back from now (for example, "24").

agent_id

enum<integer>

default:596

Price Jumps agent ID.

Available options:

596

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.resolution

string

read-only

params.min_change_pct

string

read-only

params.lookback_hours

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 Price Jumps

Query parameters

Example Request

Example Response

Response fields

Authorizations

Body

Response

​Query parameters

​Example Request

​Example Response

​Response fields

Authorizations

Body

Response

Query parameters

Example Request

Example Response

Response fields