> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsidemax.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# User Fills

> Query your historical fills with per-fill fee, realized PnL, and position context. Paginated by time window and filterable by contract.

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/user-fills) WebSocket channel. For orders still working in the book, use [`userOrders`](/info/user-orders).

<Note>
  `userFills`, [`orderHistory`](/info/order-history), and [`userFundingFlows`](/info/user-funding-flows) 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.
</Note>

## Request

```json theme={null}
{"type": "userFills", "accountId": "5", "contractId": 1}
```

<ParamField body="type" type="string" required>
  Must be `"userFills"`.
</ParamField>

<ParamField body="accountId" type="string" required>
  Your account ID. Must be greater than zero. A numeric value is also accepted.
</ParamField>

<ParamField body="contractId" type="int">
  Restrict results to one contract. Use `0` or omit for all contracts.
</ParamField>

<ParamField body="startTime" type="int64">
  Inclusive start of the time window, in Unix milliseconds. `0` or omitted means unbounded.
</ParamField>

<ParamField body="endTime" type="int64">
  Inclusive end of the time window, in Unix milliseconds. `0` or omitted means unbounded. A `startTime` later than `endTime` returns `400 BAD_REQUEST`.
</ParamField>

<ParamField body="limit" type="int">
  Maximum rows in this page. Defaults to **1000**, which is also the maximum; a larger value returns `400 BAD_REQUEST`.
</ParamField>

## Response

```json theme={null}
{
  "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"
    }
  ],
  "count": 1,
  "truncated": false
}
```

### Envelope fields

<ResponseField name="contractIdFilter" type="int">
  Echoes the `contractId` filter that was applied. `0` means no filter.
</ResponseField>

<ResponseField name="count" type="int">
  Number of rows in this page. When `count` equals your `limit`, another page may be available.
</ResponseField>

<ResponseField name="truncated" type="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.
</ResponseField>

### Fill object fields

<ResponseField name="timeMs" type="number">
  Fill time in Unix milliseconds.
</ResponseField>

<ResponseField name="height" type="number">
  Block height at which the fill was recorded.
</ResponseField>

<ResponseField name="seq" type="number">
  Sequence number within the block.
</ResponseField>

<ResponseField name="sideRole" type="string">
  Your role in this fill: `"Taker"` or `"Maker"`.
</ResponseField>

<ResponseField name="execId" type="string">
  Unique execution ID for this row. Use it to deduplicate rows when pages overlap.
</ResponseField>

<ResponseField name="contractId" type="number">
  Contract on which the fill occurred.
</ResponseField>

<ResponseField name="marketDeployerId" type="number">
  Market deployer the contract belongs to.
</ResponseField>

<ResponseField name="orderId" type="string">
  Your own order ID for this row.
</ResponseField>

<ResponseField name="orderSide" type="string">
  `"B"` for buy, `"S"` for sell.
</ResponseField>

<ResponseField name="price" type="string">
  Execution price (raw integer string).
</ResponseField>

<ResponseField name="qty" type="string">
  Filled quantity (raw integer string).
</ResponseField>

<ResponseField name="notional" type="string">
  Notional value of the fill (raw integer string).
</ResponseField>

<ResponseField name="fee" type="string">
  Your fee for this fill, signed — a negative value is a rebate.
</ResponseField>

<ResponseField name="realizedPnl" type="string">
  Your realized PnL on this fill, signed.
</ResponseField>

<ResponseField name="liquidateType" type="string">
  Liquidation classification. `"None"` for an ordinary fill; see the enum table below.
</ResponseField>

<ResponseField name="positionBefore" type="string">
  Your position size immediately before this fill, signed.
</ResponseField>

<ResponseField name="positionSide" type="string">
  `"OneWay"`, `"L"` (long), or `"S"` (short).
</ResponseField>

<ResponseField name="orderType" type="string">
  Type of **your own** order on this row. See the enum table below.
</ResponseField>

<ResponseField name="orderPrice" type="string">
  The limit price of your order — **not** the execution price in `price`. Returns `"0"` for a market order.
</ResponseField>

<Note>
  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`.
</Note>

## 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:

<Steps>
  <Step title="Request the first page">
    Send the query with your filters and an optional `startTime`.
  </Step>

  <Step title="Take the last row's timestamp">
    Read `timeMs` from the final row of the page and pass it as `startTime` on the next request.
  </Step>

  <Step title="Deduplicate the boundary">
    `startTime` is inclusive, so the row you paged from repeats. Discard duplicates by `execId`.
  </Step>

  <Step title="Stop when the page is short">
    A page where `count` is less than `limit` is the last one. While `count` equals `limit`, keep going.
  </Step>
</Steps>

## 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"`.
* Prices and quantities are raw integers — convert them with the contract's `priceScale` and `qtyScale` from [`configs`](/info/configs).

### 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`                                                                                                                    |