WebSocket userFills: Real-Time Personal Fill Stream

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 channel instead. Pass the account’s wallet address (not the numeric account ID) as the user parameter.

Subscribing

{
  "method": "subscribe",
  "subscription": {"type": "userFills", "user": "0xabc...123"}
}

Push message format

{
  "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

number

Contract ID on which the fill occurred.

string

Taker (aggressor) order ID — the order that crossed the book and matched against the resting order.

string

Maker (resting) order ID — the order that was already in the book and was hit by the aggressor.

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

string

Fill execution price (raw string). Apply the contract’s decimal precision before displaying to users.

string

Fill size (raw string) — the quantity that changed hands at price p.

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.

Determining your role

You were the taker
You were the maker

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.

aid == your_order_id  →  you are the taker

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.

rid == your_order_id  →  you are the maker

Envelope fields

string

Always "TradeFill" for fills on this channel.

string

"fills.<user_address>" — the address you subscribed with.

number

Server send timestamp in Unix milliseconds. Use this as the authoritative event time for all fills in the data array.

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

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.

Overview

Market Channels

Account Channels

WebSocket userFills: Real-Time Personal Fill Stream

Subscribing

Push message format

Fill object fields

Determining your role

Envelope fields

​Subscribing

​Push message format

​Fill object fields

​Determining your role

​Envelope fields

Subscribing

Push message format

Fill object fields

Determining your role

Envelope fields