{
"$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 Lighter Foundation reconcile 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 Lighter Foundation reconcile), '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": {
"type": "object",
"properties": {
"clamped_to": {
"description": "Effective end after clamping to `finalized_through`. History endpoint only.",
"type": "string",
"format": "date-time",
"nullable": true
},
"count": {
"description": "Number of records returned",
"type": "integer"
},
"finalized_through": {
"description": "Timestamp through which canonical (bucket-reconciled) data is available.",
"type": "string",
"format": "date-time"
},
"next_cursor": {
"description": "Cursor for pagination. Use this value as the `cursor` parameter to fetch the next page. History endpoint only.",
"type": "string",
"nullable": true
},
"preliminary_row_count": {
"description": "Number of preliminary (`source: \"ws\"`) rows in this response. `/recent` endpoint only.",
"type": "integer",
"nullable": true
},
"request_id": {
"description": "Unique request ID for support",
"type": "string",
"format": "uuid"
},
"requested_end": {
"description": "The `end` the caller requested, echoed when it was clamped. History endpoint only.",
"type": "string",
"format": "date-time",
"nullable": true
}
}
},
"success": {
"type": "boolean",
"example": true
}
}
}
