{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ApiResponseTradeIntentBucketArray",
"description": "API response containing trade intent buckets. `meta` carries `symbol`, `venue`, `built_through`, and `preliminary_row_count` when preliminary buckets are present.",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"description": "One bucket of trade intent for one market. Both sides of every trade are counted, so the eight intent buckets plus `mm_usd` sum to twice the bucket's traded notional, less delisting settlements, which are in no bucket. Winners and losers are aggregates over the market's trailing 72 hours: no wallet is named.",
"type": "object",
"required": [
"close",
"flip_ls",
"flip_sl",
"is_final",
"losers_count",
"losers_flow",
"losers_gross",
"losers_net",
"method",
"mm_usd",
"open_long",
"open_short",
"preliminary",
"preliminary_from",
"preliminary_from_ms",
"price_source",
"quality",
"stop_long",
"stop_short",
"timestamp",
"timestamp_ms",
"tp_long",
"tp_short",
"winners_count",
"winners_flow",
"winners_gross",
"winners_net"
],
"properties": {
"close": {
"description": "The price the bucket's end is marked at. Null on second intervals.",
"type": "number",
"format": "double",
"nullable": true,
"example": 81448
},
"flip_ls": {
"description": "USD sold that took a position from long to short in one fill. To the cent.",
"type": "number",
"format": "double",
"example": 683012.29
},
"flip_sl": {
"description": "USD bought that took a position from short to long in one fill. To the cent.",
"type": "number",
"format": "double",
"example": 334456.02
},
"is_final": {
"description": "The bucket is complete and will not change.",
"type": "boolean",
"example": true
},
"losers_count": {
"description": "Losers counted at full weight. Null on second intervals and when `quality` is `quarantined`.",
"type": "integer",
"nullable": true,
"example": 16
},
"losers_flow": {
"description": "The same for the market's losers.",
"type": "number",
"format": "double",
"nullable": true,
"example": -607408.26
},
"losers_gross": {
"description": "The losers' gross position in USD at the bucket's end. Null on second intervals and when `quality` is `quarantined`.",
"type": "number",
"format": "double",
"nullable": true,
"example": 155965344.67
},
"losers_net": {
"description": "The losers' net position in USD at the bucket's end. Null on second intervals and when `quality` is `quarantined`.",
"type": "number",
"format": "double",
"nullable": true,
"example": 46895101.67
},
"method": {
"description": "Version of the method the bucket was computed with: `who/3`, or `who/2` on older rows.",
"type": "string",
"example": "who/3"
},
"mm_usd": {
"description": "USD traded by wallets classified as market makers, counted here instead of in an intent bucket. To the cent.",
"type": "number",
"format": "double",
"example": 84960401.5
},
"open_long": {
"description": "USD bought to open or increase a long. To the cent.",
"type": "number",
"format": "double",
"example": 50638693.18
},
"open_short": {
"description": "USD sold to open or increase a short. To the cent.",
"type": "number",
"format": "double",
"example": 41296459.21
},
"preliminary": {
"description": "The bucket holds figures computed live after the archive's end. They are replaced by the archived figures once those hours are built.",
"type": "boolean",
"example": false
},
"preliminary_from": {
"description": "Where the bucket's preliminary figures begin: inside the bucket, or at its open when the whole bucket is preliminary. Null when `preliminary` is false.",
"type": "string",
"format": "date-time",
"nullable": true,
"example": null
},
"preliminary_from_ms": {
"description": "`preliminary_from` as Unix milliseconds.",
"type": "integer",
"format": "int64",
"nullable": true,
"example": null
},
"price_source": {
"description": "Where `close` comes from: `mark`, `oracle` (a HIP-3 market without a stored mark), `carried` (the last of those when none is recent) or `trade`. Null on second intervals.",
"type": "string",
"enum": [
"mark",
"oracle",
"carried",
"trade"
],
"nullable": true,
"example": "mark"
},
"quality": {
"description": "`ok`; `partial` while the method's 7-day lookbacks were not yet full; `quarantined` when an input of the bucket failed a continuity check, so the winners' and losers' figures are null. Intent buckets and `mm_usd` are always served.",
"type": "string",
"enum": [
"ok",
"partial",
"quarantined"
],
"example": "ok"
},
"stop_long": {
"description": "USD sold to reduce or close a long at a loss or break-even, or by liquidation or auto-deleveraging. To the cent.",
"type": "number",
"format": "double",
"example": 30236676.09
},
"stop_short": {
"description": "USD bought to reduce or close a short at a loss or break-even, or by liquidation or auto-deleveraging. To the cent.",
"type": "number",
"format": "double",
"example": 12304052.04
},
"timestamp": {
"description": "Bucket open time, RFC 3339 UTC.",
"type": "string",
"format": "date-time",
"example": "2026-10-23T00:00:00.000Z"
},
"timestamp_ms": {
"description": "`timestamp` as Unix milliseconds.",
"type": "integer",
"format": "int64",
"example": 1792713600000
},
"tp_long": {
"description": "USD sold to reduce or close a long at a profit (closed PnL above zero, not forced). To the cent.",
"type": "number",
"format": "double",
"example": 8084342.05
},
"tp_short": {
"description": "USD bought to reduce or close a short at a profit (closed PnL above zero, not forced). To the cent.",
"type": "number",
"format": "double",
"example": 29240753.02
},
"winners_count": {
"description": "Winners counted at full weight. Null on second intervals and when `quality` is `quarantined`.",
"type": "integer",
"nullable": true,
"example": 17
},
"winners_flow": {
"description": "What the market's winners bought less what they sold in the bucket, in USD, weighted as the cohort stood at the previous hour's close. Null when `quality` is `quarantined`.",
"type": "number",
"format": "double",
"nullable": true,
"example": -2861558.86
},
"winners_gross": {
"description": "The winners' gross position in USD at the bucket's end. Null on second intervals and when `quality` is `quarantined`.",
"type": "number",
"format": "double",
"nullable": true,
"example": 121926882.58
},
"winners_net": {
"description": "The winners' net position in USD (long positive) at the bucket's end. Null on second intervals and when `quality` is `quarantined`.",
"type": "number",
"format": "double",
"nullable": true,
"example": -77011655.75
}
}
}
},
"meta": {
"description": "Response metadata. Every 2xx JSON response carries `meta.request_id`; list payloads add `count`; cursor-paged routes add `has_more` and, when another page follows, `next_cursor`; per-symbol routes add `symbol` and `venue`. Fields that do not apply to a route are omitted.",
"type": "object",
"required": [
"request_id"
],
"properties": {
"as_of": {
"description": "Positioning: the 5-minute close the records describe, equal to each record's `window_end`.",
"type": "string",
"format": "date-time"
},
"built_through": {
"description": "Trade intent: how far the series is built. A second without a record had no trades up to this instant; after it nothing is known yet.",
"type": "string",
"format": "date-time"
},
"clamped_to": {
"description": "The boundary the request's `end` was clamped to, when clamping occurred.",
"type": "string",
"format": "date-time",
"nullable": true
},
"count": {
"description": "Number of records returned",
"type": "integer"
},
"coverage_from": {
"description": "Earliest coverage for the requested symbol and data type. Present only when the requested window ends before coverage begins.",
"type": "string",
"format": "date-time"
},
"finalized_through": {
"description": "Two-tier datasets (Lighter trades): data at or before this instant is final; later data is preliminary.",
"type": "string",
"format": "date-time"
},
"has_more": {
"description": "Cursor-paged routes: whether another page follows. `next_cursor` is present exactly when this is `true`. A final page can be empty when the previous page was exactly full; `has_more` is `false` on it.",
"type": "boolean"
},
"next_cursor": {
"description": "Opaque cursor for the next page, present exactly when `has_more` is `true`. Pass it back unchanged as `cursor` with the same filters. Do not parse or construct it.",
"type": "string"
},
"notice": {
"description": "Human-readable advisory about the response. Used when the requested window ends before coverage begins for the symbol, and on CVD responses that are one page of several; may carry other advisories in future.",
"type": "string"
},
"preliminary_row_count": {
"description": "Number of preliminary rows in this response, on routes that intentionally serve preliminary data (Lighter `/recent`, trade intent).",
"type": "integer",
"nullable": true
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"requested_end": {
"description": "The `end` the request asked for, echoed when it was clamped to `finalized_through`.",
"type": "string",
"format": "date-time",
"nullable": true
},
"symbol": {
"description": "Per-symbol routes: the canonical public symbol the response describes (for example `BTC`, `xyz:TSLA`, `HYPE-USDC`, `#0`).",
"type": "string",
"example": "BTC"
},
"venue": {
"description": "Per-symbol routes: the venue the response describes.",
"type": "string",
"enum": [
"hyperliquid",
"hip3",
"hip4",
"spot",
"lighter",
"rh-lighter"
],
"example": "hyperliquid"
}
}
},
"success": {
"type": "boolean",
"example": true
}
}
}