{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "ApiResponseLighterTradeArray",
"description": "API response containing an array of Lighter trades. History responses serve canonical rows only and clamp `end` to `finalized_through`; `/recent` responses serve preliminary rows and report `preliminary_row_count`.",
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"description": "Lighter trade (fill) record. Canonical rows (`source: \"bucket\"`) come from the daily reconcile of the deployment's published trade history (the Lighter Foundation export for Lighter mainnet, the venue trade export for Lighter on Robinhood Chain) and carry full enrichment. The `/recent` endpoint serves preliminary real-time rows (`source: \"ws\"`) without fee/tx_hash/order_id/realized_pnl and the other bucket-only enrichment fields until the daily reconcile finalizes them.",
"type": "object",
"required": [
"coin",
"crossed",
"price",
"side",
"size",
"source",
"symbol",
"timestamp",
"trade_id"
],
"properties": {
"account_index": {
"description": "Lighter numeric account index this row belongs to (serialized as a string)",
"type": "string",
"example": "513030"
},
"allocated_margin_after": {
"description": "Isolated-margin allocation after the fill (0 for cross)",
"type": "number",
"nullable": true,
"example": 0
},
"allocated_margin_before": {
"description": "Isolated-margin allocation before the fill (0 for cross)",
"type": "number",
"nullable": true,
"example": 0
},
"client_id": {
"description": "Client-assigned order ID. Canonical rows only.",
"type": "integer",
"format": "int64",
"nullable": true,
"example": 46758119273906
},
"coin": {
"description": "Trading pair symbol (deprecated, use symbol instead)",
"type": "string",
"deprecated": true,
"example": "BTC"
},
"counterparty_address": {
"description": "Counterparty's Lighter account index (serialized as a string). Canonical rows only.",
"type": "string",
"nullable": true,
"example": "710765"
},
"crossed": {
"description": "True if this account was the taker (crossed the spread), false if maker",
"type": "boolean",
"example": false
},
"entry_quote_before": {
"description": "This account's position entry quote value before the fill",
"type": "number",
"nullable": true,
"example": 61179.114686
},
"fee": {
"description": "This account's fee for the fill. Canonical rows only.",
"type": "string",
"nullable": true,
"example": "0.000028"
},
"fee_account_id": {
"description": "Account credited with the fee. Canonical rows only.",
"type": "integer",
"format": "int64",
"nullable": true,
"example": 0
},
"initial_margin_fraction_before": {
"description": "This account's initial margin fraction before the fill",
"type": "number",
"nullable": true,
"example": 0.02
},
"integrator_fee": {
"description": "Integrator fee charged on the fill. Canonical rows only.",
"type": "number",
"nullable": true,
"example": 0
},
"is_maker": {
"description": "True if this account was the maker. Canonical rows only.",
"type": "boolean",
"nullable": true,
"example": true
},
"l2_block_height": {
"description": "Lighter L2 block height containing the trade. Canonical rows only.",
"type": "integer",
"format": "int64",
"nullable": true,
"example": 300075269
},
"order_id": {
"description": "Order ID of this account's order. Canonical rows only.",
"type": "integer",
"format": "int64",
"nullable": true,
"example": 844421856609148
},
"position_sign_changed": {
"description": "True if the fill flipped this account's position between long and short",
"type": "boolean",
"nullable": true,
"example": false
},
"position_size_after": {
"description": "Signed position size after the fill (derived: position_size_before plus/minus size by side)",
"type": "number",
"nullable": true,
"example": -0.94627
},
"position_size_before": {
"description": "This account's signed position size before the fill (long positive, short negative)",
"type": "number",
"nullable": true,
"example": -0.94632
},
"price": {
"description": "Execution price",
"type": "string",
"example": "64708.5"
},
"realized_pnl": {
"description": "Matching-engine realized PnL for this fill. Canonical rows only.",
"type": "number",
"nullable": true,
"example": -0.00295
},
"side": {
"description": "Trade side of the account this row belongs to: 'B' (buy) or 'A' (sell/ask)",
"type": "string",
"enum": [
"A",
"B"
],
"example": "B"
},
"size": {
"description": "Trade size in base units",
"type": "string",
"example": "0.00005"
},
"source": {
"description": "Row provenance: 'bucket' = canonical (finalized by the daily reconcile of the deployment's published trade history), 'ws' = preliminary real-time capture",
"type": "string",
"enum": [
"bucket",
"ws"
],
"example": "bucket"
},
"symbol": {
"description": "Trading pair symbol",
"type": "string",
"example": "BTC"
},
"timestamp": {
"description": "Execution timestamp (UTC)",
"type": "string",
"format": "date-time",
"example": "2026-07-26T14:47:59.174Z"
},
"trade_id": {
"description": "Unique Lighter trade ID. Each trade produces two rows (one per counterparty) sharing this ID.",
"type": "integer",
"format": "int64",
"example": 26121110211
},
"trade_type": {
"description": "Upstream trade type. Canonical rows only.",
"type": "string",
"nullable": true,
"example": "trade"
},
"transaction_time_us": {
"description": "Intra-block transaction time in microseconds. Canonical rows only.",
"type": "integer",
"format": "int64",
"nullable": true,
"example": 1785077279174437
},
"tx_hash": {
"description": "Lighter settlement transaction hash (fixed-width hex). Canonical rows only.",
"type": "string",
"nullable": true,
"example": "000000197b6fd6e90000019f9ee5a9c6000000000000000000000000000000000000000000000000"
},
"usdc_amount": {
"description": "Notional value of the fill in USDC. Canonical rows only.",
"type": "number",
"nullable": true,
"example": 3.235425
}
}
}
},
"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
}
}
}