Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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-api-key>

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

Headline totals, shares and revenue run rate for one builder.

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

One row per market the builder routed in the window, sorted by volume descending (at most 1000 rows).

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

Packed per-day arrays aligned to dates, one entry per calendar day in the window. Days with no fills carry "0.00" / 0.

Per-day shares use that day's denominators.

4. Positioning

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.

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

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.

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. 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

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.

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.

Last updated