{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ApiResponseLighterLiquidationArray",
"description": "API response containing an array of native Lighter liquidation events",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"description": "Native Lighter liquidation event. Raw ask/bid account fields are preserved instead of a derived `liquidated_user`: the upstream payload does not reliably flag which side was liquidated, so the liquidated side is derived at read time from position signs. Margin and fee integer fields are raw upstream units.",
"type": "object",
"required": [
"ask_account",
"ask_order_id",
"bid_account",
"bid_order_id",
"block_height",
"is_maker_ask",
"liquidation_type",
"maker_allocated_margin_usdc_after",
"maker_allocated_margin_usdc_before",
"maker_entry_quote_before",
"maker_fee",
"maker_initial_margin_fraction_before",
"maker_position_sign_changed",
"maker_position_size_before",
"price",
"raw_json",
"size",
"source",
"symbol",
"taker_allocated_margin_usdc_after",
"taker_allocated_margin_usdc_before",
"taker_entry_quote_before",
"taker_fee",
"taker_initial_margin_fraction_before",
"taker_position_sign_changed",
"taker_position_size_before",
"timestamp",
"trade_id",
"transaction_time_us",
"tx_hash",
"usd_amount"
],
"properties": {
"ask_account": {
"description": "Lighter account index on the ask side (serialized as a string)",
"type": "string",
"example": "728637"
},
"ask_order_id": {
"description": "Order ID on the ask side",
"type": "integer",
"format": "int64",
"example": 562952982931319
},
"bid_account": {
"description": "Lighter account index on the bid side (serialized as a string)",
"type": "string",
"example": "726722"
},
"bid_order_id": {
"description": "Order ID on the bid side",
"type": "integer",
"format": "int64",
"example": 844421854021817
},
"block_height": {
"description": "Lighter L2 block height containing the liquidation",
"type": "integer",
"format": "int64",
"example": 300340672
},
"is_maker_ask": {
"description": "True if the maker was on the ask side",
"type": "boolean",
"example": false
},
"liquidation_type": {
"description": "Upstream liquidation type",
"type": "string",
"example": "liquidation"
},
"maker_allocated_margin_usdc_after": {
"description": "Maker's isolated-margin USDC allocation after the fill (raw upstream units)",
"type": "integer",
"format": "int64",
"example": 0
},
"maker_allocated_margin_usdc_before": {
"description": "Maker's isolated-margin USDC allocation before the fill (raw upstream units)",
"type": "integer",
"format": "int64",
"example": 0
},
"maker_entry_quote_before": {
"description": "Maker's position entry quote value before the fill",
"type": "number",
"example": 120665.315247
},
"maker_fee": {
"description": "Maker fee (raw upstream units)",
"type": "integer",
"example": 28
},
"maker_initial_margin_fraction_before": {
"description": "Maker's initial margin fraction before the fill (raw upstream units)",
"type": "integer",
"example": 500
},
"maker_position_sign_changed": {
"description": "True if the fill flipped the maker's position between long and short",
"type": "boolean",
"example": false
},
"maker_position_size_before": {
"description": "Maker's signed position size before the fill",
"type": "number",
"example": -1.85452
},
"price": {
"description": "Execution price",
"type": "number",
"example": 64921.9
},
"raw_json": {
"description": "Raw upstream payload as received from Lighter. Empty for rows backfilled from the venue's finalized export (`source: \"bucket\"`, Lighter on Robinhood Chain).",
"type": "string"
},
"size": {
"description": "Liquidated size in base units",
"type": "number",
"example": 0.18476
},
"source": {
"description": "Row provenance: `ws` for live capture; `bucket` for rows backfilled from the venue's finalized export (Lighter on Robinhood Chain), which carry an empty `raw_json`.",
"type": "string",
"example": "ws"
},
"symbol": {
"description": "Trading pair symbol",
"type": "string",
"example": "BTC"
},
"taker_allocated_margin_usdc_after": {
"description": "Taker's isolated-margin USDC allocation after the fill (raw upstream units)",
"type": "integer",
"format": "int64",
"example": 23859483
},
"taker_allocated_margin_usdc_before": {
"description": "Taker's isolated-margin USDC allocation before the fill (raw upstream units)",
"type": "integer",
"format": "int64",
"example": 259232053
},
"taker_entry_quote_before": {
"description": "Taker's position entry quote value before the fill",
"type": "number",
"example": 12945.451185
},
"taker_fee": {
"description": "Taker fee (raw upstream units)",
"type": "integer",
"example": 10000
},
"taker_initial_margin_fraction_before": {
"description": "Taker's initial margin fraction before the fill (raw upstream units)",
"type": "integer",
"example": 200
},
"taker_position_sign_changed": {
"description": "True if the fill flipped the taker's position between long and short",
"type": "boolean",
"example": false
},
"taker_position_size_before": {
"description": "Taker's signed position size before the fill (long positive, short negative)",
"type": "number",
"example": 0.19771
},
"timestamp": {
"description": "Liquidation time. By default an integer, Unix milliseconds. With `0xArchive-Version: 2026-10-01` an RFC 3339 UTC string with millisecond precision, and the integer moves to `timestamp_ms`.",
"oneOf": [
{
"description": "Default: Unix milliseconds.",
"type": "integer",
"format": "int64",
"example": 1785116108743
},
{
"description": "Version 2026-10-01: RFC 3339 UTC.",
"type": "string",
"format": "date-time",
"example": "2026-01-01T00:00:00.000Z"
}
]
},
"timestamp_ms": {
"description": "With `0xArchive-Version: 2026-10-01` only: `timestamp` as Unix milliseconds.",
"type": "integer",
"format": "int64",
"example": 1767225600000
},
"trade_id": {
"description": "Unique Lighter trade ID of the liquidation fill",
"type": "integer",
"format": "int64",
"example": 26144238102
},
"transaction_time_us": {
"description": "Intra-block transaction time in microseconds",
"type": "integer",
"format": "int64",
"example": 1785116108751813
},
"tx_hash": {
"description": "Lighter settlement transaction hash (fixed-width hex)",
"type": "string",
"example": "000000198190c10e0000019fa13627c7000000000000000000000000000000000000000000000000"
},
"usd_amount": {
"description": "Notional value of the liquidation in USD",
"type": "number",
"example": 11994.970244
}
}
}
},
"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
}
}
}