aggregatedTrades
Returns an account's fills grouped by order, with separate entries for each trade type and maker/taker role. Each entry includes total filled size, notional, average price, fees, realized PnL and first/last fill details. Use trades for individual fills.
This guide covers Lighter mainnet. The endpoint does not require an authentication token.
GET https://mainnet.zklighter.elliot.ai/api/v1/aggregatedTrades
Query parameters
account_index
int64
yes
–
Account to query.
market_id
int64
no
255 (all)
Filter by market.
market_type
string
no
all
perps, spot, bo. Comma-separated for several, e.g. perps,spot.
order_index_str
string
no
–
Return only this order (order index as a string).
ask_filter
int8
no
-1
-1 both sides, 0 buys only, 1 sells only.
role
string
no
both
maker or taker.
type
string
no
all
trade, liquidation, deleverage, market_settlement. Note the underscore here; the response uses market-settlement.
start_timestamp
int64 (ms)
no
–
Inclusive lower bound on the stored order aggregate's last fill time.
end_timestamp
int64 (ms)
no
–
Exclusive upper bound on the stored order aggregate's last fill time.
limit
int64
no
100
Number of orders per page, 1–1000.
cursor
string
no
–
next_cursor from the previous response.
Timestamp rules:
Both must be on or after the exchange start (Jan 17, 2025 UTC =
1737072000000).If both are set,
start_timestampmust be less thanend_timestamp.Filtering selects stored order aggregates by their last fill time. It does not trim their individual fills to the requested window.
Results are then split by trade type and maker/taker role. Each returned entry's
first_timestampandlast_timestampdescribe that subgroup, so they need not both fall inside the requested window.Omitting either timestamp leaves that side of the window unbounded.
Response
Illustrative response:
account_index
Queried account.
order_id
Order index as a string; "0" can represent a synthetic entry without a normal order ID.
grouping_id
Stored grouping identifier returned by the indexer, or null. Treat it as opaque; use order_id to identify the order.
master_twap_id
Parent TWAP order id if the order is a TWAP child, else null.
market_id, market_symbol
Market.
market_kind
perps, spot or bo.
is_ask
true = sell, false = buy.
type
trade, liquidation, deleverage, market-settlement.
role
maker or taker.
first_trade_id, last_trade_id
First / last fill in this trade-type and role subgroup (strings).
first_timestamp, last_timestamp
First / last fill time in this subgroup, in Unix milliseconds.
first_block_height, last_block_height
First / last fill block in this subgroup.
fill_count
Number of fills aggregated in this subgroup.
size
Total filled base size.
usd_amount
Total filled notional, USDC.
average_price
Size-weighted average fill price.
pnl
Realized PnL from these fills, USDC; null if the fills didn't reduce a position.
fee
Total fee paid, in fee_asset_id units (USDC, or the base asset for spot buys).
integrator_fee
Total integrator fee, same units as fee.
fee_asset_id
Asset the fee is charged in (3 = USDC).
position_size_before, entry_quote_before
Position size and entry quote before the first fill in this subgroup; null when unavailable.
position_sign_changed
Whether the position sign before the first fill differs from the sign after the last fill in this subgroup, including opening from or closing to zero; null when position data is unavailable.
initial_margin_fraction_before
Initial margin fraction before the first fill (500 = 5%).
allocated_margin_usdc_before, allocated_margin_usdc_after
Isolated-margin allocation before the first / after the last fill (raw integer, same format as *_allocated_margin_usdc_* in trades).
Pagination
Stored order aggregates are selected by their overall last trade ID, newest first. Within each order, returned trade-type/role entries are sorted by their own last trade IDs. The flattened response is not necessarily globally sorted by each entry's
last_trade_id.If more orders exist, the response includes
next_cursor. Pass it ascursorwith the same filters to get the next page. Whennext_cursoris missing, you've reached the end.limitcounts orders. If one order has fills of differentroleortype(e.g. part maker, part taker), it comes back as one entry per role/type, sotradescan contain more entries thanlimit.Orders still receiving fills can move between requests. A fixed
end_timestampbounds the query but does not freeze the aggregates or guarantee a stable snapshot. For exports, reconcile overlapping queries using order and fill identifiers. Synthetic entries can share order_id 0, so do not deduplicate on order_id alone.
Errors
20001
invalid param
Bad or out-of-range parameter (e.g. limit > 1000, unknown type/market_type).
20001
invalid param : timestamps must be on or after exchange start (January 17, 2025 UTC)
start_timestamp / end_timestamp before 1737072000000.
20001
invalid param : start_timestamp must be less than end_timestamp
Empty or inverted window.
20001
invalid param : invalid order_index_str
Non-numeric or ≤ 0 order index.
20009
invalid cursor
Malformed cursor.
21100
account not found: <index>
Unknown account_index.
Examples
A one-hour window for one account, maximum page size:
Perps + spot taker fills on one market:
Next page of the same one-hour query (keep both timestamp filters):
For the generated endpoint reference, see aggregatedTrades.
Account to query.
Filter by market.
255Return only this order (order index as a string). Must parse as a positive signed 64-bit integer.
next_cursor from the previous response.
-1 both sides, 0 buys only, 1 sells only.
-1maker or taker.
trade, liquidation, deleverage, market_settlement. Note the underscore here; the response uses market-settlement.
Inclusive lower bound on the stored order aggregate's last fill time.
Exclusive upper bound on the stored order aggregate's last fill time.
Number of orders per page, 1–1000.
100Successful response.
200Opaque cursor for the next page; absent at the end. Keep all filters unchanged and URL-encode it.
Invalid query or cursor, or account not found; see the error table.
GET /api/v1/aggregatedTrades?account_index=1 HTTP/1.1
Host: mainnet.zklighter.elliot.ai
Accept: */*
{
"code": 200,
"next_cursor": "eyJ2ZXJzaW9uIjoxLCJ0cmFkZV9pZCI6MzgxODIxMDg1NTR9",
"trades": [
{
"account_index": 281474976710654,
"order_id": "36591746915350675",
"grouping_id": "36591746915350675",
"master_twap_id": null,
"market_id": 128,
"market_symbol": "SPY",
"market_kind": "perps",
"is_ask": false,
"type": "trade",
"role": "maker",
"first_trade_id": "38173459320",
"last_trade_id": "38182108554",
"first_timestamp": 1793807287488,
"last_timestamp": 1793808698879,
"first_block_height": 374940593,
"last_block_height": 374991730,
"fill_count": 116,
"size": "101.0104",
"usd_amount": "77395.189111",
"pnl": null,
"average_price": "766.21",
"fee": "2.438882286892",
"integrator_fee": "0.000000000000",
"fee_asset_id": 3,
"position_size_before": "2314.8726",
"entry_quote_before": "1778329.357642",
"position_sign_changed": false,
"initial_margin_fraction_before": 500,
"allocated_margin_usdc_before": 0,
"allocated_margin_usdc_after": 0
}
]
}Last updated
Was this helpful?