---
title: "Builder user journey economics"
method: GET
path: "/api/public/v1/builders/{builder}/journey"
tags: ["Builder Analytics"]
---

# Builder user journey economics

`GET /api/public/v1/builders/{builder}/journey`

Lifetime economics of the builder's trailing-year acquisition cohort (wallets with 3+ attributed fills): average and median revenue per wallet, concentration (avg/median), median days from first fill to peak-revenue day and to 50% and 75% of lifetime revenue, and where users peak (before day 7, days 7-30, after day 30). Answers how fast and how unevenly a builder monetizes new users. BREAKING (2026-08-28): avgRevenueUsd, medianRevenueUsd, concentration, and every avgDays/medianDays field are now NULLABLE and serve null when users = 0 (no qualifying cohort). They previously served 0, which clients could not distinguish from a cohort that genuinely earned nothing. Counts (users, peakDayDistribution) are unchanged and still serve 0.

## Path parameters

- `builder` string, required — Builder address (0x-hex)

## Response `200`

OK

- BuilderJourneyBody
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `avgRevenueUsd` number, double, nullable, required — Mean lifetime attributed builder fees per qualifying wallet; null when there is no qualifying cohort (users = 0). Null means unknown, never zero
  - `builder` string, required
  - `builderName` string — Known display name for the builder; omitted if unknown
  - `concentration` number, double, nullable, required — avgRevenueUsd / medianRevenueUsd — how whale-skewed per-user revenue is (1 = evenly spread). Null when there is no qualifying cohort, and also when the median is 0 (the ratio is undefined)
  - `dataNotes` string, required
  - `daysToHalfRevenue` BuilderJourneyDays, required
    - `avgDays` number, double, nullable, required — Mean across qualifying wallets; null when there is no qualifying cohort (users = 0) — an absence of data, not a zero
    - `medianDays` number, double, nullable, required — Median across qualifying wallets; null when there is no qualifying cohort (users = 0) — an absence of data, not a zero
  - `daysToPeak` BuilderJourneyDays, required
    - `avgDays` number, double, nullable, required — Mean across qualifying wallets; null when there is no qualifying cohort (users = 0) — an absence of data, not a zero
    - `medianDays` number, double, nullable, required — Median across qualifying wallets; null when there is no qualifying cohort (users = 0) — an absence of data, not a zero
  - `daysToThreeQuartersRevenue` BuilderJourneyDays, required
    - `avgDays` number, double, nullable, required — Mean across qualifying wallets; null when there is no qualifying cohort (users = 0) — an absence of data, not a zero
    - `medianDays` number, double, nullable, required — Median across qualifying wallets; null when there is no qualifying cohort (users = 0) — an absence of data, not a zero
  - `medianRevenueUsd` number, double, nullable, required — Median lifetime attributed builder fees per qualifying wallet; null when there is no qualifying cohort (users = 0). Null means unknown, never zero
  - `minFills` integer, required — Inclusion floor: wallets need >= this many lifetime attributed fills (fixed at 3 so one-shot wallets don't define days-to-peak as trivially zero)
  - `peakDayDistribution` BuilderJourneyPeakDistribution, required
    - `from7To30d` integer, required — Peak-revenue day 7 to 30 days (inclusive) after the first fill
    - `over30d` integer, required — Peak-revenue day more than 30 days after the first fill
    - `under7d` integer, required — Wallets whose peak-revenue day came less than 7 days after their first fill
  - `users` integer, required — Wallets the journey stats are computed over — those whose first builder-fee order via this builder was within the last 365 days and with at least minFills lifetime attributed fills (see dataNotes)
  - `verified` BuilderStamp
    - `coverage` BuilderCoverage, required
      - `attributed_fees_usd` number, double, required — Join-attributed fees in the rollup window
      - `computed_at` string, required — When the rollup was computed (RFC3339)
      - `ledger_fees_usd` number, double, required — Exact ledger revenue in the rollup window
      - `ratio` number, double, required — attributed_fees / ledger_fees — the share of revenue the fill-level metrics account for
      - `window_end` string, required — End of that window (RFC3339)
      - `window_start` string, required — Start of the window the coverage rollup was computed over (RFC3339)
    - `ledger_block` integer, required — Latest block in HL's builder-fee ledger this data was verified against
    - `ledger_chain_time` string, required — Chain timestamp of that ledger entry (RFC3339)

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error
- `504` — Gateway Timeout

---

[API](https://skmtc.dev/coinversa/apis/coinversa-api.md) · [All operations](https://skmtc.dev/coinversa/apis/coinversa-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/coinversa/coinversa-api/revisions/77c03c427063/schema)