userFills | Hyperliquid WebSocket API - GoldRush API Documentation

Credit Cost

1 per minute

Processing

Realtime

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.

Send this JSON message after the connection is established:

method

string

required

Always "subscribe".

subscription

object

required

Show 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

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

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

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

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.

Show fill properties

coin

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

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.

Show 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".

liquidationFills

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

userNonFundingLedgerUpdates

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

Last reviewed: 2026-06-16

Credit Cost

Processing

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed message

​Related endpoints

liquidationFills

userNonFundingLedgerUpdates

Endpoint

Subscribe

Example

Unsubscribe

Streamed message

Related endpoints