> ## 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 user 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). ## OpenAPI ````yaml /api-reference/openapi.json get /api/public/v1/builders/{builder}/lifecycle openapi: 3.1.0 info: title: coinversa-api version: 0.1.0 servers: - url: https://api.coinversa.ai description: Production security: [] paths: /api/public/v1/builders/{builder}/lifecycle: get: tags: - Builder Analytics summary: Builder user lifecycle description: >- 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). operationId: get-api-public-v1-builders-by-builder-lifecycle parameters: - description: Builder address (0x-hex) in: path name: builder required: true schema: description: Builder address (0x-hex) type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/BuilderLifecycleBody' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Bad Request '401': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Unauthorized '422': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Unprocessable Entity '429': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Too Many Requests '500': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Internal Server Error '504': content: application/problem+json: schema: $ref: '#/components/schemas/APIError' description: Gateway Timeout security: - apiKey: [] components: schemas: BuilderLifecycleBody: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.coinversa.ai/schemas/BuilderLifecycleBody.json format: uri readOnly: true type: string active: $ref: '#/components/schemas/BuilderLifecycleStatus' description: 'Definition: last attributed fill via THIS builder within 7 days' builder: type: string builderName: description: Known display name for the builder; omitted if unknown type: string churn: description: >- 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) format: double type: number competitiveLoss: description: >- 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 format: double type: number competitiveLossFeesUsd: description: >- 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 format: double type: - number - 'null' cooling: $ref: '#/components/schemas/BuilderLifecycleStatus' description: >- Definition: last attributed fill via THIS builder within 30 days, but more than 7 days ago dataNotes: type: string dormant: $ref: '#/components/schemas/BuilderLifecycleStatus' description: >- Definition: no attributed fill via ANY builder within 30 days, and the last fill via this builder was within 90 days movedOn: $ref: '#/components/schemas/BuilderLifecycleStatus' description: >- Definition: no attributed fill via any builder within 30 days, and no attributed fill via this builder within 90 days (wallets whose orders never filled at all land here too) switched: $ref: '#/components/schemas/BuilderLifecycleStatus' description: >- Definition: NO attributed fill via this builder within 30 days BUT >= 1 attributed fill via a DIFFERENT builder within 30 days — wallets demonstrably still trading builder flow, just not here. The other-builder fill's order is recovered up to 90 days before the 30-day window; fills of orders resting longer are missed (see dataNotes) totalUsers: description: >- 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) format: int32 type: integer trueRetention: description: >- Definition: (active + cooling) / totalUsers — the share of all historical order-placing users that still filled via this builder within the last 30 days format: double type: number verified: $ref: '#/components/schemas/BuilderStamp' required: - builder - totalUsers - active - cooling - switched - dormant - movedOn - trueRetention - churn - competitiveLoss - competitiveLossFeesUsd - dataNotes type: object APIError: additionalProperties: false properties: $schema: description: A URL to the JSON Schema for this object. examples: - https://api.coinversa.ai/schemas/APIError.json format: uri readOnly: true type: string code: description: Machine-readable error code type: string current_tier: description: Caller's effective tier type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string required_tier: description: Minimum tier for this operation type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upgrade_url: description: Where to upgrade type: string type: object BuilderLifecycleStatus: additionalProperties: false properties: share: description: users / totalUsers; 0 when the builder has no historical users format: double type: number users: format: int32 type: integer required: - users - share type: object BuilderStamp: additionalProperties: false properties: coverage: $ref: '#/components/schemas/BuilderCoverage' description: >- Attribution coverage vs the ledger; null until the coverage pipeline is provisioned ledger_block: description: >- Latest block in HL's builder-fee ledger this data was verified against format: int64 type: integer ledger_chain_time: description: Chain timestamp of that ledger entry (RFC3339) type: string required: - ledger_block - ledger_chain_time - coverage type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object BuilderCoverage: additionalProperties: false properties: attributed_fees_usd: description: Join-attributed fees in the rollup window format: double type: number computed_at: description: When the rollup was computed (RFC3339) type: string ledger_fees_usd: description: Exact ledger revenue in the rollup window format: double type: number ratio: description: >- attributed_fees / ledger_fees — the share of revenue the fill-level metrics account for format: double type: number window_end: description: End of that window (RFC3339) type: string window_start: description: Start of the window the coverage rollup was computed over (RFC3339) type: string required: - window_start - window_end - ledger_fees_usd - attributed_fees_usd - ratio - computed_at type: object securitySchemes: apiKey: description: Get one at https://coinversa.ai/developers in: header name: X-API-Key type: apiKey ````