{
"$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.",
"type": "string"
},
"size": {
"description": "Liquidated size in base units",
"type": "number",
"example": 0.18476
},
"source": {
"description": "Row provenance",
"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 timestamp in Unix epoch milliseconds",
"type": "integer",
"format": "int64",
"example": 1785116108743
},
"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": {
"type": "object",
"properties": {
"count": {
"description": "Number of records returned",
"type": "integer"
},
"next_cursor": {
"description": "Cursor for pagination (format: timestamp_tradeId)",
"type": "string",
"nullable": true
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
}
}
},
"success": {
"type": "boolean",
"example": true
}
}
}
