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

<CardGroup cols={2}>
  <Card title="Credit Cost"> 1 per minute</Card>
  <Card title="Processing"> Realtime</Card>
</CardGroup>

<Tip>
  Estimate your monthly cost for this API using the [Pricing Calculator](/pricing-calculator?endpoint=%2Fapi-reference%2Fhyperliquid-websocket%2Fuser-fills).
</Tip>

<Info>
  * 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.
</Info>

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

<ParamField query="key" type="string" required>
  Your GoldRush API key. Passed as a query parameter at connection time - no `Authorization` header is used.
</ParamField>

## Subscribe

Send this JSON message after the connection is established:

<ParamField body="method" type="string" required>
  Always `"subscribe"`.
</ParamField>

<ParamField body="subscription" type="object" required>
  <Expandable title="properties">
    <ResponseField name="type" type="string" required>Always `"userFills"`.</ResponseField>

    <ResponseField name="addresses" type="string[]" required>
      One or more wallet addresses (lowercase `0x`-prefixed hex) to stream fills for. Aliases `user` (string) and `users` (string\[]) are also accepted.
    </ResponseField>

    <ResponseField name="aggregateByTime" type="boolean">
      When `true`, partial fills of the same order within the same block are merged into one. Default `false`.
    </ResponseField>
  </Expandable>
</ParamField>

### Example

<CodeGroup>
  ```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())
  ```
</CodeGroup>

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

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

<ResponseField name="channel" type="string">Always `"userFills"`.</ResponseField>

<ResponseField name="fills" type="array<[string, object]>">
  Tuples of `[address, fill]`. The `address` is the subscribed wallet the fill belongs to; the `fill` object carries the trade details.

  <Expandable title="fill properties">
    <ResponseField name="coin" type="string">Asset symbol - e.g. `"BTC"`, `"ETH"` for perps; spot pairs use the `@N` form (e.g. `"@107"`).</ResponseField>
    <ResponseField name="px" type="string">Fill execution price (decimal string).</ResponseField>
    <ResponseField name="sz" type="string">Fill size (decimal string).</ResponseField>
    <ResponseField name="side" type="string">`"B"` for buy/long, `"A"` for ask/short.</ResponseField>
    <ResponseField name="time" type="int">Unix timestamp in milliseconds when the fill executed.</ResponseField>
    <ResponseField name="startPosition" type="string">Signed position size on the same coin immediately before this fill.</ResponseField>
    <ResponseField name="dir" type="string">Human-readable direction label - `"Open Long"`, `"Open Short"`, `"Close Long"`, `"Close Short"`, `"Buy"`, `"Sell"`, or position-flip labels `"Long > Short"` / `"Short > Long"`.</ResponseField>
    <ResponseField name="closedPnl" type="string">Realized PnL in USDC attributable to this fill (zero when the fill opens or extends a position).</ResponseField>
    <ResponseField name="hash" type="string">L1 transaction hash that included this fill.</ResponseField>
    <ResponseField name="oid" type="int">Parent order ID.</ResponseField>
    <ResponseField name="crossed" type="boolean">`true` when the fill came from the taker side of the order, `false` when it was the maker side.</ResponseField>
    <ResponseField name="fee" type="string">Trading fee paid for this fill, denominated in `feeToken`.</ResponseField>
    <ResponseField name="tid" type="int">Unique trade ID.</ResponseField>
    <ResponseField name="feeToken" type="string">Symbol the fee was paid in - typically `"USDC"`.</ResponseField>
    <ResponseField name="twapId" type="int | null">Parent TWAP order ID if this fill is a slice of a TWAP, otherwise `null`.</ResponseField>
    <ResponseField name="cloid" type="string">Optional. Client order ID (`0x`-prefixed 32-character hex) if one was set at order placement.</ResponseField>
    <ResponseField name="builderFee" type="string">Optional. Builder fee paid for this fill, denominated in `feeToken`. Present only on fills routed through a builder code.</ResponseField>
    <ResponseField name="builder" type="string">Optional. Builder address the order was routed through.</ResponseField>

    <ResponseField name="liquidation" type="object">
      Optional. Present only when this fill closed a position as part of a liquidation event.

      <Expandable title="properties">
        <ResponseField name="liquidatedUser" type="string">The wallet whose position was liquidated.</ResponseField>
        <ResponseField name="markPx" type="string">Mark price at the time of liquidation.</ResponseField>
        <ResponseField name="method" type="string">Liquidation method - `"market"` or `"backstop"`.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

## Related endpoints

<CardGroup cols={2}>
  <Card title="allFills" href="/api-reference/hyperliquid-websocket/all-fills">stream every fill on HyperCore in real time for global market analytics and cross-wallet order-flow…</Card>
  <Card title="builderFills" href="/api-reference/hyperliquid-websocket/builder-fills">stream live attributed fills for one or more builder addresses in real time.</Card>
  <Card title="liquidationFills" href="/api-reference/hyperliquid-websocket/liquidation-fills">stream a global, market-wide feed of every liquidation fill on HyperCore.</Card>
  <Card title="userNonFundingLedgerUpdates" href="/api-reference/hyperliquid-websocket/user-non-funding-ledger-updates">stream real-time non-funding ledger events (deposits, withdrawals, vault and staking activity) for one or…</Card>
</CardGroup>

*Last reviewed: 2026-06-16*