> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bluprynt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List tokenomics changes

> Required scope: `tokenomics:read`.



## OpenAPI

````yaml /openapi/explorer.json get /tokenomics/changes
openapi: 3.0.0
info:
  title: Explorer API
  version: 0.0.1
  description: Key-callable routes of the Bluprynt Compliance Explorer registry API.
servers:
  - url: https://explorer-api.bluprynt.com
security:
  - apiKey: []
tags:
  - name: Disclosure monitoring
  - name: Tokenomics
paths:
  /tokenomics/changes:
    get:
      tags:
        - Tokenomics
      summary: List tokenomics changes
      description: 'Required scope: `tokenomics:read`.'
      operationId: Tokenomics.changes
      parameters:
        - name: class
          required: false
          in: query
          description: >-
            Applied before `limit`. Comma-separated (unlock_event |
            emission_change | allocation_change | allocation_move |
            control_change | value_accrual_change | governance_proposal |
            venue_notice | supply_change | governance_param_change |
            legal_classification_change | migration_event | onchain_mismatch).
          schema: {}
        - name: direction
          required: false
          in: query
          description: >-
            Applied before `limit`. Comma-separated (weakens | mixed |
            strengthens | neutral | undetermined); `undetermined` = no assessed
            direction.
          schema: {}
        - name: materiality
          required: false
          in: query
          description: >-
            Applied before `limit`. Comma-separated (material | clarification |
            editorial | review | unclassified).
          schema: {}
        - name: status
          required: false
          in: query
          description: >-
            Applied before `limit`. Comma-separated (upcoming | occurred |
            proposed | superseded).
          schema: {}
        - name: eventFrom
          required: false
          in: query
          description: >-
            Applied before `limit`. ISO 8601; events with no evidenced time
            never match.
          schema: {}
        - name: eventTo
          required: false
          in: query
          description: Applied before `limit`. ISO 8601.
          schema: {}
        - name: detectedFrom
          required: false
          in: query
          description: Applied before `limit`. ISO 8601.
          schema: {}
        - name: detectedTo
          required: false
          in: query
          description: Applied before `limit`. ISO 8601.
          schema: {}
        - name: minCirculatingPct
          required: false
          in: query
          description: >-
            Applied before `limit`. Exact decimal; only events with an evidenced
            circulating-supply percent ≥ it match.
          schema: {}
        - name: mismatchKind
          required: false
          in: query
          description: >-
            Applied before `limit`. Comma-separated SPEC-059 §4.7 issuer vs
            on-chain comparison kinds (undisclosed_unlock | amount_mismatch |
            date_mismatch | recipient_mismatch | disclosed_not_on_chain).
          schema: {}
        - name: since
          required: false
          in: query
          description: >-
            Opaque `nextCursor` from a previous response (anything else is 400
            `invalid_cursor`): returns later revisions in ascending `feedSeq`.
            Without it the response is a backlog page in priority order: weakens
            → mixed → strengthens → neutral → undetermined, then newest
            `detectedAt`, then id.
          schema: {}
        - name: page
          required: false
          in: query
          description: >-
            Opaque `nextPage` from a previous backlog response with the same
            filters (anything else is 400 `invalid_page`): the next backlog
            page. Cannot be combined with `since`.
          schema: {}
        - name: limit
          required: false
          in: query
          description: 1–200, default 50.
          schema: {}
        - name: asset
          required: false
          in: query
          description: Applied before `limit`. One watched registry asset id.
          schema: {}
      responses:
        '200':
          description: Envelope wrapping one feed page.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenomicsChangesDto'
        '401':
          description: Unknown or revoked key (`api_key_invalid`).
        '403':
          description: The key does not hold the required scope (`api_key_scope_missing`).
      security:
        - apiKey: []
components:
  schemas:
    TokenomicsChangesDto:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/TokenomicsChangeDto'
        hasMore:
          type: boolean
          description: >-
            More rows match the filters than were returned. With `since`: poll
            again with `nextCursor`. Without `since`: fetch the rest of the
            backlog with `page=nextPage`.
        nextCursor:
          type: string
          description: >-
            Opaque incremental resume token, passed back as `since`. With
            `since`, it points after the last returned row (or repeats the
            `since` sent when none). Without `since` (backlog pages), it is the
            head the first backlog page froze, the same on every page: after the
            backlog, polling from it returns every later revision, including
            rows revised while the backlog was paged.
        nextPage:
          type: string
          nullable: true
          description: >-
            Opaque backlog token (priority order only), passed back as `page`
            with the same filters; null when the backlog is complete or with
            `since`.
        order:
          type: string
          enum:
            - since
            - priority
      required:
        - items
        - hasMore
        - nextCursor
        - nextPage
        - order
    TokenomicsChangeDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
        revision:
          type: number
          description: >-
            Feed revision of this event (1 on first write; +1 each later
            change).
        feedSeq:
          type: string
          description: >-
            Monotonic feed sequence of this revision (exact integer string), for
            ordering and audit. Resume with `nextCursor`, not this value.
        category:
          type: string
          enum:
            - tokenomics
        itemKey:
          type: string
          nullable: true
          description: >-
            Stable item id across ledger revisions (T-30 → T-7 → T-1 → occurred
            share one).
        itemRevision:
          type: number
          nullable: true
          description: Ledger revision of the underlying reading.
        asset:
          $ref: '#/components/schemas/TokenomicsAssetRefDto'
        class:
          type: string
          description: SPEC-059 §4.5 change class.
        status:
          type: string
          nullable: true
          enum:
            - upcoming
            - occurred
            - proposed
            - superseded
          description: >-
            A scheduled unlock stays `upcoming`; only a finalized on-chain
            release is `occurred`.
        eventAt:
          type: string
          nullable: true
          description: When the event happens/happened (evidenced; null if not stated).
        detectedAt:
          type: string
        fieldName:
          type: string
        changeKind:
          type: string
        materiality:
          type: string
        summary:
          type: string
          nullable: true
        oldValue:
          type: string
          nullable: true
        newValue:
          type: string
          nullable: true
        impact:
          $ref: '#/components/schemas/TokenomicsImpactDto'
        unlock:
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/TokenomicsUnlockDto'
        oldEvidence:
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/TokenomicsEvidenceSideDto'
        newEvidence:
          $ref: '#/components/schemas/TokenomicsEvidenceSideDto'
        primaryEvidence:
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/TokenomicsPrimaryEvidenceDto'
        onChainEvidence:
          description: Every chain read behind the reading.
          type: array
          items:
            $ref: '#/components/schemas/TokenomicsChainEvidenceDto'
        observationEvidenceSha256:
          type: string
          nullable: true
          description: sha256 of the ledger reading’s evidence bundle.
        observationRecordedAt:
          type: string
          nullable: true
          description: When the ledger recorded the reading.
        onchainMismatch:
          nullable: true
          description: >-
            Issuer vs on-chain comparison (SPEC-059 §4.7); null when none is
            stored or the stored payload is incomplete. Never derived from
            `impact`.
          type: object
          allOf:
            - $ref: '#/components/schemas/TokenomicsOnchainMismatchDto'
      required:
        - id
        - revision
        - feedSeq
        - category
        - itemKey
        - itemRevision
        - asset
        - class
        - status
        - eventAt
        - detectedAt
        - fieldName
        - changeKind
        - materiality
        - summary
        - oldValue
        - newValue
        - impact
        - unlock
        - oldEvidence
        - newEvidence
        - primaryEvidence
        - onChainEvidence
        - observationEvidenceSha256
        - observationRecordedAt
        - onchainMismatch
    TokenomicsAssetRefDto:
      type: object
      properties:
        assetId:
          type: string
          nullable: true
          description: Registry asset id (null when not yet in the registry).
        chainId:
          type: number
        contractAddress:
          type: string
      required:
        - assetId
        - chainId
        - contractAddress
    TokenomicsImpactDto:
      type: object
      properties:
        direction:
          type: string
          nullable: true
          enum:
            - weakens
            - mixed
            - strengthens
            - neutral
          description: >-
            Evidenced effect on holders (BLU-4355 shared contract) — never a
            price forecast; null = undetermined.
        status:
          type: string
          enum:
            - assessed
            - undetermined
            - pending
        disposition:
          type: string
          nullable: true
        reason:
          type: string
          nullable: true
        rulesVersion:
          type: string
          nullable: true
        assessedAt:
          type: string
          nullable: true
      required:
        - direction
        - status
        - disposition
        - reason
        - rulesVersion
        - assessedAt
    TokenomicsUnlockDto:
      type: object
      properties:
        amount:
          type: string
          description: Whole tokens, exact decimal string.
        amountRaw:
          type: string
          description: Raw base units, exact integer string.
        decimals:
          type: number
        pctCirculating:
          type: string
          nullable: true
          description: Exact decimal percent of circulating supply.
        circulatingReadAt:
          type: string
          nullable: true
        pctTotalSupply:
          type: string
          nullable: true
          description: Exact decimal percent of total supply.
        recipientClass:
          type: string
          nullable: true
        recipientAddress:
          type: string
          nullable: true
        scheduleMatch:
          type: string
          nullable: true
          enum:
            - as_scheduled
            - deviates
            - unscheduled
        txHash:
          type: string
          nullable: true
      required:
        - amount
        - amountRaw
        - decimals
        - pctCirculating
        - circulatingReadAt
        - pctTotalSupply
        - recipientClass
        - recipientAddress
        - scheduleMatch
        - txHash
    TokenomicsEvidenceSideDto:
      type: object
      properties:
        value:
          type: string
          nullable: true
        quote:
          type: string
          nullable: true
        artifactId:
          type: string
          nullable: true
        sha256:
          type: string
          nullable: true
      required:
        - value
        - quote
        - artifactId
        - sha256
    TokenomicsPrimaryEvidenceDto:
      type: object
      properties:
        kind:
          type: string
          enum:
            - issuer_document
            - on_chain
            - governance
            - venue_notice
        observedAt:
          type: string
          nullable: true
          description: >-
            Exact time the primary evidence was observed: held-document fetch
            time (µs), source retrieval time, or chain read time — as recorded,
            never rounded or estimated.
        sourceUrl:
          type: string
          nullable: true
          description: Project-held source URL (document, proposal, notice).
        artifactId:
          type: string
          nullable: true
          description: >-
            Id of the immutable held artifact the quote was read from (for
            issuer documents, the held-document key, which is its source URL).
        sha256:
          type: string
          nullable: true
          description: sha256 of the held artifact or normalised text.
        quote:
          type: string
          nullable: true
          description: >-
            Verbatim span from the held source, byte-for-byte as stored (always
            set for `issuer_document`; null for `on_chain`).
        publishedAt:
          type: string
          nullable: true
          description: >-
            Source-stated publication / creation time (governance `createdAt`,
            venue `publishedAt`).
        chain:
          nullable: true
          description: Set for `on_chain`.
          type: object
          allOf:
            - $ref: '#/components/schemas/TokenomicsChainEvidenceDto'
      required:
        - kind
        - observedAt
        - sourceUrl
        - artifactId
        - sha256
        - quote
        - publishedAt
        - chain
    TokenomicsChainEvidenceDto:
      type: object
      properties:
        chainId:
          type: number
        address:
          type: string
          description: Contract or account that was read.
        method:
          type: string
          description: >-
            Read method or event (e.g. `eth_call:totalSupply()`,
            `log:Transfer`).
        callData:
          type: string
          nullable: true
        block:
          type: string
          description: Finalized block number, exact decimal string.
        blockHash:
          type: string
          nullable: true
        blockTimestamp:
          type: string
          nullable: true
          description: >-
            Block timestamp exactly as read from the chain (unix seconds or ISO,
            as recorded).
        txHash:
          type: string
          nullable: true
        logIndex:
          type: string
          nullable: true
        backend:
          type: string
          description: RPC/indexer backend that served the read.
        readAt:
          type: string
          description: When the read was made, exactly as recorded.
        exchangeSha256:
          type: string
          description: sha256 of the recorded request/response exchange.
      required:
        - chainId
        - address
        - method
        - callData
        - block
        - blockHash
        - blockTimestamp
        - txHash
        - logIndex
        - backend
        - readAt
        - exchangeSha256
    TokenomicsOnchainMismatchDto:
      type: object
      properties:
        kinds:
          type: array
          items:
            type: string
            enum:
              - undisclosed_unlock
              - amount_mismatch
              - date_mismatch
              - recipient_mismatch
              - disclosed_not_on_chain
        comparisonStatus:
          type: string
          enum:
            - comparable
            - undetermined
          description: >-
            `undetermined` when either side is missing, stale or incomplete; no
            kind is then asserted as fact.
        reason:
          type: string
        issuer:
          $ref: '#/components/schemas/TokenomicsMismatchIssuerDto'
        onChain:
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/TokenomicsMismatchOnChainDto'
        tolerances:
          $ref: '#/components/schemas/TokenomicsMismatchTolerancesDto'
        comparedAt:
          type: string
          description: ISO 8601.
        issuerEvidence:
          description: >-
            The typed issuer records `issuer.evidenceIds` resolve to, in
            citation order.
          type: array
          items:
            $ref: '#/components/schemas/TokenomicsIssuerEvidenceDto'
      required:
        - kinds
        - comparisonStatus
        - reason
        - issuer
        - onChain
        - tolerances
        - comparedAt
        - issuerEvidence
    TokenomicsMismatchIssuerDto:
      type: object
      properties:
        evidenceIds:
          description: Held issuer-document evidence ids compared.
          type: array
          items:
            type: string
        amount:
          type: string
          nullable: true
          description: Exact decimal string as disclosed.
        eventAt:
          type: string
          nullable: true
          description: Disclosed event time (ISO 8601).
        recipientClass:
          type: string
          nullable: true
        asOf:
          type: string
          nullable: true
          description: As-of time of the disclosure (ISO 8601).
        sourcesChecked:
          type: number
          description: Held token-owned sources read for the comparison.
      required:
        - evidenceIds
        - amount
        - eventAt
        - recipientClass
        - asOf
        - sourcesChecked
    TokenomicsMismatchOnChainDto:
      type: object
      properties:
        evidenceIds:
          description: Finalized chain-read evidence ids compared.
          type: array
          items:
            type: string
        scanFromBlock:
          type: string
          description: Exact integer string.
        scanToBlock:
          type: string
          description: Exact integer string.
        finalizedBlock:
          type: string
          description: Exact integer string.
        complete:
          type: boolean
          description: >-
            The whole window was scanned; an incomplete scan never proves
            absence.
      required:
        - evidenceIds
        - scanFromBlock
        - scanToBlock
        - finalizedBlock
        - complete
    TokenomicsMismatchTolerancesDto:
      type: object
      properties:
        relativeAmountPct:
          type: number
        dateHours:
          type: number
      required:
        - relativeAmountPct
        - dateHours
    TokenomicsIssuerEvidenceDto:
      type: object
      properties:
        id:
          type: string
          description: >-
            P3 evidence id: sha256 of `[url, sha256, charOffset, quote]` (span)
            or `[url, sha256]` (source revision).
        kind:
          type: string
          enum:
            - issuer_span
            - issuer_source
          description: >-
            `issuer_span`: a held verbatim span; `issuer_source`: a checked held
            source revision.
        url:
          type: string
          description: Fetched project-document URL.
        sha256:
          type: string
          description: sha256 of the held document text.
        sourceEvidenceId:
          type: string
          description: Id of the held source revision the record belongs to.
        observedAt:
          type: string
          description: When the source revision was observed (ISO 8601).
        charOffset:
          type: number
          nullable: true
          description: Offset of the span in the held text (span only).
        quote:
          type: string
          nullable: true
          description: Verbatim span (span only).
      required:
        - id
        - kind
        - url
        - sha256
        - sourceEvidenceId
        - observedAt
        - charOffset
        - quote
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: bx_live_…
      description: >-
        Exchange API key issued by Bluprynt, sent as `Authorization: Bearer
        bx_live_<key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.