For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Name
Type
Required
Default
Description

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_timestamp must be less than end_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_timestamp and last_timestamp describe 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:

Field
Description

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 as cursor with the same filters to get the next page. When next_cursor is missing, you've reached the end.

  • limit counts orders. If one order has fills of different role or type (e.g. part maker, part taker), it comes back as one entry per role/type, so trades can contain more entries than limit.

  • Orders still receiving fills can move between requests. A fixed end_timestamp bounds 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

Code
Message
Cause

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.

get
Query parameters
account_indexinteger · int64Required

Account to query.

market_idinteger · int64Optional

Filter by market.

Default: 255
order_index_strstringOptional

Return only this order (order index as a string). Must parse as a positive signed 64-bit integer.

cursorstringOptional

next_cursor from the previous response.

ask_filterinteger · int8 · min: -1 · max: 1Optional

-1 both sides, 0 buys only, 1 sells only.

Default: -1
rolestring · enumOptional

maker or taker.

Possible values:
typestring · enumOptional

trade, liquidation, deleverage, market_settlement. Note the underscore here; the response uses market-settlement.

Possible values:
start_timestampinteger · int64 · min: 1737072000000Optional

Inclusive lower bound on the stored order aggregate's last fill time.

end_timestampinteger · int64 · min: 1737072000000Optional

Exclusive upper bound on the stored order aggregate's last fill time.

limitinteger · int64 · min: 1 · max: 1000Optional

Number of orders per page, 1–1000.

Default: 100
Responses
200

Successful response.

application/json
codeinteger · int32RequiredExample: 200
messagestringOptional
next_cursorstringOptional

Opaque cursor for the next page; absent at the end. Keep all filters unchanged and URL-encode it.

get/api/v1/aggregatedTrades
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?