> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/builder-analytics/builder-dashboard.md). # Builder Dashboard Per-builder revenue, volume, trader, market-share, profitability and retention stats. API reference for the **builder dashboard** endpoints. They expose volume, revenue, trader counts, share of Hyperliquid volume and a per-asset breakdown for one builder over a fixed window, a daily series for charts, live long/short exposure, trader profitability, and a weekly retention matrix. *** ## Base URL ``` https://api.hydromancer.xyz ``` ## Authentication Send your API key as a Bearer token on every request: ``` Authorization: Bearer ``` Your key must be authorized for these endpoints. Contact us to enable access. ## Conventions * **`builder`** (required): the routed builder code, the address that received the builder fee on the fill. 0x-prefixed, 42 characters, case-insensitive. * **`window`** (optional, default `7d`; not used by `builder-retention-cohorts` or `builder-positioning`): one of `today`, `1d`, `7d`, `30d`, `90d`, `all`. The five complete-day presets are runs of whole UTC days ending **yesterday** (`all` starts on the builder's first active day). `today` is the exception: the current partial UTC day, from `00:00` UTC up to now, so it moves through the day and is at most 60 s stale. * **`withToday`** (optional, default `false`, `builder-stats` only): when `true`, the response gains a nested **`today`** object — a full stats block for the current partial UTC day — alongside the settled window, which is returned **unchanged**. Omitted by default, so existing responses are identical. Ignored when the window already ends today (the `today` preset). Note the two blocks' distinct `traders` counts do not add (a trader active in both is counted in both). * **Volume** is the sum of `abs(px * sz)` over fills routed through the builder. **Revenue** is the sum of `builder_fee` paid in USD-stable tokens (`USDC`, `USDT0`, `USDE`); fees paid in other tokens are excluded, not converted. * **Share of Hyperliquid** divides by exchange-wide trade volume across every venue and market type (perps, HIP-3 dexes, spot, outcome markets), counting one side per trade. Settlements, auto-deleveraging, vault netting, dust conversion and outcome mint/redeem lifecycle actions are not trades. On outcome markets each matched leg counts once, so a mint or burn through the book contributes both of its legs. * **Decimal values** are returned as **strings**, e.g. `"1234.56"`. Ratios carry up to 10 decimal places. Dates are UTC `YYYY-MM-DD`. * Responses are cached for 60 seconds per (builder, window). * **Responses are compressed.** The origin always gzips these endpoints, and the edge delivers gzip or brotli to any client that advertises support in `Accept-Encoding`, which every HTTP library and browser does. A request that advertises nothing is delivered as plain JSON by the edge, so `curl` should use `--compressed`. Error bodies from these endpoints (400, 404) follow the same rule. * A builder with no fills in the window returns **200** with zero totals (an empty `assets` list, all-zero series). **404** is reserved for an address that has never routed a fill, or for `all` when its first fill is today. *** ## 1. Window stats ``` GET /dashboard/builder-stats?builder=
&window= ``` Headline totals, shares and revenue run rate for one builder. ```bash curl --compressed -H "Authorization: Bearer $API_KEY" \ "https://api.hydromancer.xyz/dashboard/builder-stats?builder=0xb84168cf3be63c6b8dad05ff5d755e97432ff80b&window=7d" ``` ```json { "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b", "window": "7d", "startDate": "2026-08-26", "endDate": "2026-09-01", "days": 7, "volume": "605701761.01", "revenue": "302855.947989", "revenueTokens": ["USDC", "USDT0", "USDE"], "fills": 412330, "traders": 14151, "newTraders": 812, "volumePerTrader": "42806.71", "avgDailyTraders": "5120.43", "tradingDays": 7, "hyperliquidVolume": "63114522018.40", "hyperliquidVolumeShare": "0.0095969", "allBuildersVolume": "2880000000.00", "builderVolumeShare": "0.2103131114", "revenueRunRate": { "daily": "43265.14", "monthly": "1297954.06", "annualized": "15791774.36" } } ``` | Field | Description | | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `startDate`, `endDate`, `days` | The resolved window (inclusive) and its length in calendar days. | | `volume` | Routed volume in the window. | | `revenue` | Builder fees in the tokens listed in `revenueTokens`. | | `fills` | Routed fills. | | `traders` | Distinct users with a routed fill. | | `newTraders` | Users whose first-ever fill with this builder falls in the window. | | `volumePerTrader` | `volume / traders`. | | `avgDailyTraders` | Sum of daily distinct users divided by `days`. | | `tradingDays` | Days with at least one routed fill. | | `hyperliquidVolume`, `hyperliquidVolumeShare` | Exchange-wide one-sided trade volume and the builder's share of it. | | `allBuildersVolume`, `builderVolumeShare` | Volume across every builder and the builder's share of it. | | `revenueRunRate` | `daily = revenue / days`, `monthly = daily * 30`, `annualized = daily * 365`. For `today` the divisor is the elapsed fraction of the UTC day (an "at current pace" figure), and the field is `null` until 04:00 UTC, when too little of the day has elapsed to extrapolate. | ## 2. Volume by asset ``` GET /dashboard/builder-volume-by-asset?builder=
&window= ``` One row per market the builder routed in the window, sorted by volume descending (at most 1000 rows). ```bash curl --compressed -H "Authorization: Bearer $API_KEY" \ "https://api.hydromancer.xyz/dashboard/builder-volume-by-asset?builder=0xb84168cf3be63c6b8dad05ff5d755e97432ff80b&window=30d" ``` ```json { "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b", "window": "30d", "startDate": "2026-08-03", "endDate": "2026-09-01", "assets": [ { "coin": "BTC", "dex": "hyperliquid", "marketType": "perp", "volume": "1078250213.46", "revenue": "539125.00", "fills": 248485, "traders": 14157, "volumeShare": "0.4129" }, { "coin": "SOL", "dex": "hyperliquid", "marketType": "perp", "volume": "339055500.03", "revenue": "169527.69", "fills": 136659, "traders": 10198, "volumeShare": "0.1298" }, { "coin": "xyz:SPCX", "dex": "xyz", "marketType": "perp", "volume": "99122436.53", "revenue": "74461.99", "fills": 39725, "traders": 2385, "volumeShare": "0.038" } ] } ``` | Field | Description | | --------------------------------------- | ------------------------------------------------------------ | | `coin`, `dex` | The market. HIP-3 coins carry their dex prefix (`xyz:SPCX`). | | `marketType` | `perp`, `spot` or `outcome`. | | `volume`, `revenue`, `fills`, `traders` | As above, for this market. | | `volumeShare` | This market's share of the builder's own window volume. | ## 3. Daily series ``` GET /dashboard/builder-daily-series?builder=
&window= ``` Packed per-day arrays aligned to `dates`, one entry per calendar day in the window. Days with no fills carry `"0.00"` / `0`. ```bash curl --compressed -H "Authorization: Bearer $API_KEY" \ "https://api.hydromancer.xyz/dashboard/builder-daily-series?builder=0xb84168cf3be63c6b8dad05ff5d755e97432ff80b&window=7d" ``` ```json { "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b", "window": "7d", "startDate": "2026-08-26", "endDate": "2026-09-01", "dates": ["2026-08-26", "2026-08-27", "2026-08-28", "2026-08-29", "2026-08-30", "2026-08-31", "2026-09-01"], "series": { "volume": ["81234567.10", "…", "…", "…", "…", "…", "…"], "revenue": ["40617.28", "…", "…", "…", "…", "…", "…"], "fills": [58120, 0, 0, 0, 0, 0, 0], "traders": [5231, 0, 0, 0, 0, 0, 0], "newTraders": [112, 0, 0, 0, 0, 0, 0], "hyperliquidVolumeShare": ["0.0091", "…", "…", "…", "…", "…", "…"], "builderVolumeShare": ["0.2044", "…", "…", "…", "…", "…", "…"] } } ``` Per-day shares use that day's denominators. ## 4. Positioning ``` GET /dashboard/builder-positioning?builder=
``` Live long/short exposure of the positions your traders hold **right now**. The only endpoint here that is not a window aggregate, so it takes no `window`; it is at most 60 seconds stale. ```bash curl --compressed -H "Authorization: Bearer $API_KEY" \ "https://api.hydromancer.xyz/dashboard/builder-positioning?builder=0xb84168cf3be63c6b8dad05ff5d755e97432ff80b" ``` ```json { "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b", "longNotional": "50250088.958362", "shortNotional": "15702566.839671", "netNotional": "34547522.118691", "grossNotional": "65952655.798033", "longShare": "0.7619", "longPositions": 15117, "shortPositions": 3636, "totalPositions": 18962, "traders": 12274 } ``` Notional is `|size| × mark price`. Both sides are positive magnitudes — the direction is in `netNotional`, which goes negative when the book is net short. `longShare` is the long side over `grossNotional`, as a ratio. A builder that has routed fills but holds nothing open returns zeros, not a 404. A `503` means our position engine is still starting up — retry shortly rather than treating it as an error. ## 5. Profitability ``` GET /dashboard/builder-profitability?builder=
&window= ``` Completed-trade outcomes for the builder's traders. A trade counts in the window on the day its position **closed**, carrying its whole PnL, so a position opened before the window still counts in full. ```bash curl --compressed -H "Authorization: Bearer $API_KEY" \ "https://api.hydromancer.xyz/dashboard/builder-profitability?builder=0xb84168cf3be63c6b8dad05ff5d755e97432ff80b&window=30d" ``` ```json { "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b", "window": "30d", "startDate": "2026-08-10", "endDate": "2026-09-08", "days": 30, "trades": 260578, "wins": 101529, "losses": 159049, "winRate": "0.3896", "traders": 28979, "profitableTraders": 9412, "profitableTraderShare": "0.3248", "grossPnl": "1240118.55", "netPnl": "-1516463.49", "fundingPnl": "-118240.10", "fees": "2638342.94", "avgTradePnl": "-5.82", "avgTraderPnl": "-52.33", "fills": 512440, "avgFillsPerTrade": "1.97", "holdTime": { "meanSeconds": "142832.00", "p10Seconds": "167.00", "p50Seconds": "7246.00", "p95Seconds": "447447.00" }, "scope": "perp-and-spot" } ``` **`holdTime`** is how long positions stayed open, in seconds, over the same window as the rest of the response — `window=30d` means positions that **closed** within those 30 days, each counted for its full duration even if it was opened long before the window started. It is `null` when the window has no trades, rather than zero. Read the percentiles, not just the mean: hold time is heavily right-skewed. In the example above the mean is \~40 hours while the median is \~2 hours, so the mean describes almost none of the builder's traders. The percentiles are t-digest approximations; the mean is exact. **Perp and spot only.** Outcome (HIP-4) prediction markets keep a separate trade history and are **not** included here — `scope` says so on every response. If you route outcome markets, your perp and spot numbers are complete but your outcome activity is not counted, and a builder routing *only* outcome markets reads zeros here. Outcome profitability has its own endpoint, `/dashboard/outcome-builder-profitability`, documented under [outcome builder analytics](/readme/outcome-analytics/outcome-builder-dashboard.md). It returns the same fields with `scope: "outcome"`, so the two can be read side by side — but they are separate lineages and must not be added together without care: a trade appears in exactly one of them. **`winRate` and `profitableTraderShare` answer different questions.** `winRate` is winning **trades** over all trades, so your most active accounts dominate it. `profitableTraderShare` is the share of **traders** whose summed PnL over the window is positive. A trader can win most of their trades and still be down over the window, so the two routinely differ — read the second one for "are my users making money". Both are ratios, not percentages: multiply by 100 to display. `grossPnl` is before fees and funding; `netPnl` is after both. A trade that breaks exactly even counts as a loss. `avgTradePnl` divides `netPnl` by trades, `avgTraderPnl` divides it by traders. ## 6. Retention cohorts ``` GET /dashboard/builder-retention-cohorts?builder=
&weeks=&cohorts= ``` Weekly retention matrix. Traders are grouped by the week of their **first fill through this builder**, then counted again in each later week they fill through it. Weeks run Monday to Sunday, UTC. This endpoint does not take `window`. Instead: * **`weeks`** (optional, default `12`, max `26`): the highest week offset reported. `W0` is the cohort's own week. * **`cohorts`** (optional, default `26`, max `104`): how many trailing cohorts to return, counted back from the current week. ```bash curl --compressed -H "Authorization: Bearer $API_KEY" \ "https://api.hydromancer.xyz/dashboard/builder-retention-cohorts?builder=0xb84168cf3be63c6b8dad05ff5d755e97432ff80b&weeks=12" ``` ```json { "builder": "0xb84168cf3be63c6b8dad05ff5d755e97432ff80b", "weeks": 12, "cohorts": [ { "week": "2026-08-17", "label": "Aug 17-23", "size": 4512, "activeUsers": [4512, 1774, 875, 394], "retention": ["1.00", "0.3932", "0.1939", "0.0873"], "censored": false }, { "week": "2026-08-24", "label": "Aug 24-30", "size": 4683, "activeUsers": [4683, 1473, 531], "retention": ["1.00", "0.3145", "0.1134"], "censored": false } ] } ``` Cohorts are ordered oldest first, so the response reads top to bottom as it renders. **Row lengths differ by design.** Each cohort is truncated at its own age — a three-week-old cohort has four entries, not `weeks + 1` — which is what makes the matrix triangular. Within that span the arrays are dense, so index *i* is always week offset *i*, and a week in which nobody returned is a real `0` rather than a missing entry. `activeUsers[0]` is the cohort itself, so `retention[0]` is always `"1.00"`. `retention` values are ratios, not percentages: multiply by 100 to display. **`censored`.** A cohort at the very start of our builder-fill history counts every trader who was already active as though they were new, which inflates that cohort and understates its retention. Those cohorts carry `"censored": true` — show them differently, or exclude them, rather than comparing them with the rest. The flag is absolute, not per-builder: a builder whose first fill came well after our history begins never has one. Activity means **any fill** — one fill anywhere in a week retains the trader for that week, with no volume or trade-count floor. ## Errors | Status | When | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `builder` missing or not a 0x-prefixed 42-character address; `window` not one of the presets. `weeks` and `cohorts` are clamped to their documented range rather than rejected. | | 403 | The API key is not authorized for the endpoint. | | 503 | `builder-positioning` only: our position engine is still starting up. Temporary — retry shortly. | | 404 | The address has never routed a fill, or for `all` its first fill is today. A known builder with a quiet window is a 200 with zeros, and one whose cohorts all fall outside the requested range is a 200 with an empty `cohorts` list. |