User Fills

The 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

{"type": "userFills", "accountId": "5", "contractId": 1}

string

required

type (required) — Must be "userFills".

string

required

accountId (required) — Your account ID. Must be greater than zero. A numeric value is also accepted.

int

contractId — Restrict results to one contract. Use 0 or omit for all contracts.

int64

startTime — Inclusive start of the time window, in Unix milliseconds. 0 or omitted means unbounded.

int64

endTime — Inclusive end of the time window, in Unix milliseconds. 0 or omitted means unbounded. A startTime later than endTime returns 400 BAD_REQUEST.

int

limit — Maximum rows in this page, from 1 to 1000. Defaults to 1000. A value outside the range returns HTTP 400 with code INVALID_PARAM, errors[].field "limit" and errors[].reason "OUT_OF_RANGE".

Response

{
  "type": "userFills",
  "accountId": "5",
  "contractIdFilter": 1,
  "fills": [
    {
      "timeMs": 1700000000000,
      "height": 42,
      "seq": 3,
      "sideRole": "Taker",
      "execId": "900",
      "contractId": 7,
      "marketDeployerId": 5,
      "orderId": "101",
      "orderSide": "B",
      "price": "50000",
      "qty": "3",
      "notional": "150000",
      "fee": "12",
      "realizedPnl": "56",
      "liquidateType": "None",
      "positionBefore": "90",
      "positionSide": "L",
      "orderType": "L",
      "orderPrice": "49500",
      "txIndex": null
    }
  ],
  "count": 1,
  "truncated": false
}

Envelope fields

string

Always "userFills".

string

The account ID from the request.

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 response has an upper bound on its size and the page was cut at a row boundary, so it holds fewer than limit rows while more rows remain. Continue paginating from the last row. false when the page was not cut.

object[]

The fills in this page, in ascending time order. Each element carries the fields below.

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, an amount in the settlement coin (raw integer string).

string

Your fee for this fill, an amount in the settlement coin, signed — a negative value is a rebate.

string

Your realized PnL on this fill, an amount in the settlement coin, 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.

number | null

Index of the originating transaction within its block. Together with height, (height, txIndex) identifies that transaction. null when not available.

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 most limit rows per page. There is no cursor token — page forward through the time window:

Request the first page

Send the query with your filters and an optional startTime.

Take the last row's timestamp

Read the time of the final row of the page (timeMs; updatedTimeMs for orderHistory) and pass it as startTime on the next request.

Deduplicate the boundary

startTime is inclusive, so rows at the boundary time repeat. Discard duplicates by the row’s unique ID: execId for userFills, orderId for orderHistory.

Continue while more rows may remain

When count equals limit, or truncated is true, another page may be available — request it. Otherwise the window is exhausted.

Value conventions

64-bit integers — IDs, prices, quantities, and amounts — are returned as JSON strings to preserve precision.
height, timeMs, and small integers such as contractId and seq are returned as bare numbers.
Enumerations are returned as strings. Any value the server does not recognize is returned as "Unknown".
These strings are raw integers. Convert price and orderPrice with the contract’s priceScale, qty and positionBefore with its qtyScale, and the amounts — notional, fee, realizedPnl, and the funding amount — with the settlement coin’s szDecimals, all from configs. Use exact decimal arithmetic, never floating point.

Enumerations

Field	Values
`orderSide`	`B` (buy) · `S` (sell)
`orderType`	`L` (limit) · `M` (market) · `SL` (stop limit) · `SM` (stop market) · `TPL` (take-profit limit) · `TPM` (take-profit market)
`positionSide`	`OneWay` · `L` (long) · `S` (short)
`sideRole`	`Taker` · `Maker`
`liquidateType`	`None` · `ForceLiquidate` · `ForceClose` · `AdlLiquidate` · `AdlClose` · `OffsetLiquidate`
Any unrecognized value	`Unknown`

Errors

The three history queries share one error set. Errors use the standard error body described in the Info API overview.

HTTP	`code`	Cause
400	`INVALID_PARAM`	A parameter is missing, has the wrong type, or is out of range. `errors[]` names the field; `reason` is `MISSING_PARAM`, `INVALID_TYPE`, or `OUT_OF_RANGE` (for example, `limit` above 1000).
400	`BAD_REQUEST`	The body is not valid JSON, `startTime` is later than `endTime`, or `type` is not supported.
405	`METHOD_NOT_ALLOWED`	The request method is not `POST`.
413	`BODY_TOO_LARGE`	The request body exceeds the size limit.
500	`INTERNAL_ERROR`	Internal server error.
503	`DOWNSTREAM_UNAVAILABLE`	History data is temporarily unavailable. Retry later.
504	`DOWNSTREAM_TIMEOUT`	The query did not complete in time. Narrow the time window or reduce `limit`, then retry.

Overview

Market Data

Account

Orders

History

Request

Response

Envelope fields

Fill object fields

Value conventions

Enumerations

Errors

​Request

​Response

​Envelope fields

​Fill object fields

​Pagination

​Value conventions

​Enumerations

​Errors

Request

Response

Envelope fields

Fill object fields

Pagination

Value conventions

Enumerations

Errors