HyperCore APIs are in beta. Message fields, limits, and behavior may change, including breaking changes. To request access, contact [email protected].
Fills for orders placed with one or more builder codes.
{
"method": "subscribe",
"subscriptionId": "builders_01",
"subscription": {
"type": "builderFills",
"builders": [
"0x2222222222222222222222222222222222222222"
]
}
}| Parameter | Type | Required | Description |
|---|---|---|---|
builders | string[] | Yes | Builder addresses. Always an array, even for one builder. 1 to 200 addresses. |
fromBlock | integer | No | Replay from this block (inclusive), then continue live. Omit for live only. |
aggregateByTime | boolean | No | Merge a taker order's partial fills in the same block. Default false. |
Each fill includes the builder it was attributed to.
{
"channel": "subscriptionResponse",
"subscriptionId": "builders_01",
"data": {
"type": "builderFills",
"builders": [
"0x2222222222222222222222222222222222222222"
]
}
}Each message carries the fills from one block.
{
"seq": 1,
"channel": "builderFills",
"subscriptionId": "builders_01",
"data": {
"blockNumber": 1183759646,
"blockTime": 1791999593756,
"fills": [
[
"0x654086857e1fad6dcf05cf6695cce51ea3984268",
{
"coin": "BTC",
"px": "81772.0",
"sz": "0.00067",
"side": "B",
"time": 1791999593756,
"startPosition": "-0.37115",
"dir": "Close Short",
"closedPnl": "0.012",
"hash": "0x5a1e...",
"oid": 574446008493,
"crossed": true,
"fee": "0.0246",
"tid": 87654321,
"feeToken": "USDC",
"twapId": null,
"builder": "0x2222222222222222222222222222222222222222"
}
]
]
}
}| Field | Description |
|---|---|
data.blockNumber | Block the fills came from. Persist it to resume. |
data.blockTime | Block time, Unix milliseconds. |
data.fills | Array of [user, fill] pairs. |
| Field | Type | Description |
|---|---|---|
coin | string | Market. See coin names. |
px | string | Execution price. |
sz | string | Executed size. |
side | string | B (buy) or A (sell), for this user. |
time | integer | Fill time, Unix milliseconds. |
startPosition | string | Position size before the fill. |
dir | string | Display direction, for example Open Long or Close Short. |
closedPnl | string | Realized profit or loss from this fill. |
hash | string | Transaction hash. |
oid | integer | ID of the order that filled. |
crossed | boolean | true if this side was the taker. |
fee | string | Fee paid; negative for a rebate. |
tid | integer | Trade ID. Both sides of a trade share the same tid. |
feeToken | string | Token the fee was paid in. |
twapId | integer or null | TWAP order ID, if the fill came from a TWAP. |
liquidation | object | Present on liquidation fills: liquidatedUser, markPx, method. |
builder | string | Present when the order used a builder code. |
Fill objects follow Hyperliquid's native fill format, so conditional fields such as builderFee, deployerFee, priorityGas, and cloid can also appear. Ignore fields you don't use.
aggregateByTime (default false) merges a taker order's partial fills within the same block into one record: sz, fee, closedPnl, and, when present, builderFee, deployerFee, and priorityGas are summed, and px is the size-weighted average price, which isn't rounded to the tick size. Other fields, including tid, hash, and startPosition, come from the first partial fill. Maker fills are never merged.
Pass fromBlock to replay from a recent block, inclusive. After a disconnect, resubscribe with fromBlock set to the last processed blockNumber plus one and deduplicate on tid plus user. If the block is older than the replay window, you receive a gap message for the missing range, then data from the oldest available block. See replay and recovery.
{"method":"unsubscribe","subscriptionId":"builders_01"}