> ## 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 codes & attribution

> How builder-fee revenue and per-fill attribution are computed — the exact on-chain ledger, the orders-to-fills join, the verified stamp, and what dataNotes means.

A **builder code** on Hyperliquid is an address that attaches a fee to the orders it routes — wallets approve a maximum fee per builder, and the builder earns that fee on every fill it originates. It's how front-ends, wallet apps, trading bots, and builder dexes monetize order flow. Coinversa indexes the entire builder-fee economy: exact revenue for every builder, plus fill-level attribution of who traded what through whom.

<Note>
  **Builder ≠ builder dex.** The 7 [builder dexes](/concepts/markets) (`xyz`, `flx`, `vntl`, …) are one kind of builder — venues that list their own markets. But any front-end can run a builder code without being a dex (wallet apps are among the largest). This page and the [builder endpoints](/api-reference/builders) use "builder" to mean any builder-code operator.
</Note>

## Two data planes

Every builder response mixes two data sources with different guarantees:

| Plane           | Source                                                  | Powers                                      | Guarantee                                                        |
| --------------- | ------------------------------------------------------- | ------------------------------------------- | ---------------------------------------------------------------- |
| **Ledger**      | Hyperliquid's own cumulative builder-fee ledger         | `revenueUsd` everywhere                     | **Exact** — validated to ±0.1% against the on-chain ledger       |
| **Attribution** | Trades joined to builder-fee orders on `(oid, address)` | Fills, volume, users, coins, PnL breakdowns | Attributed — currently \~77–95% coverage per builder (see below) |

The one-line rule: **revenue is exact; detail metrics are attributed.** When a leaderboard row says a builder earned \$1.2M last week, that number reconciles with the chain. When it says 4,812 users generated it, that count comes from the fill join and can slightly undercount.

## The trigger-order gap (read dataNotes)

Trigger-order fills (stop-loss / take-profit) currently attribute at ledger level only — roughly **6% of fees ecosystem-wide**, which puts per-builder attribution coverage at **\~77–95%**. Live capture of trigger orders began **2026-08-20**, backfilled to **2026-03-24**, with earlier history in progress.

Practical consequence: attributed fills, volume, and user counts **slightly undercount** versus ledger revenue. Every builder response says so in its `dataNotes` field:

```json theme={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."
```

If you're building on this data, surface the caveat to your users — we do.

## The verified stamp

Every builder response carries a `verified` stamp, the same pattern as the census stamp on entity responses:

```json theme={null}
"verified": {
  "ledger_block": 723441892,
  "ledger_chain_time": "2026-08-21T14:02:11Z",
  "coverage": null
}
```

* `ledger_block` / `ledger_chain_time` — the latest block in Hyperliquid's builder-fee ledger this response was verified against. Treat `ledger_chain_time` as the freshness timestamp.
* `coverage` — **null today**, by design. When the attribution-reconciliation pipeline ships, it becomes a live ratio object (`window_start`, `window_end`, `ledger_fees_usd`, `attributed_fees_usd`, `ratio`, `computed_at`) quantifying exactly how much of ledger revenue the fill-level metrics account for.

<Note>
  `coverage: null` means "not yet provisioned" — it is never an error, and nothing about the response is degraded when it's null. Don't retry on it.
</Note>

## Builder names

`builderName` comes from a curated registry of 115 known builders. When a builder isn't in the registry, the field is **omitted — never guessed**. Builder addresses in responses are always canonical lowercase 0x-hex; path parameters accept any 0x spelling.

## Cohort tiers on builder endpoints

The `/traders` and `/cohorts` endpoints label wallets with their exchange-wide **all-time** `pnlTier` / `sizeTier`, returned as legacy slugs (`smart_money`, `whale`, …) per the [trader cohorts](/concepts/cohorts) vocabulary. These are lifetime classifications — the pulse `cohorts-recent` endpoints classify by 30-day-rolling tiers, so the same wallet can carry a different tier there. Wallets not yet in the cohort rollup appear as `null` tiers on `/traders` and in an `untracked` bucket on `/cohorts`, so per-tier user counts always sum to `totalUsers`.

## History depth

Builder-fee **orders are complete and gapless from 2025-01-25** — attributed fills cover the same range. Most trackers' builder data starts around August 2025; Coinversa's extra depth is visible today through the [retention endpoint's](/api-reference/get-api-public-v1-builders-by-builder-retention) 12-month cohort triangle and the `firstSeen` / `lastSeen` timestamps on builder profiles.

Per-request query windows are narrower than the underlying history: `period` is `day | week | month`, and `since` parameters clamp to 90 days — see [Data windows](/api-reference/data-windows#builder-analytics-windows).

## Which endpoint answers what

| Endpoint                                                                                          | Tier    | Question it answers                                                   |
| ------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------- |
| [`/builders/leaderboard`](/api-reference/get-api-public-v1-builders-leaderboard)                  | Starter | Who are the top builders by exact revenue, and how are they trending? |
| [`/builders/{builder}/profile`](/api-reference/get-api-public-v1-builders-by-builder-profile)     | Starter | One builder's revenue, daily series, top coins, and user base.        |
| [`/trader/{address}/builders`](/api-reference/get-api-public-v1-trader-by-address-builders)       | Starter | Which builders does this wallet trade through?                        |
| [`/builders/{builder}/traders`](/api-reference/get-api-public-v1-builders-by-builder-traders)     | Pro     | Who are a builder's users — with PnL, fees paid, and cohort tiers?    |
| [`/builders/{builder}/fills`](/api-reference/get-api-public-v1-builders-by-builder-fills)         | Pro     | The raw attributed fill stream for a builder.                         |
| [`/builders/{builder}/cohorts`](/api-reference/get-api-public-v1-builders-by-builder-cohorts)     | Pro     | What kind of traders use this builder — sharps or exit liquidity?     |
| [`/builders/{builder}/retention`](/api-reference/get-api-public-v1-builders-by-builder-retention) | Pro     | Do this builder's users stick around month over month?                |
| [`/builders/{builder}/overlap`](/api-reference/get-api-public-v1-builders-by-builder-overlap)     | Pro     | Which other builders do this builder's users also trade through?      |

Cross-builder overlap is only possible because Coinversa attributes fills for **all** builders, not one — a single-builder integration can't see where its users go.

<Note>
  Builder analytics is available over **REST and [x402 pay-per-call](/api-reference/tiers#x402-pay-per-call)** today. MCP tools for builder data are coming — no date yet.
</Note>