builderFillsByTime | Hyperliquid Info API
Info API
builderFillsByTime | Hyperliquid Info API
Hyperliquid builderFillsByTime: fetch a builder’s attributed trade fills within a time window for revenue attribution and fee accounting.
POST
builderFillsByTime | Hyperliquid Info API
Credit Cost
1 per call
Processing
Realtime
type: "builderFillsByTime" is used to fetch a builder’s attributed trade fills within a time window for revenue attribution and fee accounting.
- GoldRush-native: No
POST api.hyperliquid.xyz/infoequivalent. Available only viaPOST hypercore.goldrushdata.com/info. - Each response contains at most 2,000 fills; widen the window in chunks or page by advancing
startTimeif you need more. - GoldRush serves this
typefrom a dedicated HyperCore historical store, so windows can extend back to GoldRush’s full HyperCore coverage. - Use
builderFills(noTimesuffix) when you only need the most recent N fills without specifying a window.
[startTime, endTime] window in milliseconds. Use this for builder revenue reports, monthly fee reconciliation, or rebuilding historical builder order-flow.
Builder-keyed. GoldRush-native as there is no upstream Hyperliquid /info equivalent. Served from a dedicated HyperCore historical store, so windows can extend back to GoldRush’s full HyperCore coverage.
Endpoint
Request
string
required
Always
"builderFillsByTime".string
required
The builder address that orders were routed through. Must be a
0x-prefixed 42-character hex address.int
required
Unix timestamp in milliseconds. Inclusive lower bound. Required unless
cursor is supplied.int
Unix timestamp in milliseconds. Inclusive upper bound. Defaults to current server time when omitted.
boolean
When
true, partial fills sharing the same timestamp are consolidated into one row. Default false.string
Pagination cursor - a Unix timestamp in milliseconds encoded as a string. When set, returns fills strictly before this time and overrides
startTime. Use the time value of the oldest fill in the previous page to fetch the next page.Example
Response
An array of fill objects ordered bytime. Each entry is a fill from an order that was routed through the builder address within the window.
Field descriptions
All numeric fields (
px, sz, startPosition, closedPnl, fee, builderFee) are returned as decimal strings with full upstream precision (up to 18 decimal places). Do not parse them as floats - keep them as strings or use a fixed-precision decimal type.string
The trader’s wallet address - the account that placed the order routed through the builder code.
string
Asset symbol - e.g.
"BTC", "ETH" for perps; spot pairs use the @N form (e.g. "@107"); HIP-3 markets use the deployer-prefixed form.string
Fill execution price.
string
Fill size.
string
"B" for buy/long, "A" for ask/short.int
Unix timestamp in milliseconds when the fill executed.
string
Signed position size the trader held on this 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 for the trader (zero when the fill opens or extends a position).
string
L1 transaction hash that included this fill.
int
Parent order ID.
int
Unique trade 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 by the trader for this fill, denominated in
feeToken.string
Symbol the fee was paid in - typically
"USDC".string
Optional. Builder fee earned for this fill, denominated in
feeToken. Omitted when no builder fee was charged.string
Optional. Client order ID (
0x-prefixed 32-character hex) if one was set at order placement.object
Optional. Present only when this fill closed a position as part of a liquidation event.
Related endpoints
builderFills
fetch a builder’s most recent attributed trade fills for revenue attribution and order-flow analytics.
userFillsByTime
fetch a user’s trade fills within a time window for P&L recaps and tax ledger reconstruction.
userTwapSliceFillsByTime
fetch a user’s TWAP slice fills within a time window for execution-quality reconciliation on algorithmic…
userFills
fetch a user’s most recent trade fills without specifying a time window.