userFills query returns your account’s historical fill detail. A single match produces two rows on chain — one for the taker and one for the maker — and each side sees only its own row, carrying that side’s fee, realized PnL, and position context. Counterparty identity is never disclosed.
For fills as they happen, subscribe to the userFills WebSocket channel. For orders still working in the book, use userOrders.
userFills, orderHistory, and userFundingFlows are the three history queries. They share one endpoint, one set of request parameters, and one pagination contract, documented below; their field names match the WebSocket push payloads exactly.Request
string
required
Must be
"userFills".string
required
Your account ID. Must be greater than zero. A numeric value is also accepted.
int
Restrict results to one contract. Use
0 or omit for all contracts.int64
Inclusive start of the time window, in Unix milliseconds.
0 or omitted means unbounded.int64
Inclusive end of the time window, in Unix milliseconds.
0 or omitted means unbounded. A startTime later than endTime returns 400 BAD_REQUEST.int
Maximum rows in this page. Defaults to 1000, which is also the maximum; a larger value returns
400 BAD_REQUEST.Response
Envelope fields
int
Echoes the
contractId filter that was applied. 0 means no filter.int
Number of rows in this page. When
count equals your limit, another page may be available.boolean
true when the page was cut short at a row boundary because the response reached its byte ceiling. Continue paginating from the last row.Fill object fields
number
Fill time in Unix milliseconds.
number
Block height at which the fill was recorded.
number
Sequence number within the block.
string
Your role in this fill:
"Taker" or "Maker".string
Unique execution ID for this row. Use it to deduplicate rows when pages overlap.
number
Contract on which the fill occurred.
number
Market deployer the contract belongs to.
string
Your own order ID for this row.
string
"B" for buy, "S" for sell.string
Execution price (raw integer string).
string
Filled quantity (raw integer string).
string
Notional value of the fill (raw integer string).
string
Your fee for this fill, signed — a negative value is a rebate.
string
Your realized PnL on this fill, signed.
string
Liquidation classification.
"None" for an ordinary fill; see the enum table below.string
Your position size immediately before this fill, signed.
string
"OneWay", "L" (long), or "S" (short).string
Type of your own order on this row. See the enum table below.
string
The limit price of your order — not the execution price in
price. Returns "0" for a market order.There is no order-level fee total in this response. To get the total fee for an order, sum the per-fill
fee values sharing the same orderId.Pagination
Results are returned in ascending time order (oldest first), at mostlimit rows per page. There is no cursor token — page forward through the time window:
1
Request the first page
Send the query with your filters and an optional
startTime.2
Take the last row's timestamp
Read
timeMs from the final row of the page and pass it as startTime on the next request.3
Deduplicate the boundary
startTime is inclusive, so the row you paged from repeats. Discard duplicates by execId.4
Stop when the page is short
A page where
count is less than limit is the last one. While count equals limit, keep going.Value conventions
- 64-bit integers — IDs, prices, quantities, and amounts — are returned as JSON strings to preserve precision.
height,timeMs, and small integers such ascontractIdandseqare returned as bare numbers.- Enumerations are returned as strings. Any value the server does not recognize is returned as
"Unknown". - Prices and quantities are raw integers — convert them with the contract’s
priceScaleandqtyScalefromconfigs.