Skip to main content
Twelve endpoints cover the Hyperliquid builder-code economy, all under https://api.coinversa.ai/api/public/v1 with the X-API-Key header. Every endpoint is Starter or Pro, and every one has an x402 pay-per-call twin that needs no key at all. For the data model — the exact-vs-attributed distinction, the verified stamp, dataNotes, and builder names — see Builder codes & attribution.

​
Endpoint guide

​
/builders/leaderboard · Starter

All builders ranked by exact ledger revenue over the period (period=day|week|month, default week; limit ≤100, offset ≤1000). Attributed metrics (volume, users, fills) ride along, each with the immediately-preceding same-length window’s value for deltas. feeTenthsBp is the builder’s most common requested fee over the last 7 days of orders, in tenths of a basis point.

​
/builders/{builder}/profile · Starter

One builder in depth: exact revenueUsd for the period (default month), firstSeen / lastSeen in the fee ledger, distinct fee tokens, a daily attributed series with biggestDay, top coins (topCoins ≤50, default 10) with marketType, and user totals including profitableUsers. Gotcha: returns 404 when the builder has no revenue in the fee ledger; the daily series, coins, and user counts are attribution-plane.

​
/trader/{address}/builders · Starter

The per-wallet view: every builder a wallet traded through in the window (since, default 30d, clamped to 90d), ordered by fees paid descending, with fills, volume, and first/last seen. Gotcha: the response’s window echoes what you requested even when the data was clamped to 90d.

​
/builders/{builder}/traders · Pro

A builder’s attributed wallets for the window, sortable by sort=builderFee|volume|pnl (default builderFee; limit ≤500). Each row carries realized PnL on attributed fills, fees paid, volume, live equity, and the exchange-wide all-time pnlTier / sizeTier. Gotcha: equity is 0 and both tiers are null when the wallet isn’t in the cohort rollup yet.

​
/builders/{builder}/fills · Pro

The raw attributed fill stream: time, wallet, coin, marketType (perp|spot|hip4 — @N coins are spot, #N are HIP-4 outcomes), side, price, size, PnL, and the builder fee per fill, with oid (nullable) and tid. Filters: since (default 24h, clamped to 90d), exact coin (BTC, xyz:GOLD, @123, #10010), and address.

​
/builders/{builder}/cohorts · Pro

Cohort composition of the builder’s user base for the period: users, share, fees paid, volume, PnL, and fills split by all-time PnL tier and size tier. Gotcha: wallets missing from the cohort rollup appear under tier untracked, so per-tier user counts always sum to totalUsers; share is users / totalUsers.

​
/builders/{builder}/retention · Pro

Retention triangle over the last 12 calendar months (or 16 ISO weeks with granularity=weekly): wallets are cohorted by the period of their first builder-fee order via this builder, and activeWallets[k] counts how many were still active k periods later (index 0 = the cohort period itself). Parameters: granularity=monthly|weekly (default monthly) and revenueWeighted=true, which adds a per-cohort activeRevenueUsd series of attributed builder fees (fill plane). Gotchas: “active” means placed at least one builder-fee order that month — the order need not fill, so these counts can exceed the attributed-fill user counts on /cohorts and /overlap. It’s the heaviest builder query and is cached for 6 hours.

​
/builders/{builder}/overlap · Pro

The top 10 other builders this builder’s active users also traded through in the period, by shared users. Gotchas: feesUsd is what the shared users paid to the other builder, not to this one; share uses activeUsers (this builder’s attributed users in the period) as the denominator.

​
/builders/{builder}/orders · Pro

Order intent, not just what filled: totalIntents and counts and shares by action type (plain orders, batch modifies, stop/TP trigger orders) in actions, the time-in-force mix (tifs), reduceOnlyShare, a trigger breakdown (take-profit vs stop, market vs limit, position-TPSL vs standalone, resolved vs still-pending), and fillConversion — how much of that intent reached at least one attributed fill. period=day|week|month, default week. Gotcha: trigger-order history begins 2026-03-24 (earlier history is being backfilled — see dataNotes).

​
/builders/{builder}/heatmap · Pro

When the builder’s users trade: a 7×24 UTC weekday-by-hour grid of attributed volume, builder fees and fill counts over a fixed trailing 84 days (12 weeks), zero-filled and Sunday-first. No query parameters.

​
/builders/{builder}/lifecycle · Pro

Every wallet that ever traded via the builder, in mutually exclusive stages by recent activity: active (attributed fill within 7d), cooling (30d), switched (no fill via this builder in 30d but at least one via a different builder), dormant (90d) and movedOn. Headline ratios: trueRetention, churn and competitiveLoss (switched share), with competitiveLossFeesUsd — fees those switched wallets paid to other builders in the last 30d. Gotcha: competitiveLossFeesUsd is null (unknown, never zero) when the fee probe exceeds its budget; the stages and ratios always serve. Cached for 6 hours.

​
/builders/{builder}/journey · Pro

Lifetime economics of the builder’s trailing-year acquisition cohort (wallets with 3+ attributed fills): average and median revenue per wallet, concentration, median days from first fill to the peak-revenue day and to 50% and 75% of lifetime revenue, and where users peak (before day 7, days 7–30, after day 30). Gotcha: the revenue, concentration and day fields are null when users is 0; counts still serve 0. Cached for 6 hours.

​
Response envelope

Every builder response carries builderName (omitted when unknown), a verified stamp, and the constant dataNotes disclosure. A trimmed leaderboard response:
  • revenueUsd is exact (ledger plane); attributed* fields come from the fill join and slightly undercount — see the two data planes.
  • verified.coverage is null until the reconciliation pipeline ships — normal, not an error.

​
Errors

Builder routes return huma problem-details errors (title / status / detail / code), the same error model as every /api/public/v1 endpoint — see Authentication. A tier-gated request without sufficient entitlement returns:
reason is missing_api_key (no key), invalid_api_key (key present but inactive) or insufficient_tier (key below the required tier). Other errors: 400 with detail: "invalid ethereum address" for a malformed builder or wallet address, and 404 from /profile when the builder has no revenue in the fee ledger.

​
For AI agents

The canonical request:
Auth on the REST API is the X-API-Key header — not a Bearer token (the REST API ignores an Authorization: Bearer header and treats it as a missing key; the WebSocket is where a Bearer token belongs).
  • Gate handling — on a 403, read code. If it’s "TIER_GATE", report required_tier and hand the human upgrade_url — or fall back to the endpoint’s x402 twin for keyless pay-per-call.
  • Stamp interpretation — verified.coverage === null is normal (pipeline not yet live); never retry on it. Treat verified.ledger_chain_time as the freshness timestamp. revenueUsd is exact; attributed* fields slightly undercount — relay dataNotes whenever you present the numbers.
  • Field gotchas — builderName absent means unknown, not invalid. Tier slugs are legacy (smart_money, not sharps) — match per Trader cohorts. since silently clamps at 90d (the response echoes what you asked for). Retention’s active counts are orders-plane and can exceed user counts elsewhere.
  • MCP — builder data is in the MCP tool catalog: eleven builder_* tools plus trader_builders, the per-wallet inverse. builder_heatmap is registered but withheld by default while its hourly rollup backfills, so an agent sees eleven of the twelve.