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

# WebSocket userFills: Real-Time Personal Fill Stream

> Subscribe to userFills to receive every fill involving your orders in real time — whether you were the taker aggressor or the resting maker.

The `userFills` channel delivers every fill where your account is one of the counterparties — both fills where you were the **taker** (your order crossed the book and aggressed) and fills where you were the **maker** (your resting order was hit). To determine your role in each fill, compare the aggressor order ID (`aid`) and the resting order ID (`rid`) against your own order IDs. For the full public trade stream regardless of account, use the [`trades`](/websocket/trades) channel instead.

Pass the account's wallet address (not the numeric account ID) as the `user` parameter.

## Subscribing

```json theme={"system"}
{
  "method": "subscribe",
  "subscription": {"type": "userFills", "user": "0xabc...123"}
}
```

## Push message format

```json theme={"system"}
{
  "msg": "TradeFill",
  "channel": "fills.0xabc...123",
  "data": [
    {
      "c": 1,
      "aid": "15",
      "rid": "12",
      "b": "B",
      "p": "1133770",
      "s": "5",
      "e": "8842931"
    }
  ],
  "ts": 1782279307885
}
```

The `data` array may contain multiple fill objects when several fills execute in the same block. Process them in array order.

## Fill object fields

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

<ResponseField name="aid" type="string">
  Taker (aggressor) order ID — the order that crossed the book and matched against the resting order.
</ResponseField>

<ResponseField name="rid" type="string">
  Maker (resting) order ID — the order that was already in the book and was hit by the aggressor.
</ResponseField>

<ResponseField name="b" type="string">
  Direction of the aggressor: `"B"` means the buyer was the aggressor (bought into resting asks); `"S"` means the seller was the aggressor (sold into resting bids).
</ResponseField>

<ResponseField name="p" type="string">
  Fill execution price (raw string). Apply the contract's decimal precision before displaying to users.
</ResponseField>

<ResponseField name="s" type="string">
  Fill size (raw string) — the quantity that changed hands at price `p`.
</ResponseField>

<ResponseField name="e" type="string">
  Execution ID — globally unique on-chain identifier for this fill. Use this to deduplicate fills if you receive the same event from multiple sources.
</ResponseField>

## Determining your role

<Tabs>
  <Tab title="You were the taker">
    If `aid` matches one of your order IDs, your order was the aggressor. You paid the taker fee and your order actively crossed the spread to execute.

    ```text theme={"system"}
    aid == your_order_id  →  you are the taker
    ```
  </Tab>

  <Tab title="You were the maker">
    If `rid` matches one of your order IDs, your order was the resting maker. You received the maker rebate (if applicable) and your limit order was hit by the incoming aggressor.

    ```text theme={"system"}
    rid == your_order_id  →  you are the maker
    ```
  </Tab>
</Tabs>

## Envelope fields

<ResponseField name="msg" type="string">
  Always `"TradeFill"` for fills on this channel.
</ResponseField>

<ResponseField name="channel" type="string">
  `"fills.<user_address>"` — the address you subscribed with.
</ResponseField>

<ResponseField name="ts" type="number">
  Server send timestamp in Unix milliseconds. Use this as the authoritative event time for all fills in the `data` array.
</ResponseField>

<Note>
  `userFills` pushes from subscription time only — there is no historical backfill on subscribe. To retrieve past fills, query the REST fills history endpoint.
</Note>

<Tip>
  Combine `userFills` with `orderUpdates` to build a complete real-time trade blotter: `orderUpdates` tells you when order status changes, and `userFills` gives you the precise fill price and size for each execution.
</Tip>