# Builder fills stream | API reference | Femtos

> Every fill of one builder code as it happens, with its builder fee: the rows of the builder fills route, pushed per block. One frame per block with all its matching events. WebSocket channel hc.builder.fills on HyperCore: parameters, response fields and a live call per layer.

- Base URL: `https://api.femtos.xyz/v1` (REST) · `wss://api.femtos.xyz/v1/ws` (WebSocket) · MCP: `https://api.femtos.xyz/mcp`
- Auth: `Authorization: Bearer $FEMTOS_KEY`. Free key: https://dashboard.femtos.xyz/signup (browser), or with
  no browser: `GET https://femtos.xyz/accounts/agent/challenge`, solve its proof of work, then `POST https://femtos.xyz/accounts/agent/signup`
  (https://femtos.xyz/agents.md#agent-onboarding)
- Decimals are exact strings, times Unix milliseconds, addresses lowercase `0x`
- Whole API in one file: https://femtos.xyz/agents.md · OpenAPI: https://api.femtos.xyz/v1/openapi.json · Index: https://femtos.xyz/llms.txt
- Page with live calls: https://femtos.xyz/reference/ws/builder-fills

WebSocket: get a ticket (`POST https://api.femtos.xyz/v1/ws-ticket` with your key), connect to `wss://api.femtos.xyz/v1/ws?ticket=$TICKET`, send the frame below; the first message has `"snapshot": true`. Details: https://femtos.xyz/agents.md#websocket

## Builder fills stream — WS `hc.builder.fills`

Every fill of one builder code as it happens, with its builder fee: the rows of the builder fills route, pushed per block. One frame per block with all its matching events.

Layers: HyperCore. Not on Elysium or HyperEVM: a channel of HyperCore only.
Page with live calls: https://femtos.xyz/reference/ws/builder-fills?layer=hypercore

| Param | In | Example or values | Meaning |
|---|---|---|---|
| `builder` | filter | `0xb84168cf3be63c6b8dad05ff5d755e97432ff80b` | Builder address (0x, as orders name it in `builder.b`), or a named wallet's handle |
| `coin` | filter | (optional) | HyperCore market (BTC, @107, xyz:TSLA) |
| `user` | filter | (optional) | Account: 0x address or a named wallet's handle |
| `min_notional` | filter | (optional) | Minimum notional (px × sz, in the quote of the market) |

```json
{"op":"subscribe","channel":"hc.builder.fills","filter":{"builder":"0xb84168cf3be63c6b8dad05ff5d755e97432ff80b"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | WsBuilderFill[] | the builder's last 50 fills (matching the filter) seen since hl-flows started, oldest first |
| `data` | WsBuilderFill[] | each fill carrying the builder's code, with its builder fee, the block it happens, from our node's fills before they reach ClickHouse: one frame per HyperCore block, `data` the block's matching events in order (a block with none sends nothing): {block, eventIdx, time, user, entity, coin, side, px, sz, notional, crossed, dir, …} |
| `data[].builderFee` | decimal | Builder fee of the fill, in feeToken |
| `data[].notional` | decimal | px × sz, quote units |
| `latency_ms.source_to_sent` | int | block → sent by the server |
| `batch` | "block" | every live frame: one block, `data` its matching events |

## Related (Builder codes)

- [Builder leaderboard](https://femtos.xyz/reference/builders.md) `GET /v1/hypercore/builders`: Every builder code ranked by fees, volume, users or orders, over 24 h to all time. (HyperCore)
- [Builder](https://femtos.xyz/reference/builder.md) `GET /v1/hypercore/builders/{builder}`: One builder code: totals and rank, day by day, per market, order outcomes and fee rates. (HyperCore)
- [Builder orders](https://femtos.xyz/reference/builder-orders.md) `GET /v1/hypercore/builders/{builder}/orders`: Every status of the orders sent with one builder code, rejections and their reasons included. (HyperCore)
- [Builder orders stream](https://femtos.xyz/reference/ws/builder-orders.md) `WS hc.builder.orders`: Every status of the orders sent with one builder code as it happens, rejections and their reasons included. One frame per block with all its matching events. (HyperCore)
- [Builder fills](https://femtos.xyz/reference/builder-fills.md) `GET /v1/hypercore/builders/{builder}/fills`: Every fill of one builder code, with its builder fee, oid, tid and hash. (HyperCore)

Every page: https://femtos.xyz/reference.md