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

> Single-builder overview: exact ledger revenue over the period, first/last fee accrual, distinct fee tokens, most common requested fee rate, a daily attributed series (fees, volume, users, fills) with the biggest day highlighted, top coins by attributed volume, and how many of the period's attributed wallets are all-time profitable. coins is null (unknown, never an empty list) when the live coin-split pass exceeds its budget — everything else always serves; see the response's dataNotes. Returns 404 for addresses with no revenue in the fee ledger.



## OpenAPI

````yaml /api-reference/openapi.json get /api/public/v1/builders/{builder}/profile
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}/profile:
    get:
      tags:
        - Builder Analytics
      summary: Builder profile
      description: >-
        Single-builder overview: exact ledger revenue over the period,
        first/last fee accrual, distinct fee tokens, most common requested fee
        rate, a daily attributed series (fees, volume, users, fills) with the
        biggest day highlighted, top coins by attributed volume, and how many of
        the period's attributed wallets are all-time profitable. coins is null
        (unknown, never an empty list) when the live coin-split pass exceeds its
        budget — everything else always serves; see the response's dataNotes.
        Returns 404 for addresses with no revenue in the fee ledger.
      operationId: get-api-public-v1-builders-by-builder-profile
      parameters:
        - description: Builder address (0x-hex)
          in: path
          name: builder
          required: true
          schema:
            description: Builder address (0x-hex)
            type: string
        - explode: false
          in: query
          name: period
          schema:
            default: month
            enum:
              - day
              - week
              - month
            type: string
        - explode: false
          in: query
          name: topCoins
          schema:
            default: 10
            format: int32
            maximum: 50
            minimum: 1
            type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BuilderProfileBody'
          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
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/APIError'
          description: Not Found
        '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:
    BuilderProfileBody:
      additionalProperties: false
      properties:
        $schema:
          description: A URL to the JSON Schema for this object.
          examples:
            - https://api.coinversa.ai/schemas/BuilderProfileBody.json
          format: uri
          readOnly: true
          type: string
        biggestDay:
          $ref: '#/components/schemas/BuilderDay'
          description: >-
            Day with the highest fees in the period, selected on the ledger's
            per-UTC-day deltas whenever the ledger covers it (attributedFeesUsd
            then carries the ledger figure — see dataNotes for the serving
            basis)
        builder:
          type: string
        builderName:
          description: Known display name for the builder; omitted if unknown
          type: string
        coins:
          description: >-
            Top coins by attributed volume; null (not empty) when the live
            coin-split pass exceeded its budget — see dataNotes. An empty array
            is a real 'no attributed coins'
          items:
            $ref: '#/components/schemas/BuilderCoin'
          type:
            - array
            - 'null'
        daily:
          description: Daily attributed series (join plane — see dataNotes)
          items:
            $ref: '#/components/schemas/BuilderDay'
          type:
            - array
            - 'null'
        dataNotes:
          type: string
        feeTenthsBp:
          description: >-
            Most common requested fee over the last 7d of orders; 0 if no recent
            orders
          format: int32
          type: integer
        feeTokens:
          description: Distinct fee tokens the builder has accrued revenue in
          format: int32
          type: integer
        firstSeen:
          description: First fee accrual in HL's ledger (RFC3339)
          type: string
        lastSeen:
          description: Latest fee accrual in HL's ledger (RFC3339)
          type: string
        period:
          type: string
        profitableUsers:
          description: >-
            Of those, wallets that are all-time profitable per the traders
            rollup
          format: int32
          type: integer
        revenueUsd:
          description: Exact ledger revenue over the period
          format: double
          type: number
        totalUsers:
          description: Distinct wallets with attributed fills in the period
          format: int32
          type: integer
        verified:
          $ref: '#/components/schemas/BuilderStamp'
      required:
        - builder
        - period
        - firstSeen
        - lastSeen
        - feeTokens
        - feeTenthsBp
        - revenueUsd
        - daily
        - coins
        - totalUsers
        - profitableUsers
        - 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
    BuilderDay:
      additionalProperties: false
      properties:
        attributedFeesUsd:
          format: double
          type: number
        date:
          description: UTC day (YYYY-MM-DD)
          type: string
        fills:
          format: int64
          type: integer
        users:
          format: int32
          type: integer
        volumeUsd:
          format: double
          type: number
      required:
        - date
        - attributedFeesUsd
        - volumeUsd
        - users
        - fills
      type: object
    BuilderCoin:
      additionalProperties: false
      properties:
        attributedFeesUsd:
          format: double
          type: number
        coin:
          type: string
        fills:
          format: int64
          type: integer
        marketType:
          enum:
            - perp
            - spot
            - hip4
          type: string
        volumeUsd:
          format: double
          type: number
      required:
        - coin
        - marketType
        - volumeUsd
        - attributedFeesUsd
        - fills
      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

````