> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coinversa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Builder endpoints

> The 12 builder analytics endpoints: ledger-exact revenue, attributed flow, cohort mix, retention, and cross-builder overlap — REST and x402.

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](https://docs.coinversa.ai/api-reference/tiers.md#x402-pay-per-call) 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](https://docs.coinversa.ai/concepts/builder-attribution.md).

## 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:

```json theme={null}
{
  "period": "week",
  "builders": [
    {
      "builder": "0x1922810825c90f4270048b96da7b1803cd8609ef",
      "builderName": "Example Builder",
      "revenueUsd": 1204551.18,
      "prevRevenueUsd": 1150322.77,
      "attributedVolumeUsd": 2410880412.55,
      "attributedUsers": 4812,
      "attributedFills": 1930211,
      "feeTenthsBp": 10
    }
  ],
  "verified": {
    "ledger_block": 723441892,
    "ledger_chain_time": "2026-08-21T14:02:11Z",
    "coverage": null
  },
  "dataNotes": "Revenue figures are exact per Hyperliquid's cumulative builder-fee ledger. Trigger-order fills (stop/TP) currently attribute at ledger level only (~6% of fees ecosystem-wide) until the parser upgrade, so join-attributed fills, volume, and user counts slightly undercount versus ledger revenue."
}
```

* `revenueUsd` is **exact** (ledger plane); `attributed*` fields come from the fill join and slightly undercount — see [the two data planes](https://docs.coinversa.ai/concepts/builder-attribution.md#two-data-planes).
* `verified.coverage` is null until the reconciliation pipeline ships — [normal, not an error](https://docs.coinversa.ai/concepts/builder-attribution.md#the-verified-stamp).

## Errors

Builder routes return **huma problem-details** errors (`title` / `status` / `detail` / `code`), the same error model as every `/api/public/v1` endpoint — see [Authentication](https://docs.coinversa.ai/authentication.md#error-responses). A tier-gated request without sufficient entitlement returns:

```json theme={null}
{
  "title": "Forbidden",
  "status": 403,
  "detail": "Api key needed for this request",
  "code": "TIER_GATE",
  "reason": "missing_api_key",
  "current_tier": "none",
  "required_tier": "starter",
  "upgrade_url": "https://coinversa.ai/developers#pricing"
}
```

`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:

```bash theme={null}
curl "https://api.coinversa.ai/api/public/v1/builders/leaderboard?period=week" \
  -H "X-API-Key: cvsa_..."
```

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](https://docs.coinversa.ai/websocket/overview.md#authentication) 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](https://docs.coinversa.ai/api-reference/tiers.md#x402-pay-per-call) 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](https://docs.coinversa.ai/concepts/cohorts.md). `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](https://docs.coinversa.ai/mcp/tools.md): 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.