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

# Builder user lifecycle

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

Every wallet that ever traded via this builder, partitioned into 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 — detectable only with all-builder attribution), dormant (90d), and movedOn. Headline ratios: trueRetention, churn, and competitiveLoss (switched share) with competitiveLossFeesUsd — builder fees those switched wallets paid to other builders in the last 30d (null, meaning unknown and never zero, when the fee probe exceeds its budget — the buckets and ratios always serve; see the response's dataNotes).

## Path parameters

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

## Response `200`

OK

- BuilderLifecycleBody
  - `$schema` string, uri — A URL to the JSON Schema for this object.
  - `active` BuilderLifecycleStatus, required
    - `share` number, double, required — users / totalUsers; 0 when the builder has no historical users
    - `users` integer, required
  - `builder` string, required
  - `builderName` string — Known display name for the builder; omitted if unknown
  - `churn` number, double, required — Definition: (dormant + movedOn) / totalUsers — the share that stopped filling via this builder AND shows no attributed fill via any other builder in the last 30 days (left the attributed builder ecosystem, not poached)
  - `competitiveLoss` number, double, required — Definition: switched / totalUsers — the share that stopped filling via this builder within the last 30 days while filling via a DIFFERENT builder in those same 30 days. Requires cross-builder fill attribution; interfaces without it necessarily report 0 here
  - `competitiveLossFeesUsd` number, double, nullable, required — Builder fees the switched wallets paid to OTHER builders over the last 30 days — revenue measurably lost to competitors; null when the fee probe exceeded its budget (see dataNotes) — null means unknown, never zero
  - `cooling` BuilderLifecycleStatus, required
    - `share` number, double, required — users / totalUsers; 0 when the builder has no historical users
    - `users` integer, required
  - `dataNotes` string, required
  - `dormant` BuilderLifecycleStatus, required
    - `share` number, double, required — users / totalUsers; 0 when the builder has no historical users
    - `users` integer, required
  - `movedOn` BuilderLifecycleStatus, required
    - `share` number, double, required — users / totalUsers; 0 when the builder has no historical users
    - `users` integer, required
  - `switched` BuilderLifecycleStatus, required
    - `share` number, double, required — users / totalUsers; 0 when the builder has no historical users
    - `users` integer, required
  - `totalUsers` integer, required — Every wallet that ever placed a builder-fee order via this builder, over its entire history (orders plane — includes wallets whose orders never filled; see dataNotes)
  - `trueRetention` number, double, required — Definition: (active + cooling) / totalUsers — the share of all historical order-placing users that still filled via this builder within the last 30 days
  - `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)