builderFills | Hyperliquid WebSocket API - GoldRush API Documentation

Credit Cost

1 per minute

Processing

Realtime

GoldRush-native: No wss://api.hyperliquid.xyz/ws equivalent.
Pass builder (string) for a single builder or addresses (string[]) for many. aggregateByTime optional.
Live-only: No historical snapshot on subscribe. For windowed history, use the Info API builderFillsByTime.
Same per-fill shape as userFills, plus builder and builderFee on every entry; channel name in messages is builderFills.

Subscribe to one builder address (builder) or many (addresses) and receive every fill routed through those builders as they execute, batched per block as [address, fill] tuples. Each fill carries the matched builder address and the corresponding builderFee.

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. Provide either builder (single address) or addresses (array of addresses).

method

string

required

Always "subscribe".

subscription

object

required

Show properties

type

string

required

Always "builderFills".

builder

string

Single builder address (lowercase 0x-prefixed 42-character hex) to stream fills for. Mutually exclusive with addresses.

addresses

string[]

Array of builder addresses to stream fills for - the multi-builder form of builder. Mutually exclusive with builder.

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":"builderFills","builder":"0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"}}

Unsubscribe

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

{
  "method": "unsubscribe",
  "subscription": {
    "type": "builderFills",
    "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
  }
}

Unsubscribe matches subscriptions by exact body. A subscription created with builder: "0xAAA" is a different subscription from one created with addresses: ["0xAAA"], even if they target the same builder. To narrow a multi-builder set, unsubscribe the original list in full, then resubscribe with the smaller list.

Streamed message

Each push has channel: "builderFills" and a fills array of [address, fill] tuples. The first element of each tuple is the trader who executed the fill; the fill object carries the trade details, including the builder it was routed through and the builderFee earned.

{
  "channel": "builderFills",
  "fills": [
    [
      "0x742d35cc6634c0532925a3b844bc9e7595f7f2e2",
      {
        "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,
        "builderFee": "0.1",
        "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"
      }
    ]
  ]
}

channel

string

Always "builderFills".

fills

array<[string, object]>

Tuples of [address, fill]. The address is the trader who placed the order; the fill object carries the trade details plus builder-attribution fields.

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 the trader held on this 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 for the trader (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 by the trader 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.

builder

string

Builder address the order was routed through - matches one of the subscribed builders.

builderFee

string

Builder fee earned for this fill, denominated in feeToken.

cloid

string

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

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

Errors

A missing or malformed builder/addresses field returns an error message on the same channel:

{ "channel": "error", "data": "subscription builderFills requires a 'builder' field" }

allFills

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

liquidationFills

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

userFills

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

Last reviewed: 2026-06-19

Credit Cost

Processing

​Endpoint

​Subscribe

​Example

​Unsubscribe

​Streamed message

​Errors

​Related endpoints

allFills

liquidationFills

userFills

Endpoint

Subscribe

Example

Unsubscribe

Streamed message

Errors

Related endpoints