# Builder leaderboard | API reference | Femtos

> Every builder code ranked by fees, volume, users or orders, over 24 h to all time. GET /v1/hypercore/builders 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/builders

## Builder leaderboard — GET `/v1/hypercore/builders`

Every builder code ranked by fees, volume, users or orders, over 24 h to all time.

Layers: HyperCore. Not on Elysium or HyperEVM: served on HyperCore only.
Page with live calls: https://femtos.xyz/reference/builders?layer=hypercore

| Param | In | Example or values | Meaning |
|---|---|---|---|
| `window` | query | `(empty)`, `24h`, `7d`, `30d`, `90d`, `all` | Window, whole hours ending with the current one: 24h, 7d, 30d, 90d, or all (since 2025-07-19) |
| `sort` | query | `(empty)`, `fees`, `volume`, `fills`, `users`, `orders` | Order, largest first |
| `limit` | query | `20` | Builders |

```bash
curl -H "Authorization: Bearer $FEMTOS_KEY" "https://api.femtos.xyz/v1/hypercore/builders?window=7d&sort=fees&limit=20"
```

| Field | Type | Meaning |
|---|---|---|
| `builders[]` | object | Ranked by `sort`: {builder, app, entity, fees, feesByToken, volume, fills, takerFills, users, feeRate, feeShare, orders} |
| `builders[].fees` | decimal | Builder fees earned: Σ builder fee of its fills, in USD stablecoins at par (USDC, USDH, USDE, USDT0) |
| `builders[].volume` | decimal | Σ px × sz of its fills, on markets quoted in USD stablecoins at par (USDC, USDH, USDE, USDT0); both sides of a trade it routed are counted only when both carry its code |
| `builders[].users` | int | Distinct accounts behind those fills |
| `builders[].feeShare` | decimal \| null | Its share of every builder's fees in the window, 0..1 (exact to 40 significant digits); null when none earned any |
| `builders[].orders` | object \| null | Its order statuses in the window; null for a window ending before order coverage: {orders, filled, canceled, rejected, triggered, feeTenthsBp} |
| `total` | object | Every builder together (users: distinct across them): {fees, feesByToken, volume, fills, takerFills, users, feeRate, builders} |
| `asOf` | int \| null | When the rollups read were last recomputed (Unix ms, every 5 minutes); null when the window has none |
| `ordersFrom` | ms | Start of the order-status coverage (2026-10-13 15:50 UTC); fills go back to 2025-07-19 |

## Related (Builder codes)

- [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)
- [Builder fills stream](https://femtos.xyz/reference/ws/builder-fills.md) `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. (HyperCore)

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