userFills | Hyperliquid WebSocket API - GoldRush API Documentation

Credit Cost

1 per minute

Processing

Realtime

Estimate your monthly cost for this API using the Pricing Calculator.

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>

string

required

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

Send this JSON message after the connection is established:

string

required

Always "subscribe".

object

required

Show properties

string

required

Always "userFills".

string[]

required

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

boolean

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

Example

wscat -c "wss://hypercore.goldrushdata.com/ws?key=$GOLDRUSH_API_KEY"

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

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);
    }
  }
});

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

{
  "method": "unsubscribe",
  "subscription": {
    "type": "userFills",
    "addresses": ["0x31ca8395cf837de08b24da3f660e77761dfb974b"]
  }
}

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.

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

string

Always "userFills".

array<[string, object]>

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

Show fill properties

string

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

string

Fill execution price (decimal string).

string

Fill size (decimal string).

string

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

int

Unix timestamp in milliseconds when the fill executed.

string

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

string

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

string

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

string

L1 transaction hash that included this fill.

int

Parent order ID.

boolean

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

string

Trading fee paid for this fill, denominated in feeToken.

int

Unique trade ID.

string

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

int | null

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

string

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

string

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

string

Optional. Builder address the order was routed through.

object

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

Show properties

string

The wallet whose position was liquidated.

string

Mark price at the time of liquidation.

string

Liquidation method - "market" or "backstop".

userNonFundingLedgerUpdates

stream real-time non-funding ledger events (deposits, withdrawals, vault and staking activity) for…

allFills

stream every fill on HyperCore in real time for global market analytics and cross-wallet…

builderFills

stream live attributed fills for one or more builder addresses in real time.

liquidationFills

stream a global, market-wide feed of every liquidation fill on HyperCore.

builderLiquidations

stream liquidation fills attributed to your builder code in real time.

orderUpdates

stream real-time order lifecycle events (placements, fills, cancels, and rejections) for one or…

See all Hyperliquid endpoints: Overview hub · WebSocket API reference Last reviewed: 2026-06-16

Foundational API

Hyperliquid API

JSON-RPC

Service Keys

Ephemeral Keys

userFills | Hyperliquid WebSocket API

Credit Cost

Processing

Endpoint

Example

Unsubscribe

Streamed message

userNonFundingLedgerUpdates

allFills

builderFills

liquidationFills

builderLiquidations

orderUpdates

Credit Cost

Processing

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed message

​Related endpoints

userNonFundingLedgerUpdates

allFills

builderFills

liquidationFills

builderLiquidations

orderUpdates

Endpoint

Subscribe

Example

Unsubscribe

Streamed message

Related endpoints