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

# userFills | Hyperliquid WebSocket API

> Hyperliquid userFills: stream real-time trade fills for one or more wallets as they execute on HyperCore.

> [card] Credit Cost
>
> 1 per minute

> [card] Processing
>
> Realtime

> [!TIP]
>
> Estimate your monthly cost for this API using the [Pricing Calculator](https://goldrush.dev/docs/pricing-calculator.md?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fuser-fills).

> [!NOTE]
>
> * Wire-compatible with `wss://api.hyperliquid.xyz/ws` `userFills` subscription - same channel name, same per-fill shape.
> * Up to 1,000 wallet addresses per subscription. Use `addresses` (string\[]); aliases `user`(string) and `users` (string\[]) are also accepted.
> * Messages are batched per HyperCore block as `[address, fill]` tuples; subscribe many wallets, receive one push per block per wallet that had activity.
> * Live-only - no historical snapshot on subscribe. For windowed history, use the Info API `userFillsByTime`.
> * No 1,000-subscription-per-IP cap. Multiplex many `userFills` subscriptions on a single connection.

Subscribe to one or more wallets and receive their live trade fills the moment they execute. The server batches one push per HyperCore block, carrying every matching fill as `[address, fill]` tuples.

**Supports up to 1,000 wallet addresses per subscription.**

## Endpoint

```
wss://hypercore.goldrushdata.com/ws?key=<GOLDRUSH_API_KEY>
```

**key** `string` *required*

Your GoldRush API key. Passed as a query parameter at connection time - no `Authorization` header is used.

## Subscribe

Send this JSON message after the connection is established:

**method** `string` *required*

Always `"subscribe"`.

**subscription** `object` *required*

**properties**

**type** `string` *required*

Always `"userFills"`.

**addresses** `string[]` *required*

One or more wallet addresses (lowercase `0x`-prefixed hex) to stream fills for. Aliases `user` (string) and `users` (string\[]) are also accepted.

**aggregateByTime** `boolean`

When `true`, partial fills of the same order within the same block are merged into one. Default `false`.

### Example

```bash wscat theme={null}
wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

> {"method":"subscribe","subscription":{"type":"userFills","addresses":["0x31ca8395cf837de08b24da3f660e77761dfb974b"]}}
```

```typescript TypeScript theme={null}
import WebSocket from "ws";

const ws = new WebSocket(
  `wss://hypercore.goldrushdata.com/ws?key=${process.env.GOLDRUSH_API_KEY}`,
);

ws.on("open", () => {
  ws.send(JSON.stringify({
    method: "subscribe",
    subscription: {
      type: "userFills",
      addresses: ["0x31ca8395cf837de08b24da3f660e77761dfb974b"],
    },
  }));
});

ws.on("message", (raw) => {
  const msg = JSON.parse(raw.toString());
  if (msg.channel === "userFills") {
    for (const [address, fill] of msg.fills) {
      console.log(address, fill.coin, fill.side, fill.sz, "@", fill.px);
    }
  }
});
```

```python Python theme={null}
import asyncio, json, os
import websockets

async def main():
    uri = f"wss://hypercore.goldrushdata.com/ws?key={os.environ['GOLDRUSH_API_KEY']}"
    async with websockets.connect(uri) as ws:
        await ws.send(json.dumps({
            "method": "subscribe",
            "subscription": {
                "type": "userFills",
                "addresses": ["0x31ca8395cf837de08b24da3f660e77761dfb974b"],
            },
        }))
        async for raw in ws:
            msg = json.loads(raw)
            if msg.get("channel") == "userFills":
                for address, fill in msg["fills"]:
                    print(address, fill["coin"], fill["side"], fill["sz"], "@", fill["px"])

asyncio.run(main())
```

## Unsubscribe

Send the same `subscription` body with `method: "unsubscribe"`:

```json theme={null}
{
  "method": "unsubscribe",
  "subscription": {
    "type": "userFills",
    "addresses": ["0x31ca8395cf837de08b24da3f660e77761dfb974b"]
  }
}
```

> [!NOTE]
>
> Unsubscribe matches subscriptions by **exact body**. A subscription created with `addresses: ["0xAAA", "0xBBB"]` is a different subscription from two single-address subscriptions. To narrow the set, unsubscribe the original list in full, then resubscribe with the smaller list.

## Streamed message

Each push has `channel: "userFills"` and a `fills` array of `[address, fill]` tuples - all fills from the same HyperCore block that match any subscribed wallet.

```json theme={null}
{
  "channel": "userFills",
  "fills": [
    [
      "0x31ca8395cf837de08b24da3f660e77761dfb974b",
      {
        "coin": "ETH",
        "px": "2150.5",
        "sz": "1.5",
        "side": "B",
        "time": 1704067200000,
        "startPosition": "1.5",
        "dir": "Open Long",
        "closedPnl": "125.5",
        "hash": "0xabc...def",
        "oid": 12345678,
        "crossed": false,
        "fee": "2.5",
        "tid": 87654321,
        "feeToken": "USDC",
        "twapId": null
      }
    ]
  ]
}
```

**channel** `string`

Always `"userFills"`.

**fills** `array\<[string, object]\>`

Tuples of `[address, fill]`. The `address` is the subscribed wallet the fill belongs to; the `fill` object carries the trade details.

**fill properties**

**coin** `string`

Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`).

**px** `string`

Fill execution price (decimal string).

**sz** `string`

Fill size (decimal string).

**side** `string`

`"B"` for buy/long, `"A"` for ask/short.

**time** `int`

Unix timestamp in milliseconds when the fill executed.

**startPosition** `string`

Signed position size on the same coin immediately before this fill.

**dir** `string`

Human-readable direction label - `"Open Long"`, `"Open Short"`, `"Close Long"`, `"Close Short"`, `"Buy"`, `"Sell"`, or position-flip labels `"Long > Short"` / `"Short > Long"`.

**closedPnl** `string`

Realized PnL in USDC attributable to this fill (zero when the fill opens or extends a position).

**hash** `string`

L1 transaction hash that included this fill.

**oid** `int`

Parent order ID.

**crossed** `boolean`

`true` when the fill came from the taker side of the order, `false` when it was the maker side.

**fee** `string`

Trading fee paid for this fill, denominated in `feeToken`.

**tid** `int`

Unique trade ID.

**feeToken** `string`

Symbol the fee was paid in - typically `"USDC"`.

**twapId** `int | null`

Parent TWAP order ID if this fill is a slice of a TWAP, otherwise `null`.

**cloid** `string`

Optional. Client order ID (`0x`-prefixed 32-character hex) if one was set at order placement.

**builderFee** `string`

Optional. Builder fee paid for this fill, denominated in `feeToken`. Present only on fills routed through a builder code.

**builder** `string`

Optional. Builder address the order was routed through.

**liquidation** `object`

Optional. Present only when this fill closed a position as part of a liquidation event.

**properties**

**liquidatedUser** `string`

The wallet whose position was liquidated.

**markPx** `string`

Mark price at the time of liquidation.

**method** `string`

Liquidation method - `"market"` or `"backstop"`.

## Related endpoints

> [card] [userNonFundingLedgerUpdates](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/user-non-funding-ledger-updates.md)
>
> stream real-time non-funding ledger events (deposits, withdrawals, vault and staking activity) for one or more…

> [card] [allFills](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/all-fills.md)
>
> stream every fill on HyperCore in real time for global market analytics and cross-wallet order-flow monitoring.

> [card] [builderFills](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/builder-fills.md)
>
> stream live attributed fills for one or more builder addresses in real time.

> [card] [liquidationFills](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/liquidation-fills.md)
>
> stream a global, market-wide feed of every liquidation fill on HyperCore.

> [card] [builderLiquidations](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/builder-liquidations.md)
>
> subscribe to real-time liquidation fills of your users.

> [card] [orderUpdates](https://goldrush.dev/docs/api-reference/hyperliquid-websocket/order-updates.md)
>
> stream real-time order lifecycle events (placements, fills, cancels, and rejections) for one or more wallets on HyperCore.

See all Hyperliquid endpoints: [Overview hub](https://goldrush.dev/docs/goldrush-hyperliquid/overview.md) · [WebSocket API reference](https://goldrush.dev/docs/goldrush-hyperliquid/websocket-api/overview.md)

*Last reviewed: 2026-06-16*


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.