openapi: 3.1.0
info:
  title: Starkscan Explorer API
  version: 2.0.0
  description: Breaking Starkscan rename of the previous public explorer contract for external integrators, SDKs, CLI workflows, and direct API integrations, including selected advanced utility routes. Clients generated from older artifacts must switch to the Starkscan discovery path, auth header, vendor extensions, and schema identifiers.
servers:
  - url: https://api.starkscan.co
    description: Hosted external Starkscan API base. Requests execute against /v1/* on the API host; app-host /api/v1/* remains compatibility.
security:
  - StarkscanApiKey: []
paths:
  /.well-known/starkscan-agent.json:
    get:
      summary: Agent-readable Starkscan memory contract
      description: Public machine-readable discovery document for agents. It points agents at the authenticated meta routes, route families, operating rules, and typed artifact contract without requiring chat history.
      servers:
        - url: /
          description: Same-host public well-known discovery root
      security:
        - {}
      responses:
        "200":
          description: Agent-readable discovery and operating contract
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentMemoryContract"
      x-starkscan-audience: public-core
      x-starkscan-certification: certified
      x-starkscan-oracle: openapi-schema
      x-starkscan-evidence-level: sampled
      x-starkscan-certification-scope: schema
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: public
      parameters:
        - $ref: "#/components/parameters/RequestIdHeader"
      tags:
        - Reference
  /v1/meta/capabilities:
    get:
      summary: Agent-readable API capabilities
      description: Authenticated route-family catalog for agents and developers. Hosted external clients call `/v1/meta/capabilities` with `X-Starkscan-Api-Key`. Same-origin explorer traffic uses this `/v1` route through the trusted edge. Use this before selecting the smallest route set for a task.
      security:
        - StarkscanApiKey: []
      responses:
        "200":
          description: Capability and route-family catalog
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetaCapabilitiesView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: openapi-schema
      x-starkscan-evidence-level: sampled
      x-starkscan-certification-scope: schema
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      parameters:
        - $ref: "#/components/parameters/RequestIdHeader"
      tags:
        - Reference
  /v1/meta/chains:
    get:
      summary: Supported chain ids for this deployment
      description: Authenticated chain catalog. Hosted external clients call `/v1/meta/chains` with `X-Starkscan-Api-Key`. Same-origin explorer traffic uses this `/v1` route through the trusted edge.
      security:
        - StarkscanApiKey: []
      responses:
        "200":
          description: Supported chain metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetaChainsView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: openapi-schema
      x-starkscan-evidence-level: sampled
      x-starkscan-certification-scope: schema
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      parameters:
        - $ref: "#/components/parameters/RequestIdHeader"
      tags:
        - Reference
  /v1/meta/agent-context:
    get:
      summary: Full agent context contract
      description: Authenticated context document that combines the public agent-memory contract with handoff artifact guidance. Hosted external clients call `/v1/meta/agent-context` with `X-Starkscan-Api-Key`. Same-origin explorer traffic uses this `/v1` route through the trusted edge.
      security:
        - StarkscanApiKey: []
      responses:
        "200":
          description: Full agent context contract
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MetaAgentContextView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: openapi-schema
      x-starkscan-evidence-level: sampled
      x-starkscan-certification-scope: schema
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      parameters:
        - $ref: "#/components/parameters/RequestIdHeader"
      tags:
        - Reference
  /v1/{chain}/status:
    get:
      summary: Chain status
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Current indexed and finalized head status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExplorerStatusView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: certified
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: exact-block
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Status
  /v1/{chain}/rpc:
    post:
      summary: Starknet JSON-RPC gateway
      description: Bounded Starknet JSON-RPC gateway. Read methods are forwarded through Starkscan's rate-limited upstream pool; write methods remain gated by the RPC pilot controls. Accepts a single JSON-RPC request object or a batch of up to 25 request objects. JSON parse errors and invalid JSON-RPC payloads are returned as JSON-RPC error envelopes with HTTP 200 so clients can keep standard JSON-RPC handling.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - $ref: "#/components/parameters/RequestIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/JsonRpcRequest"
                - $ref: "#/components/schemas/JsonRpcBatchRequest"
      responses:
        "200":
          description: JSON-RPC response or JSON-RPC error envelope forwarded from the gateway
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/JsonRpcResponse"
                  - $ref: "#/components/schemas/JsonRpcBatchResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: provider-rpc
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: advanced-utility
      x-starkscan-key-tier: utility
      tags:
        - Reference
  /v1/{chain}/rpc/ws:
    get:
      summary: Starknet JSON-RPC WebSocket proxy
      description: Beta WebSocket upgrade route for Starknet JSON-RPC subscription clients. The route is disabled unless the deployment explicitly enables `RPC_WSS_ENABLED` and configures a Starknet WebSocket upstream. After a successful protocol upgrade, clients send and receive Starknet JSON-RPC subscription messages over the WebSocket connection. This lane is certified separately from the HTTP JSON-RPC gateway.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "101":
          description: WebSocket protocol upgrade accepted.
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Chain is not served by this deployment.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: route-smoke
      x-starkscan-evidence-level: smoke
      x-starkscan-certification-scope: stream
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: advanced-utility
      x-starkscan-key-tier: utility
      tags:
        - Reference
  /v1/{chain}/block/{number_or_hash}:
    get:
      summary: Block detail by number or hash
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: number_or_hash
          in: path
          required: true
          schema:
            type: string
          example: "7550747"
        - name: tx_limit
          in: query
          description: Max block transactions returned (clamped to 1..200). Defaults to `50` when omitted.
          schema:
            type: integer
            format: int32
            default: 50
            minimum: 1
            maximum: 200
          example: 50
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Block detail with transaction preview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Block not found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: certified
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: exact-block
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Blocks
  /v1/{chain}/block-at-timestamp:
    get:
      summary: Resolve timestamp to indexed block
      description: Resolve a Unix seconds or RFC3339 timestamp to the closest indexed Starknet block. `closest=before` is the default and is the right choice for accounting "as of" balance snapshots such as calendar close. The route is served from indexed block facts only; RPC is used by the correctness gate, not by the request path.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: timestamp
          in: query
          required: true
          description: Unix seconds or RFC3339 timestamp with timezone.
          schema:
            oneOf:
              - type: string
                pattern: ^[0-9]{1,19}$
                description: Unix seconds.
              - type: string
                format: date-time
                maxLength: 96
                description: RFC3339 timestamp with timezone.
          example: 2025-12-31T23:59:59Z
        - name: closest
          in: query
          description: |
            Direction for the selected block. `before` returns the last indexed block at or before the timestamp; `after` returns the first indexed block at or after the timestamp.
          schema:
            type: string
            enum:
              - before
              - after
            default: before
          example: before
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Timestamp resolution with inclusive indexed bounds
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockAtTimestampView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: No indexed block exists in the requested closest direction
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: certified
      x-starkscan-oracle: materialized-db-plus-rpc
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: accounting
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Blocks
  /v1/{chain}/blocks:
    get:
      summary: Paginated latest blocks feed
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: cursor
          in: query
          description: Optional block number cursor for reverse pagination.
          schema:
            type: integer
            format: int64
            minimum: 0
          example: 8279910
        - name: limit
          in: query
          description: Page size (clamped to 1..200). Defaults to `25` when omitted.
          schema:
            type: integer
            format: int32
            default: 25
            minimum: 1
            maximum: 200
          example: 25
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Chain blocks page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChainBlockListPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: exact-block
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Blocks
  /v1/{chain}/block/{number}/txs:
    get:
      summary: Paginated transactions for one block
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: number
          in: path
          required: true
          schema:
            type: integer
            format: int64
          example: 8279910
        - name: cursor
          in: query
          description: Optional transaction index cursor for reverse pagination.
          schema:
            type: integer
            format: int32
            minimum: 0
          example: 0
        - name: limit
          in: query
          description: Page size (clamped to 1..100). Defaults to `25` when omitted.
          schema:
            type: integer
            format: int32
            default: 25
            minimum: 1
            maximum: 100
          example: 25
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Block transaction page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockTransactionPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Block not found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: exact-block
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Blocks
  /v1/{chain}/tx/previews:
    post:
      summary: Batch transaction previews by hash
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - $ref: "#/components/parameters/RequestIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TransactionPreviewBatchRequest"
      responses:
        "200":
          description: Ordered transaction preview results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionPreviewBatchView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: contract-fixture
      x-starkscan-evidence-level: smoke
      x-starkscan-certification-scope: utility-batch
      x-starkscan-slo-class: batch
      x-starkscan-stability: stable
      x-starkscan-surface-tier: advanced-utility
      x-starkscan-key-tier: utility
      description: Advanced utility route. This helper is externally supported, but it requires a broader utility-access key than the baseline read tier and is not the default starting point for new integrations.
      tags:
        - Utilities
  /v1/{chain}/tx/{tx_hash}:
    get:
      summary: Transaction detail by hash
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: tx_hash
          in: path
          required: true
          schema:
            type: string
          example: "0x054bfd961fb8b156c77ffa0f7882b8fcc1836753c2d3d88435b640d6300c8bd9"
        - name: logLimit
          in: query
          description: Maximum number of event logs returned in the transaction detail payload. Defaults to `96` when omitted.
          schema:
            type: integer
            format: int32
            default: 96
            minimum: 1
            maximum: 256
          example: 96
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Transaction detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TransactionDetailView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Transaction not found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: certified
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: exact-block
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Transactions
  /v1/{chain}/txs:
    get:
      summary: Paginated latest transactions feed
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: cursor
          in: query
          description: Optional cursor encoded as `block:tx`.
          schema:
            type: string
        - name: limit
          in: query
          description: Page size (clamped to 1..200).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 200
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Chain transactions page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChainTransactionListPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: exact-block
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Transactions
  /v1/{chain}/messages:
    get:
      summary: Paginated canonical cross-layer messages
      description: Global cross-layer message feed served only from indexed StarknetCore protocol message facts. Rows are keyed by protocol message hash, not token-transfer or bridge-adapter activity. Coverage metadata is explicit because a data plane may still be backfilling protocol message facts.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: direction
          in: query
          description: Optional message direction filter.
          schema:
            type: string
            enum:
              - all
              - l1_to_l2
              - l2_to_l1
        - name: txHash
          in: query
          description: Optional transaction hash filter.
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: messageHash
          in: query
          description: Optional protocol message hash filter.
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: cursor
          in: query
          description: |
            Optional opaque cursor returned unchanged from `nextCursor`. New responses use `m1:block:tx:message:tx_hash:message_hash:direction:source_tier` so pagination remains stable when multiple messages share the same numeric tuple. Legacy `block:tx:message` cursors remain accepted for older clients.
          schema:
            type: string
            pattern: ^(m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)|[0-9]+:[0-9]+:[0-9]+)$
        - name: limit
          in: query
          description: Page size (defaults to the full bounded pool directory page; clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Global message page with explicit coverage metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessagePage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Reference
  /v1/{chain}/tx/{tx_hash}/trace:
    get:
      summary: Transaction Cairo trace by hash
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: tx_hash
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Transaction trace payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractTransactionTraceView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Transaction trace not found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: exact-block
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Transactions
  /v1/{chain}/address/{address}:
    get:
      summary: Address aggregate summary
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Address summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressSummaryView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Addresses
  /v1/{chain}/address/{address}/attribution:
    get:
      summary: Indexed address attribution
      description: Address-oriented attribution lookup backed by indexed metadata. Use this when a partner workflow starts from an address and needs a readable label/protocol attribution without calling RPC on the request path.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Indexed address attribution metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressAttributionView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Addresses
  /v1/{chain}/address/summaries:
    post:
      summary: Batch address aggregate summaries
      description: |-
        Utility-tier batch helper for bounded address hydration. The route returns request-ordered indexed summary facts for up to 128 addresses and intentionally avoids raw activity scans, deployment repair, and RPC calls on the request path. Treat `activityCountExact=false` as an explicit inexact/unknown signal, not as proof that an address has no additional activity.

        Advanced utility route. This helper is externally supported, but it requires a broader utility-access key than the baseline read tier and is not the default starting point for new integrations.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - $ref: "#/components/parameters/RequestIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddressSummaryBatchRequest"
      responses:
        "200":
          description: Ordered address summary results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressSummaryBatchView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: contract-fixture
      x-starkscan-evidence-level: smoke
      x-starkscan-certification-scope: utility-batch
      x-starkscan-slo-class: batch
      x-starkscan-stability: stable
      x-starkscan-surface-tier: advanced-utility
      x-starkscan-key-tier: utility
      tags:
        - Utilities
  /v1/{chain}/address/intelligence:
    post:
      summary: Batch address deployment, attribution, and inbound-funds intelligence
      description: |-
        Utility-tier batch helper for wallet, paymaster, migration, and compliance-adjacent clients that need factual classification for a bounded list of up to 128 addresses. The route returns whether each address has indexed deployment evidence, optional readable attribution, and whether indexed token-transfer rows show the address as a recipient. It is backed by read-model indexes only; it does not call RPC on the request path and does not perform risk scoring or sanctions screening.

        Advanced utility route. This helper is externally supported, but it requires a broader utility-access key than the baseline read tier and is not the default starting point for new integrations.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - $ref: "#/components/parameters/RequestIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddressSummaryBatchRequest"
      responses:
        "200":
          description: Ordered address intelligence results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressIntelligenceBatchView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: contract-fixture
      x-starkscan-evidence-level: smoke
      x-starkscan-certification-scope: utility-batch
      x-starkscan-slo-class: batch
      x-starkscan-stability: stable
      x-starkscan-surface-tier: advanced-utility
      x-starkscan-key-tier: utility
      tags:
        - Utilities
  /v1/{chain}/query/wallet-paymaster-view:
    post:
      summary: Wallet/paymaster query bundle
      description: Partner Query Plane bundle for wallet and paymaster backends. The first slice returns bounded, request-ordered address identity, account state, and proof-backed L1 finality metadata for up to 32 unique addresses. It is backed by indexed read-model facts only and does not call RPC or scan raw activity on the request path. Token holdings, recent transactions, bridge/message rollups, and row-level provenance details are reserved for forward-compatible request shapes; when enabled in v1 they fail closed with `unsupported_section` instead of returning partial success.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - $ref: "#/components/parameters/RequestIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WalletPaymasterViewRequest"
      responses:
        "200":
          description: Wallet/paymaster bundle envelope
          headers:
            X-Starkscan-Route-Class:
              description: Route budget class for class-specific backoff.
              schema:
                type: string
                enum:
                  - batch
            X-Starkscan-Query-Class:
              description: Query Plane bundle class used for accounting and support.
              schema:
                type: string
                enum:
                  - wallet_paymaster
            X-Starkscan-Cost-Units:
              description: |
                Cost units charged for this Query Plane request. Wallet/paymaster formula: 2 base units + 1 unit per requested address + 1 unit per 8 addresses when `accountState` is enabled + 1 unit when `finality` is enabled. Forward-compatible unsupported sections have reserved costs and fail closed in v1.
              schema:
                type: integer
                format: int64
            x-ratelimit-limit:
              schema:
                type: integer
                format: int64
            x-ratelimit-remaining:
              schema:
                type: integer
                format: int64
            x-ratelimit-policy:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WalletPaymasterQueryEnvelope"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: query-plane-partner-bundles
      x-starkscan-slo-class: batch
      x-starkscan-stability: stable
      x-starkscan-surface-tier: partner
      x-starkscan-key-tier: partner
      tags:
        - Reference
  /v1/{chain}/query/defi-lending-market-view:
    post:
      summary: DeFi lending market query bundle
      description: Partner Query Plane bundle for Vesu-style lending markets, DeFi frontends, risk monitors, and liquidation services. The first slice returns request-ordered market selectors, bounded indexed contract identity, token address echoes, proof-backed L1 finality metadata, and simulation boundary metadata. It is backed by indexed read-model facts only and does not call RPC, scan events, compute risk, or read signed payloads on the request path. State samples, events, recent transactions, and row-level provenance details are reserved for forward-compatible request shapes; when enabled in v1 they fail closed with `unsupported_section`.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - $ref: "#/components/parameters/RequestIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DefiLendingMarketViewRequest"
      responses:
        "200":
          description: DeFi lending market bundle envelope
          headers:
            X-Starkscan-Route-Class:
              description: Route budget class for class-specific backoff.
              schema:
                type: string
                enum:
                  - batch
            X-Starkscan-Query-Class:
              description: Query Plane bundle class used for accounting and support.
              schema:
                type: string
                enum:
                  - defi_lending
            X-Starkscan-Cost-Units:
              description: |
                Cost units charged for this Query Plane request. DeFi lending formula: 5 base units + 3 units per requested market + 1 unit per 16 requested contracts when `contractIdentity` is enabled + 1 unit per requested market when `simulationMetadata` is enabled.
              schema:
                type: integer
                format: int64
            x-ratelimit-limit:
              schema:
                type: integer
                format: int64
            x-ratelimit-remaining:
              schema:
                type: integer
                format: int64
            x-ratelimit-policy:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefiLendingMarketQueryEnvelope"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: query-plane-partner-bundles
      x-starkscan-slo-class: batch
      x-starkscan-stability: stable
      x-starkscan-surface-tier: partner
      x-starkscan-key-tier: partner
      tags:
        - Reference
  /v1/{chain}/query/support-proof-bundle:
    post:
      summary: Support/proof query bundle
      description: Partner Query Plane bundle for support, bridge/message debugging, and customer-success proof packets. The v1 slice accepts exactly one incident selector (`txHash` or `messageHash`) and returns bounded indexed transaction detail, protocol-message lifecycle rows, StarkGate transfer resolution, and proof-backed L1 finality metadata. It is backed by indexed read-model facts only and does not call RPC, Ethereum RPC, or provider comparison endpoints on the request path. Row-level provenance details and shareable redacted proof links are reserved for forward-compatible request shapes; when enabled in v1 they fail closed with `unsupported_section`.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - $ref: "#/components/parameters/RequestIdHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SupportProofBundleRequest"
      responses:
        "200":
          description: Support/proof bundle envelope
          headers:
            X-Starkscan-Route-Class:
              description: Route budget class for class-specific backoff.
              schema:
                type: string
                enum:
                  - batch
            X-Starkscan-Query-Class:
              description: Query Plane bundle class used for accounting and support.
              schema:
                type: string
                enum:
                  - support_proof
            X-Starkscan-Cost-Units:
              description: |
                Cost units charged for this Query Plane request. Support/proof formula: 8 base units + 4 units each for requested `transaction`, `protocolMessages`, and `starkgate` sections + 1 unit when `finality` is enabled.
              schema:
                type: integer
                format: int64
            x-ratelimit-limit:
              schema:
                type: integer
                format: int64
            x-ratelimit-remaining:
              schema:
                type: integer
                format: int64
            x-ratelimit-policy:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SupportProofBundleEnvelope"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: query-plane-partner-bundles
      x-starkscan-slo-class: batch
      x-starkscan-stability: stable
      x-starkscan-surface-tier: partner
      x-starkscan-key-tier: partner
      tags:
        - Reference
  /v1/{chain}/address/{address}/transactions:
    get:
      summary: Paginated transaction summaries touching one address
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: Optional cursor encoded as `block:tx:log:transfer[:kind[:txHash[:source]]]`.
          schema:
            type: string
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Address transaction page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressTransactionPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Addresses
  /v1/{chain}/address/{address}/token-holdings:
    get:
      summary: Indexed token holdings for one owner address
      description: Wallet-first indexed holdings snapshot. Use `completeness` to decide whether the response is complete enough for portfolio parity checks. Use `GET /v1/{chain}/token/{token}/balance-of/{address}` for an exact spot read when the token contract is already known.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Address token holdings snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressTokenHoldingsView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Addresses
  /v1/{chain}/contract/{address}:
    get:
      summary: Indexed contract metadata
      description: Lightweight contract metadata for migration clients. The response is composed only from indexed read-model facts; nullable token fields mean the contract is not currently identified as token metadata in the index, not that it is provably not a token.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Indexed contract metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractMetadataView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Contracts
  /v1/{chain}/contract/{address}/verification:
    get:
      summary: Contract verification detail
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Contract verification record
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractVerificationView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Contract verification record not found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Contracts
  /v1/{chain}/contract/{address}/entrypoints:
    get:
      summary: Contract class entrypoints
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Contract entrypoint selectors grouped by type
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractEntrypointsView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Contract/class not found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Contracts
  /v1/{chain}/contract/{address}/events:
    get:
      summary: Paginated contract event logs
      description: Canonical paginated event/log surface for one contract. Use server-side topic and block filters before applying client-side protocol interpretation. Results are returned newest first in deterministic on-chain order (`blockNumber` DESC, `txIndex` DESC, `logIndex` DESC). Topic filters in this route are exact single-value matches (`topic0..topic3`), not OR-array combinations. The request `cursor` is exclusive and resumes after the last seen `(blockNumber, txIndex, logIndex)` tuple. Pass `nextCursor` from the previous response to continue without gaps or duplicates.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: topic0
          in: query
          description: Optional exact single-value match for the first log topic/event selector. Empty strings are invalid.
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: selector
          in: query
          description: Alias for `topic0` when filtering by Starknet event selector. Do not pass both `selector` and `topic0`.
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: topic1
          in: query
          description: Optional exact single-value match for the second log topic. Empty strings are invalid.
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: topic2
          in: query
          description: Optional exact single-value match for the third log topic. Empty strings are invalid.
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: topic3
          in: query
          description: Optional exact single-value match for the fourth log topic. Empty strings are invalid.
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: from_block
          in: query
          description: Optional inclusive lower block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: to_block
          in: query
          description: Optional inclusive upper block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: cursor
          in: query
          description: Optional cursor in `block:tx:log` numeric format.
          schema:
            type: string
            pattern: ^[0-9]+:[0-9]+:[0-9]+$
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Contract event page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractEventPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Contracts
  /v1/{chain}/contract/{address}/messages:
    get:
      summary: Paginated canonical messages for one contract
      description: Contract-scoped cross-layer message rows served only from indexed StarknetCore protocol message facts. Starkscan does not infer Messages rows from bridge adapter pairing facts, generic transactions, events, or token transfers. Coverage metadata is explicit because a data plane may still be backfilling protocol message facts.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: direction
          in: query
          description: Optional message direction filter.
          schema:
            type: string
            enum:
              - all
              - l1_to_l2
              - l2_to_l1
        - name: txHash
          in: query
          description: Optional transaction hash filter.
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: messageHash
          in: query
          description: Optional protocol message hash filter.
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: cursor
          in: query
          description: |
            Optional opaque cursor returned unchanged from `nextCursor`. New responses use `m1:block:tx:message:tx_hash:message_hash:direction:source_tier` so pagination remains stable when multiple messages share the same numeric tuple. Legacy `block:tx:message` cursors remain accepted for older clients.
          schema:
            type: string
            pattern: ^(m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)|[0-9]+:[0-9]+:[0-9]+)$
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Contract message page with explicit coverage metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MessagePage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: beta
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Contracts
  /v1/{chain}/contract/{address}/bridge-signals:
    get:
      summary: Paginated L2 bridge signal activity for one contract
      description: Returns low-latency bridge rows derived from indexed L2 token-transfer bridge signals, bridge registry matches, and bridge-asset mint/burn signals. This endpoint explicitly reports `coverage.status=partial` until L1 message pairing and cross-layer completion facts are indexed; clients must not treat these rows as complete L1/L2 lifecycle records.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        - name: cursor
          in: query
          description: Optional cursor in `block:tx:log:transfer` numeric format.
          schema:
            type: string
            pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Contract bridge signal page with explicit coverage metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractBridgeTransactionPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: beta
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Contracts
  /v1/{chain}/contract/{address}/read:
    get:
      summary: Read-only contract call
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: selector
          in: query
          required: true
          description: 0x-prefixed entrypoint selector felt
          schema:
            type: string
        - name: calldata
          in: query
          description: Optional felt/decimal calldata values (repeat key for multiple values).
          schema:
            type: array
            maxItems: 1024
            items:
              type: string
          style: form
          explode: true
        - name: block_tag
          in: query
          description: State reference used for call execution. Use `latest` or `pending` for live reads, or pass a block number/hash for deterministic correctness checks.
          schema:
            allOf:
              - $ref: "#/components/schemas/BlockReference"
            default: latest
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Read call result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractReadResultView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Contract or entrypoint not found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: live-rpc
      x-starkscan-evidence-level: smoke
      x-starkscan-certification-scope: provider-rpc
      x-starkscan-slo-class: cold
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Contracts
  /v1/{chain}/address/{address}/activity:
    get:
      summary: Paginated address activity
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: |
            Optional opaque cursor returned unchanged from `nextCursor`. New responses use `block:tx:log:transfer:kind:txHash[:source]` so pagination remains stable when multiple activity rows share the same numeric tuple. Legacy `block:tx:log:transfer` cursors remain accepted for older clients.
          schema:
            type: string
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Address activity page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressActivityPage"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Addresses
  /v1/{chain}/address/{address}/transfers:
    get:
      summary: Paginated token transfers touching one address
      description: Address-scoped transfer history backed by the indexed global transfer table. Direction, token, block, cursor, and limit filters are applied before pagination. `any` returns transfers where the address is either sender or recipient; self-transfers are returned once. `in` returns recipient-side rows and `out` returns sender-side rows, so a self-transfer appears in both directional views.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: path
          required: true
          schema:
            type: string
        - name: direction
          in: query
          description: |
            Optional direction relative to the path address: `any`, `in`, or `out`.
          schema:
            type: string
            enum:
              - any
              - in
              - out
            default: any
        - name: token
          in: query
          description: Optional repeated token-address filter.
          schema:
            type: array
            maxItems: 128
            items:
              type: string
              pattern: ^0[xX][0-9a-fA-F]{1,64}$
          style: form
          explode: true
        - name: from_block
          in: query
          description: Optional inclusive lower block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: to_block
          in: query
          description: Optional inclusive upper block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: cursor
          in: query
          description: Optional cursor in `block:tx:log:transfer` numeric format.
          schema:
            type: string
            pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Address transfer page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GlobalTransferPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Addresses
  /v1/{chain}/token/{token}:
    get:
      summary: Token aggregate summary
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: token
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Token summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenSummaryView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Token not found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Tokens
  /v1/{chain}/token/{token}/total-supply:
    get:
      summary: Standard-token totalSupply read
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: token
          in: path
          required: true
          schema:
            type: string
          example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d"
        - name: block_tag
          in: query
          description: State reference used for call execution. Use `latest` or `pending` for live reads, or pass a block number/hash for deterministic correctness checks.
          schema:
            allOf:
              - $ref: "#/components/schemas/BlockReference"
            default: latest
          example: latest
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Standard-token totalSupply result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenTotalSupplyView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Contract does not expose a supported totalSupply selector
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: certified
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: exact-block
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Tokens
  /v1/{chain}/token/{token}/balance-of/{address}:
    get:
      summary: Standard-token balanceOf read
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: token
          in: path
          required: true
          schema:
            type: string
          example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d"
        - name: address
          in: path
          required: true
          schema:
            type: string
          example: "0x00ca1702e64c81d9a07b86bd2c540188d92a2c73cf5cc0e508d949015e7e84a7"
        - name: block_tag
          in: query
          description: State reference used for call execution. Use `latest` or `pending` for live reads, or pass a block number/hash for deterministic correctness checks.
          schema:
            allOf:
              - $ref: "#/components/schemas/BlockReference"
            default: latest
          example: latest
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Standard-token balanceOf result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenBalanceOfView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Contract does not expose a supported balanceOf selector
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: certified
      x-starkscan-oracle: rpc-sampled
      x-starkscan-evidence-level: deploy-blocking
      x-starkscan-certification-scope: exact-block
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Tokens
  /v1/{chain}/token/{token}/holders:
    get:
      summary: Paginated token holders with indexed balances
      description: |-
        Partner-tier endpoint for token-contract-first holder analytics. Results are served from materialized fungible-balance snapshots, not transfer-history scans.

        Partner-tier route backed by materialized serving tables. It is intended for bounded indexed reads and must not run request-time scans or repairs.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: token
          in: path
          required: true
          schema:
            type: string
        - name: cursor
          in: query
          description: Optional opaque cursor returned unchanged from `nextCursor` in the previous response.
          schema:
            type: string
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Token holder page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenHolderPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Token contract not found or not recognized as a fungible token.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: materialized-db-plus-rpc
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: partner
      x-starkscan-key-tier: partner
      tags:
        - Tokens
  /v1/{chain}/token/{token}/holders/analytics:
    get:
      summary: Cached token holder concentration analytics
      description: |-
        Returns the latest operator-materialized holder concentration snapshot; the request path does not compute holder analytics.

        Partner-tier route backed by materialized serving tables. It is intended for bounded indexed reads and must not run request-time scans or repairs.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: token
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Token holder analytics snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenHolderAnalyticsSnapshot"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Token contract not found or not recognized as a fungible token.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: materialized-db-plus-rpc
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: partner
      x-starkscan-key-tier: partner
      tags:
        - Tokens
  /v1/{chain}/token/{token}/controls:
    get:
      summary: Indexed token control facts
      description: Returns the latest operator-materialized token control snapshot. Results are served from `token_controls_snapshot`; the request path does not run live RPC, public explorer calls, request-time ABI probes, or Account Calls.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: token
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Token controls snapshot or a typed not-indexed response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenControlsView"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Token contract not found or not recognized as a fungible token.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: materialized-db-plus-rpc
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Tokens
  /v1/{chain}/token/{token}/markets/pools:
    get:
      summary: Materialized token DEX pool facts
      description: |-
        Partner-tier endpoint for token-contract-first pool facts. Rows are served from `token_market_pool_snapshot`; token-level totals are served from the materialized rollup and are not recomputed on request. The route never performs request-time DEX, RPC, transfer, or Account Calls probes.

        Partner-tier route backed by materialized serving tables. It is intended for bounded indexed reads and must not run request-time scans or repairs.
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: token
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Token market pool page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenMarketPoolPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "404":
          description: Token contract not found or not recognized as a fungible token.
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: materialized-db-plus-rpc
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Tokens
  /v1/{chain}/token/{token}/transfers:
    get:
      summary: Paginated token transfers with optional address and block filters
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: token
          in: path
          required: true
          schema:
            type: string
        - name: address
          in: query
          description: Optional repeated wallet/address filter; matches transfers where either side is in the supplied set.
          schema:
            type: array
            maxItems: 128
            items:
              type: string
          style: form
          explode: true
        - name: from_block
          in: query
          description: Optional inclusive lower block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: to_block
          in: query
          description: Optional inclusive upper block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: cursor
          in: query
          description: Optional cursor in `block:tx:log:transfer` numeric format.
          schema:
            type: string
            pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Token transfer page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenTransferPage"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Tokens
  /v1/{chain}/events:
    get:
      summary: Paginated raw events with optional address, topic0, and block filters
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: query
          description: Optional repeated contract/address filter.
          schema:
            type: array
            maxItems: 128
            items:
              type: string
          style: form
          explode: true
        - name: contract
          in: query
          description: Alias for repeated `address` filters, matching Voyager-style `/events?contract=...` clients. `address`, `contract`, and `contractAddress` share one 128-item filter budget before duplicate-equivalent values are removed.
          schema:
            type: array
            maxItems: 128
            items:
              type: string
          style: form
          explode: true
        - name: contractAddress
          in: query
          description: Alias for repeated `address` filters. `address`, `contract`, and `contractAddress` share one 128-item filter budget before duplicate-equivalent values are removed.
          schema:
            type: array
            maxItems: 128
            items:
              type: string
          style: form
          explode: true
        - name: topic0
          in: query
          description: Optional repeated event-selector filter.
          schema:
            type: array
            maxItems: 128
            items:
              type: string
          style: form
          explode: true
        - name: selector
          in: query
          description: Alias for repeated `topic0` event-selector filters. Do not use `key`, `keys`, or `topic1..topic3` on the global route; use `/contract/{address}/events` for exact later-topic slot filters.
          schema:
            type: array
            maxItems: 128
            items:
              type: string
          style: form
          explode: true
        - name: from_block
          in: query
          description: Optional inclusive lower block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: to_block
          in: query
          description: Optional inclusive upper block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: cursor
          in: query
          description: Optional cursor in `block:tx:log` numeric format.
          schema:
            type: string
            pattern: ^[0-9]+:[0-9]+:[0-9]+$
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Global raw event page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GlobalEventPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Reference
  /v1/{chain}/transfers:
    get:
      summary: Paginated normalized transfers with optional address, token, and block filters
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: address
          in: query
          description: Optional repeated wallet/address filter; matches transfers where either side is in the supplied set.
          schema:
            type: array
            maxItems: 128
            items:
              type: string
          style: form
          explode: true
        - name: token
          in: query
          description: Optional repeated token-address filter.
          schema:
            type: array
            maxItems: 128
            items:
              type: string
          style: form
          explode: true
        - name: direction
          in: query
          description: Optional direction relative to supplied address filters. Requires at least one `address` filter.
          schema:
            type: string
            enum:
              - any
              - in
              - out
            default: any
        - name: from_block
          in: query
          description: Optional inclusive lower block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: to_block
          in: query
          description: Optional inclusive upper block bound.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: cursor
          in: query
          description: Optional cursor in `block:tx:log:transfer` numeric format.
          schema:
            type: string
            pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$
        - name: limit
          in: query
          description: Page size (clamped to 1..100).
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Global transfer page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GlobalTransferPage"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Reference
  /v1/me/api-keys:
    get:
      summary: List self-serve API keys for the authenticated workspace
      description: Returns metadata for the current workspace's self-serve Starkscan API keys. Secrets are never returned by this route. Hosted browser sessions may authenticate this safe read with Better Auth cookies or an explicit bearer session token.
      security:
        - SelfServeSession: []
        - SelfServeSessionCookie: []
        - SelfServeSessionCookieSecure: []
      responses:
        "200":
          description: Self-serve API key list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SelfServeApiKeyListResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedSelfServeSession"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: contract-fixture
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: session-control
      x-starkscan-slo-class: warm
      x-starkscan-stability: stable
      x-starkscan-surface-tier: self-serve
      x-starkscan-key-tier: session
      parameters:
        - $ref: "#/components/parameters/RequestIdHeader"
      tags:
        - Account
    post:
      summary: Issue or rotate the default self-serve API key for the authenticated workspace
      description: "Issues a live read-only API key for the current workspace. If an active default key already exists, the old key is revoked and replaced in the same operation. This mutating route requires `Authorization: Bearer <better_auth_session_token>` and rejects cookie-only calls."
      security:
        - SelfServeSession: []
      responses:
        "200":
          description: Issued self-serve API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SelfServeIssueApiKeyResult"
        "401":
          $ref: "#/components/responses/UnauthorizedSelfServeSession"
        "403":
          $ref: "#/components/responses/ForbiddenSelfServeMutation"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: contract-fixture
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: session-control
      x-starkscan-slo-class: warm
      x-starkscan-stability: stable
      x-starkscan-surface-tier: self-serve
      x-starkscan-key-tier: session
      parameters:
        - $ref: "#/components/parameters/RequestIdHeader"
      tags:
        - Account
  /v1/me/api-keys/{public_id}:
    delete:
      summary: Revoke one self-serve API key for the authenticated workspace
      description: "Revokes the selected self-serve API key and returns its final metadata snapshot. This mutating route requires `Authorization: Bearer <better_auth_session_token>` and rejects cookie-only calls."
      security:
        - SelfServeSession: []
      parameters:
        - name: public_id
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Revoked self-serve API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SelfServeApiKeyDeleteResponse"
        "401":
          $ref: "#/components/responses/UnauthorizedSelfServeSession"
        "403":
          $ref: "#/components/responses/ForbiddenSelfServeMutation"
        "404":
          description: Self-serve API key not found
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: contract-fixture
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: session-control
      x-starkscan-slo-class: warm
      x-starkscan-stability: stable
      x-starkscan-surface-tier: self-serve
      x-starkscan-key-tier: session
      tags:
        - Account
  /v1/me/usage:
    get:
      summary: Load recent self-serve API usage for the authenticated workspace
      description: Returns a recent usage window, per-key aggregates, recent requests, and recent failures for the current self-serve workspace. Hosted browser sessions may authenticate this safe read with Better Auth cookies or an explicit bearer session token.
      security:
        - SelfServeSession: []
        - SelfServeSessionCookie: []
        - SelfServeSessionCookieSecure: []
      responses:
        "200":
          description: Self-serve usage snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SelfServeUsageSnapshot"
        "401":
          $ref: "#/components/responses/UnauthorizedSelfServeSession"
        "429":
          $ref: "#/components/responses/RateLimited"
        "503":
          $ref: "#/components/responses/ServiceUnavailable"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: contract-fixture
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: session-control
      x-starkscan-slo-class: warm
      x-starkscan-stability: stable
      x-starkscan-surface-tier: self-serve
      x-starkscan-key-tier: session
      parameters:
        - $ref: "#/components/parameters/RequestIdHeader"
      tags:
        - Account
  /v1/{chain}/search:
    get:
      summary: Universal search
      security:
        - StarkscanApiKey: []
      parameters:
        - $ref: "#/components/parameters/ChainParam"
        - name: q
          in: query
          description: |
            Optional prefix query. Missing or empty values return an empty result set. Exact hash/address-style queries resolve first match in this order: transaction hash -> address -> block hash (single category returned). Prefix address matching reads address-activity tables only; addresses that appear exclusively in token-transfer activity remain accessible via `/v1/{chain}/address/{address}` but are not returned by `/search`.
          schema:
            type: string
        - $ref: "#/components/parameters/RequestIdHeader"
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchView"
        "401":
          $ref: "#/components/responses/UnauthorizedText"
        "403":
          $ref: "#/components/responses/ForbiddenText"
        "429":
          $ref: "#/components/responses/RateLimited"
      x-starkscan-audience: public-core
      x-starkscan-certification: beta
      x-starkscan-oracle: indexed-replay
      x-starkscan-evidence-level: heavy
      x-starkscan-certification-scope: derived-indexed
      x-starkscan-slo-class: hot
      x-starkscan-stability: stable
      x-starkscan-surface-tier: official-public-api
      x-starkscan-key-tier: read
      tags:
        - Search
components:
  securitySchemes:
    StarkscanApiKey:
      type: apiKey
      in: header
      name: X-Starkscan-Api-Key
      description: External Starkscan API key header. Required access tier and scope are defined per operation.
    SelfServeSession:
      type: http
      scheme: bearer
      bearerFormat: Better Auth session token
      description: Session token for authenticated self-serve workspace routes. Hosted browser safe reads can also use Better Auth session cookies, but mutating /v1/me/* routes require an explicit bearer token.
    SelfServeSessionCookie:
      type: apiKey
      in: cookie
      name: better-auth.session_token
      description: Better Auth session cookie accepted for hosted same-origin safe reads on /v1/me/*.
    SelfServeSessionCookieSecure:
      type: apiKey
      in: cookie
      name: __Secure-better-auth.session_token
      description: Secure Better Auth session cookie accepted for hosted same-origin safe reads on /v1/me/*.
  parameters:
    ChainParam:
      name: chain
      in: path
      required: true
      schema:
        type: string
      example: SN_MAIN
    RequestIdHeader:
      name: X-Request-Id
      in: header
      required: false
      description: Optional caller-supplied correlation ID echoed back in the response.
      schema:
        type: string
  responses:
    UnauthorizedText:
      description: Missing or invalid Starkscan credential.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
        WWW-Authenticate:
          $ref: "#/components/headers/WwwAuthenticate"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    UnauthorizedSelfServeSession:
      description: Missing, invalid, or expired self-serve session.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
        WWW-Authenticate:
          $ref: "#/components/headers/WwwAuthenticate"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimited:
      description: Rate limit hit for the current route class.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
        X-Starkscan-Route-Class:
          $ref: "#/components/headers/StarkscanRouteClass"
        x-ratelimit-limit:
          $ref: "#/components/headers/RateLimitLimit"
        x-ratelimit-remaining:
          $ref: "#/components/headers/RateLimitRemaining"
        x-ratelimit-policy:
          $ref: "#/components/headers/RateLimitPolicy"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ServiceUnavailable:
      description: The route is temporarily unavailable.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
        Retry-After:
          $ref: "#/components/headers/RetryAfter"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    BadRequest:
      description: Invalid request shape, path parameter, query parameter, or body.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ForbiddenText:
      description: Valid Starkscan credential lacks the required scope.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
        WWW-Authenticate:
          $ref: "#/components/headers/WwwAuthenticate"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    ForbiddenSelfServeMutation:
      description: Cookie-authenticated mutations are not allowed on self-serve routes.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
        WWW-Authenticate:
          $ref: "#/components/headers/WwwAuthenticate"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    NotFound:
      description: The requested route or resource was not found.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Conflict:
      description: The request conflicts with the current resource state.
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
  schemas:
    BlockReference:
      oneOf:
        - type: string
          enum:
            - latest
            - pending
        - type: string
          pattern: ^[0-9]+$
          maxLength: 19
          description: Decimal block number. Must be non-negative and fit in signed 64-bit range.
        - type: string
          pattern: ^0[xX][0-9a-fA-F]{1,128}$
          maxLength: 130
          description: 0x-prefixed Starknet block hash/felt.
      description: State reference. Block hashes are validated against the Starknet field range; decimal block numbers must be non-negative signed 64-bit values.
    ErrorResponse:
      type: object
      description: |
        Machine-readable error envelope. JSON error responses also emit `X-Request-Id` as the canonical correlation header when the request has one; `requestId` mirrors it when available inside the handler.
      additionalProperties: false
      required:
        - code
        - message
        - docSlug
        - requestId
      properties:
        code:
          type: string
          enum:
            - invalid_request
            - unauthorized
            - forbidden
            - not_found
            - conflict
            - rate_limited
            - service_unavailable
            - internal_error
            - api_error
        message:
          type: string
        docSlug:
          type: string
          description: Stable docs slug agents can use for next-step guidance.
        requestId:
          type:
            - string
            - "null"
          description: Mirrors `X-Request-Id` when available inside the handler; the response header is canonical.
    JsonRpcRequest:
      type: object
      description: Starknet JSON-RPC 2.0 request object accepted by the gateway.
      required:
        - jsonrpc
        - method
      additionalProperties: true
      properties:
        jsonrpc:
          type: string
          enum:
            - "2.0"
        method:
          type: string
        params:
          oneOf:
            - type: array
              items: {}
            - type: object
              additionalProperties: true
            - type: "null"
        id:
          oneOf:
            - type: string
            - type: integer
            - type: "null"
    JsonRpcBatchRequest:
      type: array
      description: JSON-RPC batch request accepted by the gateway pilot.
      minItems: 1
      maxItems: 25
      items:
        $ref: "#/components/schemas/JsonRpcRequest"
    JsonRpcError:
      type: object
      additionalProperties: true
      required:
        - code
        - message
      properties:
        code:
          type: integer
        message:
          type: string
        data:
          description: Optional JSON-RPC error data payload; may be any JSON value.
    JsonRpcResponse:
      type: object
      description: Starknet JSON-RPC 2.0 result or error envelope.
      required:
        - jsonrpc
        - id
      oneOf:
        - required:
            - result
          not:
            required:
              - error
        - required:
            - error
          not:
            required:
              - result
      additionalProperties: true
      properties:
        jsonrpc:
          type: string
          enum:
            - "2.0"
        id:
          oneOf:
            - type: string
            - type: integer
            - type: "null"
        result: {}
        error:
          $ref: "#/components/schemas/JsonRpcError"
    JsonRpcBatchResponse:
      type: array
      description: JSON-RPC batch response from the gateway.
      maxItems: 25
      items:
        $ref: "#/components/schemas/JsonRpcResponse"
    AgentMemoryContract:
      type: object
      additionalProperties: true
      required:
        - kind
        - schemaVersion
        - generatedFor
        - auth
        - firstCalls
        - routeFamilies
        - workspaceMemory
        - operatingRules
        - issueReportContract
      properties:
        kind:
          type: string
          enum:
            - starkscan.agent_memory
        schemaVersion:
          type: string
          example: 2026-05-02
        generatedFor:
          type: string
          enum:
            - agents
        auth:
          type: object
          additionalProperties: true
          required:
            - header
            - externalBasePath
            - defaultChain
          properties:
            header:
              type: string
              example: X-Starkscan-Api-Key
            externalBasePath:
              type: string
              example: /v1
            defaultChain:
              type: string
              example: SN_MAIN
        firstCalls:
          type: array
          items:
            $ref: "#/components/schemas/AgentFirstCall"
        routeFamilies:
          type: array
          items:
            $ref: "#/components/schemas/AgentRouteFamily"
        workspaceMemory:
          $ref: "#/components/schemas/AgentWorkspaceMemoryContract"
        operatingRules:
          type: array
          items:
            type: string
        issueReportContract:
          $ref: "#/components/schemas/AgentIssueReportContract"
    AgentFirstCall:
      type: object
      additionalProperties: true
      required:
        - method
        - path
        - purpose
      properties:
        method:
          type: string
          example: GET
        path:
          type: string
          example: /v1/meta/capabilities
        purpose:
          type: string
    AgentRouteFamily:
      type: object
      additionalProperties: true
      required:
        - name
        - tier
        - routes
        - useWhen
      properties:
        name:
          type: string
        tier:
          type: string
          enum:
            - read
            - batch
        routes:
          type: array
          items:
            type: string
        useWhen:
          type: string
    MetaCapabilitiesView:
      type: object
      additionalProperties: true
      required:
        - kind
        - schemaVersion
        - defaultChain
        - authHeader
        - firstCalls
        - routeFamilies
        - rpcProvider
        - operatingRules
        - issueReportContract
      description: |
        Authenticated capability view for agents and developers.
      properties:
        kind:
          type: string
          enum:
            - starkscan.meta.capabilities
        schemaVersion:
          type: string
        defaultChain:
          type: string
        authHeader:
          type: string
          example: X-Starkscan-Api-Key
        firstCalls:
          type: array
          items:
            $ref: "#/components/schemas/AgentFirstCall"
        routeFamilies:
          type: array
          items:
            $ref: "#/components/schemas/AgentRouteFamily"
        rpcProvider:
          $ref: "#/components/schemas/RpcProviderCapability"
        operatingRules:
          type: array
          items:
            type: string
        issueReportContract:
          $ref: "#/components/schemas/AgentIssueReportContract"
    RpcProviderCapability:
      type: object
      additionalProperties: true
      required:
        - status
        - endpoint
        - endpointTemplate
        - authHeader
        - minimumSpecVersion
        - specVersionMethod
        - supportedBlockTags
        - batch
        - writeBeta
        - quotaClasses
        - unsupportedUntilCertified
      properties:
        status:
          type: string
          enum:
            - enrolled_http_beta
            - authenticated_http_beta
        endpoint:
          type: string
          example: /api/v1/SN_MAIN/rpc
        endpointTemplate:
          type: string
          example: /api/v1/{chain}/rpc
        authHeader:
          type: string
          example: X-Starkscan-Api-Key
        minimumSpecVersion:
          type: string
          example: 0.10.2
        specVersionMethod:
          type: string
          enum:
            - starknet_specVersion
        supportedBlockTags:
          type: array
          items:
            type: string
            enum:
              - latest
              - pending
              - pre_confirmed
        batch:
          type: object
          additionalProperties: false
          required:
            - supported
            - maxItems
            - accounting
          properties:
            supported:
              type: boolean
            maxItems:
              type: integer
              minimum: 1
              maximum: 25
            accounting:
              type: string
              enum:
                - Each JSON-RPC child request is classified and rate-limited independently.
        writeBeta:
          type: object
          additionalProperties: false
          required:
            - enabled
            - status
            - openToAllApiKeys
            - methods
            - payloadPolicy
            - quotaClass
          properties:
            enabled:
              type: boolean
            status:
              type: string
              enum:
                - enrolled_write_scoped_keys_only
                - disabled_until_operator_enabled
                - all_api_keys_signed_payloads_only
            openToAllApiKeys:
              type: boolean
            methods:
              type: array
              items:
                type: string
                enum:
                  - starknet_addInvokeTransaction
                  - starknet_addDeclareTransaction
                  - starknet_addDeployAccountTransaction
            payloadPolicy:
              type: string
            quotaClass:
              type: string
              enum:
                - rpc_write
        quotaClasses:
          type: object
          additionalProperties: false
          required:
            - rpc_read_light
            - rpc_read_state
            - rpc_read_history
            - rpc_simulation
            - rpc_write
          properties:
            rpc_read_light:
              type: array
              items:
                type: string
                enum:
                  - starknet_chainId
                  - starknet_specVersion
                  - starknet_blockNumber
                  - starknet_blockHashAndNumber
                  - starknet_syncing
            rpc_read_state:
              type: array
              items:
                type: string
                enum:
                  - starknet_call
                  - starknet_getStorageAt
                  - starknet_getClass
                  - starknet_getClassHashAt
                  - starknet_getClassAt
                  - starknet_getNonce
            rpc_read_history:
              type: array
              items:
                type: string
                enum:
                  - starknet_getBlockWithTxHashes
                  - starknet_getBlockWithTxs
                  - starknet_getBlockWithReceipts
                  - starknet_getBlockTransactionCount
                  - starknet_getTransactionByBlockIdAndIndex
                  - starknet_getTransactionByHash
                  - starknet_getTransactionReceipt
                  - starknet_getTransactionStatus
                  - starknet_getStateUpdate
                  - starknet_getEvents
            rpc_simulation:
              type: array
              items:
                type: string
                enum:
                  - starknet_simulateTransactions
                  - starknet_estimateFee
                  - starknet_estimateMessageFee
            rpc_write:
              type: array
              items:
                type: string
                enum:
                  - starknet_addInvokeTransaction
                  - starknet_addDeclareTransaction
                  - starknet_addDeployAccountTransaction
        unsupportedUntilCertified:
          type: array
          items:
            type: string
            enum:
              - websocket_subscriptions
              - trace_methods_except_simulateTransactions
              - archive_history_full_provider
              - no_key_public_rpc
    MetaChainsView:
      type: object
      additionalProperties: true
      required:
        - kind
        - schemaVersion
        - defaultChain
        - chains
      properties:
        kind:
          type: string
          enum:
            - starkscan.meta.chains
        schemaVersion:
          type: string
        defaultChain:
          type: string
        chains:
          type: array
          items:
            type: object
            additionalProperties: true
            required:
              - chainId
              - statusPath
              - statusPathTemplate
            properties:
              chainId:
                type: string
              statusPath:
                type: string
              statusPathTemplate:
                type: string
        selectionRule:
          type: string
    MetaAgentContextView:
      type: object
      additionalProperties: true
      required:
        - kind
        - schemaVersion
        - agentMemory
        - workspaceMemory
        - preferredArtifactFormat
      properties:
        kind:
          type: string
          enum:
            - starkscan.meta.agent_context
        schemaVersion:
          type: string
        agentMemory:
          $ref: "#/components/schemas/AgentMemoryContract"
        workspaceMemory:
          $ref: "#/components/schemas/AgentWorkspaceMemoryContract"
        preferredArtifactFormat:
          type: string
          example: application/jsonl
    AgentWorkspaceMemoryContract:
      type: object
      additionalProperties: false
      required:
        - status
        - publicWriteApi
        - serverStoredArtifacts
        - writeSurface
        - localWorkspace
        - handoffContract
      properties:
        status:
          type: string
          enum:
            - no_public_write_api
        publicWriteApi:
          type: boolean
          enum:
            - false
        serverStoredArtifacts:
          type: string
          example: not available in this deployment
        writeSurface:
          type: string
          example: not exposed in this deployment
        localWorkspace:
          $ref: "#/components/schemas/AgentLocalWorkspaceContract"
        handoffContract:
          $ref: "#/components/schemas/AgentHandoffContract"
        rules:
          type: array
          items:
            type: string
    AgentLocalWorkspaceContract:
      type: object
      additionalProperties: false
      required:
        - status
        - defaultDirectory
        - artifactPattern
        - schemaPath
        - schemaUrl
        - guideUrl
        - validatorCommand
        - sampleCommand
      properties:
        status:
          type: string
          enum:
            - internal_local_only
        defaultDirectory:
          type: string
          example: .codex/handoffs/
        artifactPattern:
          type: string
          example: .codex/handoffs/{taskId}.jsonl
        schemaPath:
          type: string
          example: docs/maintainers/schemas/agent-handoff-artifact.schema.json
        schemaUrl:
          type: string
          example: /agent-handoff-artifact.schema.json
        guideUrl:
          type: string
          example: /agent-workspace.md
        validatorCommand:
          type: string
          example: python3 scripts/ci/agent-handoff.py validate .codex/handoffs/{taskId}.jsonl
        sampleCommand:
          type: string
          example: python3 scripts/ci/agent-handoff.py sample --task-id <task-id> --created-by <agent>
    AgentHandoffContract:
      type: object
      additionalProperties: false
      required:
        - sourceOfTruth
        - artifactKinds
        - requiredFields
        - evidenceRule
        - formats
      properties:
        sourceOfTruth:
          type: string
          example: typed JSON/JSONL artifacts, not chat history
        artifactKinds:
          type: array
          items:
            type: string
        requiredFields:
          type: array
          items:
            type: string
        evidenceRule:
          type: string
        formats:
          type: array
          items:
            type: string
    AgentIssueReportContract:
      type: object
      additionalProperties: false
      required:
        - requiredFields
        - rule
      properties:
        requiredFields:
          type: array
          items:
            type: string
          example:
            - route
            - queryParams
            - requestBody
            - responseStatus
            - responseSnippet
            - xRequestId
        rule:
          type: string
    HealthResponse:
      type: object
      additionalProperties: false
      required:
        - ok
        - databaseOk
      properties:
        ok:
          type: boolean
        databaseOk:
          type: boolean
    ReadyzResponse:
      type: object
      additionalProperties: false
      required:
        - ready
        - databaseOk
      properties:
        ready:
          type: boolean
        databaseOk:
          type: boolean
    LivezResponse:
      type: object
      additionalProperties: false
      required:
        - alive
      properties:
        alive:
          type: boolean
    ExplorerStatusView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - headBlockNumber
        - headBlockHash
        - finalizedBlockNumber
        - latestL1AcceptedBlockNumber
        - l1AcceptedProof
        - l1Finality
        - latestIndexedBlockNumber
        - earliestIndexedBlockNumber
        - indexedBlockSpan
        - lagBlocks
        - l1SettlementLatencySeconds
      properties:
        chainId:
          type: string
        headBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        headBlockHash:
          type:
            - string
            - "null"
        finalizedBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        latestL1AcceptedBlockNumber:
          type:
            - integer
            - "null"
          format: int64
          description: Latest Starknet block number covered by explicit L1 accepted proof, separate from finalized indexed storage.
        l1AcceptedProof:
          anyOf:
            - $ref: "#/components/schemas/L1AcceptedProofView"
            - type: "null"
        l1Finality:
          $ref: "#/components/schemas/L1FinalityView"
        latestIndexedBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        earliestIndexedBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        indexedBlockSpan:
          type:
            - integer
            - "null"
          format: int64
        lagBlocks:
          type:
            - integer
            - "null"
          format: int64
        l1SettlementLatencySeconds:
          type:
            - integer
            - "null"
          format: int64
    L1FinalityView:
      type: object
      additionalProperties: false
      required:
        - watermarkBlockNumber
        - watermarkAgeSeconds
        - quorum
        - lastDivergenceAt
      properties:
        watermarkBlockNumber:
          type:
            - integer
            - "null"
          format: int64
          description: Starknet block number covered by the current proof-backed L1 accepted watermark.
        watermarkAgeSeconds:
          type:
            - integer
            - "null"
          format: int64
          description: Seconds since the served L1 accepted watermark proof was indexed.
        quorum:
          $ref: "#/components/schemas/L1FinalityQuorumView"
        lastDivergenceAt:
          type:
            - string
            - "null"
          format: date-time
          description: Most recent L1 RPC quorum divergence timestamp when exported by runtime monitoring; null when not reported on the request path.
    L1FinalityQuorumView:
      type: object
      additionalProperties: false
      required:
        - endpointsConfigured
        - endpointsHealthy
        - status
      properties:
        endpointsConfigured:
          type:
            - integer
            - "null"
          format: int64
        endpointsHealthy:
          type:
            - integer
            - "null"
          format: int64
        status:
          type: string
          enum:
            - not_reported
          description: Quorum health is not reported on the hot status request path yet; see L1 freshness deploy gates for current operational proof.
    L1AcceptedProofView:
      type: object
      additionalProperties: false
      required:
        - source
        - starknetBlockNumber
        - starknetBlockHash
        - starknetGlobalRoot
        - l1BlockNumber
        - l1BlockHash
        - l1TxHash
        - updatedAt
      properties:
        source:
          type: string
          enum:
            - ethereum_starknet_core_log_state_update
        starknetBlockNumber:
          type: integer
          format: int64
        starknetBlockHash:
          type: string
        starknetGlobalRoot:
          type: string
        l1BlockNumber:
          type: integer
          format: int64
        l1BlockHash:
          type:
            - string
            - "null"
        l1TxHash:
          type: string
        updatedAt:
          type: string
          format: date-time
    OAuthProtectedResourceMetadata:
      type: object
      additionalProperties: false
      required:
        - authorization_servers
        - resource
        - bearer_methods_supported
        - scopes_supported
      properties:
        authorization_servers:
          type: array
          items:
            type: string
        resource:
          type: string
        bearer_methods_supported:
          type: array
          items:
            type: string
        scopes_supported:
          type: array
          items:
            type: string
    ChainBlockListItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - blockHash
        - parentHash
        - timestampIso
        - txCount
        - finalityStatus
      properties:
        blockNumber:
          type: integer
          format: int64
        blockHash:
          type: string
        parentHash:
          type: string
        timestampIso:
          type: string
        txCount:
          type: integer
          format: int64
        finalityStatus:
          type: string
    ChainBlockListPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ChainBlockListItem"
        nextCursor:
          type:
            - string
            - "null"
    BlockAtTimestampQueryView:
      type: object
      additionalProperties: false
      required:
        - timestampIso
        - timestampUnix
        - closest
      properties:
        timestampIso:
          type: string
          format: date-time
        timestampUnix:
          type: integer
          format: int64
        closest:
          type: string
          enum:
            - before
            - after
    BlockAtTimestampBlockView:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - blockHash
        - timestampIso
        - timestampUnix
        - finalityStatus
      properties:
        blockNumber:
          type: integer
          format: int64
        blockHash:
          type: string
        timestampIso:
          type: string
          format: date-time
        timestampUnix:
          type: integer
          format: int64
        finalityStatus:
          type: string
    BlockAtTimestampView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - query
        - block
        - previousBlock
        - nextBlock
        - source
      properties:
        chainId:
          type: string
        query:
          $ref: "#/components/schemas/BlockAtTimestampQueryView"
        block:
          $ref: "#/components/schemas/BlockAtTimestampBlockView"
        previousBlock:
          oneOf:
            - $ref: "#/components/schemas/BlockAtTimestampBlockView"
            - type: "null"
          description: Always present; inclusive indexed lower bound at or before the requested timestamp, or null when unavailable.
        nextBlock:
          oneOf:
            - $ref: "#/components/schemas/BlockAtTimestampBlockView"
            - type: "null"
          description: Always present; inclusive indexed upper bound at or after the requested timestamp, or null when unavailable.
        source:
          type: string
          enum:
            - indexed_blocks
    ChainTransactionListItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - timestampIso
        - txHash
        - txIndex
        - txType
        - fromAddress
        - toAddress
        - executionStatus
        - finalityStatus
      properties:
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type: string
        txHash:
          type: string
        txIndex:
          type: integer
          format: int32
        txType:
          type: string
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        executionStatus:
          type:
            - string
            - "null"
        finalityStatus:
          type: string
    ChainTransactionListPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ChainTransactionListItem"
        nextCursor:
          type:
            - string
            - "null"
    BlockTransactionView:
      type: object
      additionalProperties: false
      required:
        - txHash
        - txIndex
        - txCursor
        - fromAddress
        - toAddress
        - executionStatus
        - finalityStatus
      properties:
        txHash:
          type: string
        txIndex:
          type: integer
          format: int32
        txCursor:
          type: string
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        executionStatus:
          type:
            - string
            - "null"
        finalityStatus:
          type:
            - string
            - "null"
    BlockGasPriceView:
      type: object
      additionalProperties: false
      required:
        - priceInWei
        - priceInFri
      properties:
        priceInWei:
          type:
            - string
            - "null"
        priceInFri:
          type:
            - string
            - "null"
    BlockView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - blockNumber
        - blockHash
        - parentHash
        - timestampIso
        - txCount
        - rawObjectKey
        - stateRoot
        - sequencerAddress
        - l1DataAvailabilityMode
        - starknetVersion
        - l1GasPrice
        - l2GasPrice
        - l1DataGasPrice
        - transactions
      properties:
        chainId:
          type: string
        blockNumber:
          type: integer
          format: int64
        blockHash:
          type: string
        parentHash:
          type: string
        timestampIso:
          type: string
        txCount:
          type: integer
          format: int64
        rawObjectKey:
          type: string
        stateRoot:
          type:
            - string
            - "null"
          description: Canonical Starknet block state root when indexed from the raw block payload.
        sequencerAddress:
          type:
            - string
            - "null"
          description: Sequencer address reported by the Starknet block header when available.
        l1DataAvailabilityMode:
          type:
            - string
            - "null"
          description: L1 data availability mode reported by the Starknet block header when available.
        starknetVersion:
          type:
            - string
            - "null"
          description: Starknet protocol version reported by the block header when available.
        l1GasPrice:
          anyOf:
            - $ref: "#/components/schemas/BlockGasPriceView"
            - type: "null"
        l2GasPrice:
          anyOf:
            - $ref: "#/components/schemas/BlockGasPriceView"
            - type: "null"
        l1DataGasPrice:
          anyOf:
            - $ref: "#/components/schemas/BlockGasPriceView"
            - type: "null"
        transactions:
          type: array
          maxItems: 200
          items:
            $ref: "#/components/schemas/BlockTransactionView"
    BlockTransactionPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/BlockTransactionView"
        nextCursor:
          type:
            - string
            - "null"
    ExplorerLiveFeedSnapshot:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - emittedAtIso
        - status
        - blocks
      properties:
        schemaVersion:
          type: integer
          format: int32
        emittedAtIso:
          type: string
        status:
          $ref: "#/components/schemas/ExplorerStatusView"
        blocks:
          type: array
          maxItems: 25
          items:
            $ref: "#/components/schemas/BlockView"
    TransactionReceiptView:
      type: object
      additionalProperties: false
      required:
        - executionStatus
        - finalityStatus
        - gasUsed
        - effectiveGasPrice
        - revertReason
      properties:
        executionStatus:
          type:
            - string
            - "null"
        finalityStatus:
          type:
            - string
            - "null"
        gasUsed:
          type:
            - string
            - "null"
        effectiveGasPrice:
          type:
            - string
            - "null"
        revertReason:
          type:
            - string
            - "null"
    TransactionLogView:
      type: object
      additionalProperties: false
      required:
        - logIndex
        - address
        - topic0
        - topic1
        - topic2
        - topic3
        - data
      properties:
        logIndex:
          type: integer
          format: int32
        address:
          type: string
        topic0:
          type:
            - string
            - "null"
        topic1:
          type:
            - string
            - "null"
        topic2:
          type:
            - string
            - "null"
        topic3:
          type:
            - string
            - "null"
        data:
          type: array
          maxItems: 1024
          items:
            type: string
    TransactionTransferView:
      type: object
      additionalProperties: false
      required:
        - logIndex
        - transferIndex
        - tokenAddress
        - fromAddress
        - toAddress
        - amount
        - tokenId
        - standard
        - historicalUsd
      properties:
        logIndex:
          type: integer
          format: int32
        transferIndex:
          type: integer
          format: int32
        tokenAddress:
          type: string
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        amount:
          type:
            - string
            - "null"
        tokenId:
          type:
            - string
            - "null"
        standard:
          type: string
        historicalUsd:
          description: Indexed transaction-time USD valuation when materialized; null when no priced historical fact is available. Do not treat this as a live/current market price.
          oneOf:
            - $ref: "#/components/schemas/TokenTransferHistoricalUsd"
            - type: "null"
    TokenTransferHistoricalUsd:
      type: object
      description: Row-backed historical USD valuation for one transfer, computed from the transfer amount and the token price at `priceHourIso`.
      additionalProperties: false
      required:
        - amountDecimal
        - priceUsd
        - valueUsd
        - priceHourIso
        - priceSource
        - provider
        - providerAssetId
        - quoteCurrency
        - coverageStatus
        - coverageReasonCode
        - indexedAt
      properties:
        amountDecimal:
          type:
            - string
            - "null"
        priceUsd:
          description: Token unit price in USD for `priceHourIso`, not current spot price.
          type:
            - string
            - "null"
        valueUsd:
          description: Transfer USD value at `priceHourIso`, not current spot value.
          type:
            - string
            - "null"
        priceHourIso:
          type:
            - string
            - "null"
          format: date-time
        priceSource:
          type:
            - string
            - "null"
        provider:
          type:
            - string
            - "null"
        providerAssetId:
          type:
            - string
            - "null"
        quoteCurrency:
          type: string
        coverageStatus:
          type: string
          enum:
            - priced
            - unpriced
        coverageReasonCode:
          type: string
          enum:
            - priced
            - token_unmapped
            - metadata_missing
            - non_fungible
            - amount_missing
            - price_missing
            - provider_granularity_daily
        indexedAt:
          type:
            - string
            - "null"
          format: date-time
    BridgeIntentKind:
      type: string
      enum:
        - deposit
        - withdraw
        - bridge_unknown
    BridgeIntentConfidence:
      type: string
      description: |
        Confidence for emitted bridge intents. Low-confidence candidates are intentionally omitted from `bridgeIntent`.
      enum:
        - high
        - medium
    BridgeIntentView:
      type: object
      additionalProperties: false
      required:
        - kind
        - protocol
        - confidence
        - reasons
      properties:
        kind:
          $ref: "#/components/schemas/BridgeIntentKind"
        protocol:
          type:
            - string
            - "null"
        confidence:
          $ref: "#/components/schemas/BridgeIntentConfidence"
        reasons:
          type: array
          maxItems: 32
          items:
            type: string
    TransactionPreviewLogView:
      type: object
      additionalProperties: false
      required:
        - logIndex
        - address
        - topic0
      properties:
        logIndex:
          type: integer
          format: int32
        address:
          type: string
        topic0:
          type:
            - string
            - "null"
    TransactionPreviewView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - blockNumber
        - txIndex
        - txHash
        - txCursor
        - fromAddress
        - toAddress
        - executionStatus
        - finalityStatus
        - txType
        - transferCount
        - tokenTransfersTruncated
        - tokenTransfers
      properties:
        chainId:
          type: string
        blockNumber:
          type: integer
          format: int64
        txIndex:
          type: integer
          format: int32
        txHash:
          type: string
        txCursor:
          type: string
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        executionStatus:
          type:
            - string
            - "null"
        finalityStatus:
          type:
            - string
            - "null"
        txType:
          type:
            - string
            - "null"
        transferCount:
          type: integer
          format: int64
        tokenTransfersTruncated:
          type: boolean
        tokenTransfers:
          type: array
          maxItems: 4096
          items:
            $ref: "#/components/schemas/TransactionTransferView"
        hasBurnToZero:
          type: boolean
        hasMintFromZero:
          type: boolean
        bridgeSignalContracts:
          type: array
          maxItems: 256
          items:
            type: string
        bridgeIntent:
          oneOf:
            - $ref: "#/components/schemas/BridgeIntentView"
            - type: "null"
        logCount:
          type: integer
          format: int64
        logsTruncated:
          type: boolean
        logs:
          type: array
          maxItems: 4096
          items:
            $ref: "#/components/schemas/TransactionPreviewLogView"
    TransactionPreviewBatchView:
      type: object
      additionalProperties: false
      required:
        - items
      properties:
        items:
          type: array
          maxItems: 128
          items:
            $ref: "#/components/schemas/TransactionPreviewView"
    TransactionPreviewBatchRequest:
      type: object
      additionalProperties: false
      required:
        - hashes
      properties:
        hashes:
          type: array
          minItems: 1
          maxItems: 128
          items:
            type: string
        includeLogs:
          type:
            - boolean
            - "null"
          description: |
            Include bounded preview logs for each transaction. Defaults to `false` when omitted.
        includeLogCounts:
          type:
            - boolean
            - "null"
          description: |
            Include exact log counts even when logs are not requested. When omitted, defaults to the same value as `includeLogs`.
        includeBridgeSignals:
          type:
            - boolean
            - "null"
          default: true
          description: |
            Include bridge transfer signal detection (`hasMintFromZero`, `hasBurnToZero`, `bridgeSignalContracts`, `bridgeIntent`). Defaults to `true` when omitted.
        logLimitPerTx:
          type:
            - integer
            - "null"
          format: int32
          default: 64
          minimum: 1
          maximum: 256
          description: |
            Maximum number of logs returned per transaction when `includeLogs` is enabled. Defaults to `64` when omitted.
    TransactionDetailView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - blockNumber
        - txIndex
        - txHash
        - txCursor
        - fromAddress
        - toAddress
        - executionStatus
        - finalityStatus
        - txType
        - rawObjectKey
        - calldata
        - receipt
        - logsTruncated
        - logs
        - tokenTransfers
        - messages
        - messagesCoverage
        - bridgeIntent
      properties:
        chainId:
          type: string
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
        txIndex:
          type: integer
          format: int32
        txHash:
          type: string
        txCursor:
          type: string
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        executionStatus:
          type:
            - string
            - "null"
        finalityStatus:
          type:
            - string
            - "null"
        txType:
          type:
            - string
            - "null"
        rawObjectKey:
          type: string
        receipt:
          oneOf:
            - $ref: "#/components/schemas/TransactionReceiptView"
            - type: "null"
        logsTruncated:
          type: boolean
        logs:
          type: array
          maxItems: 512
          items:
            $ref: "#/components/schemas/TransactionLogView"
        calldata:
          type: array
          maxItems: 1024
          items:
            type: string
        tokenTransfers:
          type: array
          maxItems: 4096
          items:
            $ref: "#/components/schemas/TransactionTransferView"
        messages:
          type: array
          maxItems: 32
          items:
            $ref: "#/components/schemas/MessageItem"
        messagesCoverage:
          $ref: "#/components/schemas/MessageCoverageView"
        bridgeIntent:
          oneOf:
            - $ref: "#/components/schemas/BridgeIntentView"
            - type: "null"
    AddressSummaryView:
      type: object
      additionalProperties: false
      required:
        - address
        - totalActivityCount
        - latestActivityBlock
      properties:
        address:
          type: string
        totalActivityCount:
          type: integer
          format: int64
        latestActivityBlock:
          type:
            - integer
            - "null"
          format: int64
        activityCountExact:
          type:
            - boolean
            - "null"
        classHash:
          type:
            - string
            - "null"
          description: Starknet contract class hash (0x-prefixed felt hex), null when unavailable.
          pattern: ^0x[0-9a-fA-F]{1,64}$
        isAccount:
          type:
            - boolean
            - "null"
          description: True if the class behaves as an account contract, null when unknown.
        createdOnIso:
          type:
            - string
            - "null"
        deployedAtTxHash:
          type:
            - string
            - "null"
        deployedByAddress:
          type:
            - string
            - "null"
    ContractMetadataView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - address
        - classHash
        - deployedAtBlock
        - deployedAtTx
        - createdOnIso
        - deployedByAddress
        - isAccount
        - isToken
        - tokenKind
        - alias
        - metadataCompleteness
        - source
      properties:
        chainId:
          type: string
        address:
          type: string
        classHash:
          type:
            - string
            - "null"
          description: Starknet class hash from indexed deployment facts when available.
        deployedAtBlock:
          type:
            - integer
            - "null"
          format: int64
          description: Deployment block from canonical indexed state-update facts when available.
        deployedAtTx:
          type:
            - string
            - "null"
          description: Deployment transaction hash when an indexed deployment transaction is known.
        createdOnIso:
          type:
            - string
            - "null"
          format: date-time
        deployedByAddress:
          type:
            - string
            - "null"
        isAccount:
          type:
            - boolean
            - "null"
        isToken:
          type:
            - boolean
            - "null"
          enum:
            - true
            - null
          description: True when token metadata exists; null means not identified in the indexed token metadata table.
        tokenKind:
          type:
            - string
            - "null"
          enum:
            - erc20
            - erc721
            - erc1155
            - unknown
            - null
        alias:
          type:
            - string
            - "null"
          description: Token name or symbol when indexed token metadata is available.
        metadataCompleteness:
          type: boolean
          description: True when both class hash and canonical deployment block are available.
        source:
          type: string
          enum:
            - indexed_read_model
      allOf:
        - oneOf:
            - required:
                - isToken
                - tokenKind
                - alias
              properties:
                isToken:
                  type: "null"
                tokenKind:
                  type: "null"
                alias:
                  type: "null"
            - required:
                - isToken
                - tokenKind
              properties:
                isToken:
                  type: boolean
                  enum:
                    - true
                tokenKind:
                  type: string
                  enum:
                    - erc20
                    - erc721
                    - erc1155
                    - unknown
    AddressSummaryBatchRequest:
      type: object
      additionalProperties: false
      required:
        - addresses
      properties:
        addresses:
          type: array
          minItems: 1
          maxItems: 128
          items:
            type: string
    AddressSummaryBatchView:
      type: object
      description: |
        Ordered indexed address summaries. Bulk responses favor predictable latency over cold repair; nullable fields and `activityCountExact=false` mean Starkscan does not have complete indexed evidence for that field in this batch response.
      additionalProperties: false
      required:
        - items
      properties:
        items:
          type: array
          maxItems: 128
          items:
            $ref: "#/components/schemas/AddressSummaryView"
    AddressIntelligenceItemBaseView:
      type: object
      additionalProperties: false
      required:
        - address
        - label
        - protocol
        - isDeployed
        - classHash
        - isAccount
        - deployedAtTxHash
        - deployedByAddress
        - hasReceivedFunds
        - latestActivityBlock
        - totalActivityCount
        - activityCountExact
        - source
      properties:
        address:
          type: string
        label:
          type:
            - string
            - "null"
          description: Human-readable protocol, project, or token label when indexed attribution is known.
        protocol:
          anyOf:
            - $ref: "#/components/schemas/AddressAttributionProtocolView"
            - type: "null"
        isDeployed:
          type: boolean
          description: True only when authoritative indexed deployment/class evidence exists for the address.
        classHash:
          type:
            - string
            - "null"
        isAccount:
          type:
            - boolean
            - "null"
        deployedAtTxHash:
          type:
            - string
            - "null"
          description: Indexed deployment transaction hash when authoritative deployment evidence exists.
        deployedByAddress:
          type:
            - string
            - "null"
          description: Indexed deployer/factory address when authoritative deployment attribution exists.
        hasReceivedFunds:
          type: boolean
          description: True when indexed token-transfer rows show the address as recipient.
        latestActivityBlock:
          type:
            - integer
            - "null"
          format: int64
        totalActivityCount:
          type: integer
          format: int64
        activityCountExact:
          type:
            - boolean
            - "null"
          description: |
            True when the returned activity count is complete for the indexed summary windows used by this response. False means the batch route intentionally returned bounded indexed metadata without cold repair or raw activity scans.
        source:
          type: string
          enum:
            - indexed_partner_address_evidence
    AddressIntelligenceItemView:
      oneOf:
        - allOf:
            - $ref: "#/components/schemas/AddressIntelligenceItemBaseView"
            - type: object
              description: Deployed address with authoritative indexed class evidence.
              required:
                - isDeployed
                - classHash
              properties:
                isDeployed:
                  const: true
                classHash:
                  type: string
        - allOf:
            - $ref: "#/components/schemas/AddressIntelligenceItemBaseView"
            - type: object
              description: Address without authoritative indexed deployment evidence.
              required:
                - isDeployed
                - classHash
                - deployedAtTxHash
                - deployedByAddress
              properties:
                isDeployed:
                  const: false
                classHash:
                  type: "null"
                deployedAtTxHash:
                  type: "null"
                deployedByAddress:
                  type: "null"
    AddressAttributionProtocolView:
      type: object
      additionalProperties: false
      required:
        - name
        - kind
      properties:
        name:
          type: string
          description: Human-readable protocol, project, or token label.
        kind:
          type:
            - string
            - "null"
          description: Indexed protocol or token kind when known.
    AddressAttributionBaseView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - requestedAddress
        - canonicalAddress
        - known
        - label
        - confidence
        - source
        - protocol
      properties:
        chainId:
          type: string
        requestedAddress:
          type: string
          description: Address supplied by the client after path validation.
        canonicalAddress:
          type: string
          description: Canonical indexed Starknet address used for lookup.
        known:
          type: boolean
          description: True when Starkscan has a readable label/protocol attribution.
        label:
          type:
            - string
            - "null"
          description: Human-readable label when known.
        confidence:
          type: string
          enum:
            - high
            - none
          description: Confidence bucket for the resolved label.
        source:
          type: string
          enum:
            - indexed_address_attribution
            - indexed_protocol_registry
            - indexed_token_metadata
        protocol:
          oneOf:
            - $ref: "#/components/schemas/AddressAttributionProtocolView"
            - type: "null"
    AddressAttributionView:
      oneOf:
        - allOf:
            - $ref: "#/components/schemas/AddressAttributionBaseView"
            - type: object
              description: Known address with a Starkscan-readable label.
              required:
                - known
                - label
                - confidence
                - protocol
              properties:
                known:
                  const: true
                label:
                  type: string
                confidence:
                  const: high
                protocol:
                  $ref: "#/components/schemas/AddressAttributionProtocolView"
        - allOf:
            - $ref: "#/components/schemas/AddressAttributionBaseView"
            - type: object
              description: Unknown address with no readable Starkscan attribution.
              required:
                - known
                - label
                - confidence
                - source
                - protocol
              properties:
                known:
                  const: false
                label:
                  type: "null"
                confidence:
                  const: none
                source:
                  const: indexed_address_attribution
                protocol:
                  type: "null"
    AddressIntelligenceBatchView:
      type: object
      additionalProperties: false
      required:
        - items
      properties:
        items:
          type: array
          maxItems: 128
          items:
            $ref: "#/components/schemas/AddressIntelligenceItemView"
    WalletPaymasterViewRequest:
      type: object
      additionalProperties: false
      required:
        - addresses
      properties:
        addresses:
          type: array
          minItems: 1
          maxItems: 32
          items:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        include:
          $ref: "#/components/schemas/WalletPaymasterViewInclude"
        freshness:
          $ref: "#/components/schemas/WalletPaymasterViewFreshness"
    WalletPaymasterViewInclude:
      type: object
      additionalProperties: false
      properties:
        identity:
          type: boolean
          default: true
        accountState:
          type: boolean
          default: true
        tokenHoldings:
          oneOf:
            - $ref: "#/components/schemas/WalletPaymasterLimitedSectionRequest"
            - type: "null"
          description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section.
        recentTransactions:
          oneOf:
            - $ref: "#/components/schemas/WalletPaymasterRecentTransactionsRequest"
            - type: "null"
          description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section.
        bridgeAndMessages:
          type: boolean
          default: false
          description: Reserved for forward-compatible requests. In v1, true fails closed with unsupported_section.
        finality:
          type: boolean
          default: true
        provenanceDetails:
          type: boolean
          default: false
          description: Reserved for forward-compatible requests. In v1, true fails closed with unsupported_section; row-level details are not exposed in the first slice.
    WalletPaymasterLimitedSectionRequest:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type:
            - boolean
            - "null"
        limit:
          type:
            - integer
            - "null"
          format: int32
          minimum: 1
          maximum: 100
        cursorsByAddress:
          type: object
          additionalProperties:
            type:
              - string
              - "null"
        includeSpam:
          type: boolean
          default: false
    WalletPaymasterRecentTransactionsRequest:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type:
            - boolean
            - "null"
        limit:
          type:
            - integer
            - "null"
          format: int32
          minimum: 1
          maximum: 25
        cursorsByAddress:
          type: object
          additionalProperties:
            type:
              - string
              - "null"
        includeReceipts:
          type: boolean
          default: false
    WalletPaymasterViewFreshness:
      type: object
      additionalProperties: false
      properties:
        maxIndexedLagMs:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: Accepted for forward-compatible requests; current responses warn that millisecond freshness is unavailable.
        requireFresh:
          type: boolean
          default: false
    DefiLendingMarketViewRequest:
      type: object
      additionalProperties: false
      required:
        - markets
      properties:
        markets:
          type: array
          minItems: 1
          maxItems: 8
          items:
            $ref: "#/components/schemas/DefiLendingMarketSelectorRequest"
        include:
          $ref: "#/components/schemas/DefiLendingMarketViewInclude"
        freshness:
          $ref: "#/components/schemas/DefiLendingMarketViewFreshness"
    DefiLendingMarketSelectorRequest:
      type: object
      additionalProperties: false
      required:
        - marketId
      properties:
        marketId:
          type: string
          minLength: 1
          maxLength: 128
          description: Client-supplied stable market identifier, for example `vesu-main`.
        contracts:
          type: array
          maxItems: 32
          items:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
          description: Lending market, pool, singleton, vToken, periphery, oracle, or liquidation-helper contracts to hydrate from indexed address summaries.
        tokenAddresses:
          type: array
          maxItems: 32
          items:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
          description: Token addresses relevant to the selected market; echoed back for stable partner request correlation.
    DefiLendingMarketViewInclude:
      type: object
      additionalProperties: false
      properties:
        contractIdentity:
          type: boolean
          default: true
        stateSamples:
          oneOf:
            - $ref: "#/components/schemas/DefiLendingStateSamplesRequest"
            - type: "null"
          description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section.
        events:
          oneOf:
            - $ref: "#/components/schemas/DefiLendingEventsRequest"
            - type: "null"
          description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section.
        recentTransactions:
          oneOf:
            - $ref: "#/components/schemas/DefiLendingRecentTransactionsRequest"
            - type: "null"
          description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section.
        simulationMetadata:
          type: boolean
          default: true
          description: Returns the Query Plane boundary that simulation and signed-write execution remain on JSON-RPC.
        provenanceDetails:
          type: boolean
          default: false
          description: Reserved for forward-compatible requests. In v1, true fails closed with unsupported_section; row-level details are not exposed in the first slice.
    DefiLendingStateSamplesRequest:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type:
            - boolean
            - "null"
        keys:
          type: array
          items:
            type: string
          maxItems: 16
        maxSamplesPerContract:
          type:
            - integer
            - "null"
          format: int32
          minimum: 1
          maximum: 16
    DefiLendingEventsRequest:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type:
            - boolean
            - "null"
        eventSelectors:
          type: array
          items:
            type: string
            pattern: ^0[xX][0-9a-fA-F]{1,64}$
        fromBlock:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        toBlock:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        limit:
          type:
            - integer
            - "null"
          format: int32
          minimum: 1
          maximum: 500
        cursorsByMarketId:
          type: object
          additionalProperties:
            type:
              - string
              - "null"
    DefiLendingRecentTransactionsRequest:
      type: object
      additionalProperties: false
      properties:
        enabled:
          type:
            - boolean
            - "null"
        limit:
          type:
            - integer
            - "null"
          format: int32
          minimum: 1
          maximum: 50
        cursorsByMarketId:
          type: object
          additionalProperties:
            type:
              - string
              - "null"
    DefiLendingMarketViewFreshness:
      type: object
      additionalProperties: false
      properties:
        maxIndexedLagMs:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: Accepted for forward-compatible requests; current responses warn that millisecond freshness is unavailable.
        requireFresh:
          type: boolean
          default: false
    SupportProofBundleRequest:
      type: object
      additionalProperties: false
      properties:
        txHash:
          type:
            - string
            - "null"
          pattern: ^0[xX][0-9a-fA-F]{1,64}$
          description: Incident transaction hash. Exactly one of `txHash` or `messageHash` is required.
        messageHash:
          type:
            - string
            - "null"
          pattern: ^0[xX][0-9a-fA-F]{1,64}$
          description: Incident protocol-message hash. Exactly one of `txHash` or `messageHash` is required.
        supportCorrelationId:
          type:
            - string
            - "null"
          maxLength: 128
          description: Optional customer-support ticket, case, or incident id echoed back for operator correlation.
        include:
          $ref: "#/components/schemas/SupportProofBundleInclude"
        freshness:
          $ref: "#/components/schemas/SupportProofBundleFreshness"
    SupportProofBundleInclude:
      type: object
      additionalProperties: false
      properties:
        transaction:
          type: boolean
          default: true
          description: Return transaction detail when the incident selector is `txHash`; message-hash incidents return a warning instead of doing a reverse scan.
        protocolMessages:
          type: boolean
          default: true
        starkgate:
          type: boolean
          default: true
        finality:
          type: boolean
          default: true
        provenanceDetails:
          type: boolean
          default: false
          description: Reserved for forward-compatible requests. In v1, true fails closed with unsupported_section; row-level details are not exposed in the first slice.
    SupportProofBundleFreshness:
      type: object
      additionalProperties: false
      properties:
        maxIndexedLagMs:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: Accepted for forward-compatible requests; current responses warn that millisecond freshness is unavailable.
        requireFresh:
          type: boolean
          default: false
    WalletPaymasterQueryEnvelope:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - chain
        - requestId
        - snapshot
        - provenance
        - partial
        - warnings
        - data
      properties:
        schemaVersion:
          type: string
          enum:
            - starkscan.query.wallet_paymaster_view.v1
        chain:
          type: string
        requestId:
          type: string
        snapshot:
          $ref: "#/components/schemas/QueryPlaneSnapshot"
        provenance:
          type: array
          items:
            $ref: "#/components/schemas/QueryPlaneProvenance"
        partial:
          type: boolean
          description: True when requested sections or source rows are unavailable and warnings explain the gap.
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/QueryPlaneWarning"
        data:
          $ref: "#/components/schemas/WalletPaymasterViewData"
    DefiLendingMarketQueryEnvelope:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - chain
        - requestId
        - snapshot
        - provenance
        - partial
        - warnings
        - data
      properties:
        schemaVersion:
          type: string
          enum:
            - starkscan.query.defi_lending_market_view.v1
        chain:
          type: string
        requestId:
          type: string
        snapshot:
          $ref: "#/components/schemas/QueryPlaneSnapshot"
        provenance:
          type: array
          items:
            $ref: "#/components/schemas/QueryPlaneProvenance"
        partial:
          type: boolean
          description: True when requested sections or source rows are unavailable and warnings explain the gap.
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/QueryPlaneWarning"
        data:
          $ref: "#/components/schemas/DefiLendingMarketViewData"
    SupportProofBundleEnvelope:
      type: object
      additionalProperties: false
      required:
        - schemaVersion
        - chain
        - requestId
        - snapshot
        - provenance
        - partial
        - warnings
        - data
      properties:
        schemaVersion:
          type: string
          enum:
            - starkscan.query.support_proof_bundle.v1
        chain:
          type: string
        requestId:
          type: string
        snapshot:
          $ref: "#/components/schemas/QueryPlaneSnapshot"
        provenance:
          type: array
          items:
            $ref: "#/components/schemas/QueryPlaneProvenance"
        partial:
          type: boolean
          description: True when requested sections or source rows are unavailable and warnings explain the gap.
        warnings:
          type: array
          items:
            $ref: "#/components/schemas/QueryPlaneWarning"
        data:
          $ref: "#/components/schemas/SupportProofBundleData"
    QueryPlaneSnapshot:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - blockHash
        - l1AcceptedBlockNumber
        - l1AcceptedSource
        - finalityStatus
        - freshnessMs
        - watermarkSource
      properties:
        blockNumber:
          type:
            - integer
            - "null"
          format: int64
        blockHash:
          type:
            - string
            - "null"
        l1AcceptedBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        l1AcceptedSource:
          type:
            - string
            - "null"
        finalityStatus:
          type: string
          enum:
            - l1_accepted
            - l2_accepted
            - unknown
        freshnessMs:
          type:
            - integer
            - "null"
          format: int64
        watermarkSource:
          type: string
          enum:
            - indexed_read_model
    QueryPlaneProvenance:
      type: object
      additionalProperties: false
      required:
        - fact
        - source
        - blockNumber
        - coverage
      properties:
        fact:
          type: string
        source:
          type: string
        blockNumber:
          type:
            - integer
            - "null"
          format: int64
        coverage:
          type: string
    QueryPlaneWarning:
      type: object
      additionalProperties: false
      required:
        - warningCode
        - message
      properties:
        warningCode:
          type: string
        section:
          type: string
        source:
          type: string
        sourceBlockNumber:
          type: integer
          format: int64
        bundleBlockNumber:
          description: |
            Bundle snapshot block number associated with this warning. This is the indexed Query Plane snapshot block, not the live head unless the bundle snapshot itself falls back to the live head.
          type: integer
          format: int64
        message:
          type: string
    WalletPaymasterViewData:
      type: object
      additionalProperties: false
      required:
        - addresses
      properties:
        addresses:
          type: array
          maxItems: 32
          items:
            $ref: "#/components/schemas/WalletPaymasterAddressView"
    WalletPaymasterAddressView:
      type: object
      additionalProperties: false
      required:
        - address
      properties:
        address:
          type: string
        identity:
          $ref: "#/components/schemas/WalletPaymasterIdentityView"
        accountState:
          $ref: "#/components/schemas/WalletPaymasterAccountStateView"
        tokenHoldings:
          type: "null"
          description: Present as null only when requested; first slice returns an unsupported-section warning.
        recentTransactions:
          type: "null"
          description: Present as null only when requested; first slice returns an unsupported-section warning.
        bridgeAndMessages:
          type: "null"
          description: Present as null only when requested; first slice returns an unsupported-section warning.
        finality:
          $ref: "#/components/schemas/WalletPaymasterFinalityView"
    WalletPaymasterIdentityView:
      type: object
      additionalProperties: false
      required:
        - label
        - protocol
        - isAccount
        - source
      properties:
        label:
          type:
            - string
            - "null"
        protocol:
          oneOf:
            - type: object
              additionalProperties: true
            - type: "null"
          description: Indexed protocol attribution object when available.
        isAccount:
          type:
            - boolean
            - "null"
        source:
          type: string
          enum:
            - starkscan_address_summary_read_model
    WalletPaymasterAccountStateView:
      type: object
      additionalProperties: false
      required:
        - classHash
        - nonce
        - deployed
        - latestObservedBlock
        - activityCount
        - activityCountExact
        - createdOnIso
        - deployedAtTxHash
        - deployedByAddress
      properties:
        classHash:
          type:
            - string
            - "null"
        nonce:
          type:
            - string
            - "null"
        deployed:
          type:
            - boolean
            - "null"
        latestObservedBlock:
          type:
            - integer
            - "null"
          format: int64
        activityCount:
          type:
            - integer
            - "null"
          format: int64
        activityCountExact:
          type:
            - boolean
            - "null"
        createdOnIso:
          type:
            - string
            - "null"
          format: date-time
        deployedAtTxHash:
          type:
            - string
            - "null"
        deployedByAddress:
          type:
            - string
            - "null"
    WalletPaymasterFinalityView:
      type: object
      additionalProperties: false
      required:
        - latestL1AcceptedBlockNumber
        - source
      properties:
        latestL1AcceptedBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        source:
          type:
            - string
            - "null"
    DefiLendingMarketViewData:
      type: object
      additionalProperties: false
      required:
        - markets
      properties:
        markets:
          type: array
          maxItems: 8
          items:
            $ref: "#/components/schemas/DefiLendingMarketView"
    DefiLendingMarketView:
      type: object
      additionalProperties: false
      required:
        - marketId
        - tokenAddresses
      properties:
        marketId:
          type: string
        tokenAddresses:
          type: array
          maxItems: 32
          items:
            type: string
        contracts:
          type: array
          maxItems: 32
          items:
            $ref: "#/components/schemas/DefiLendingContractIdentityView"
        simulationMetadata:
          $ref: "#/components/schemas/DefiLendingSimulationMetadataView"
    DefiLendingContractIdentityView:
      type: object
      additionalProperties: false
      required:
        - address
        - classHash
        - deployed
        - latestObservedBlock
        - activityCount
        - activityCountExact
        - source
      properties:
        address:
          type: string
        classHash:
          type:
            - string
            - "null"
        deployed:
          type:
            - boolean
            - "null"
        latestObservedBlock:
          type:
            - integer
            - "null"
          format: int64
        activityCount:
          type:
            - integer
            - "null"
          format: int64
        activityCountExact:
          type:
            - boolean
            - "null"
        source:
          type: string
          enum:
            - starkscan_address_summary_read_model
    DefiLendingSimulationMetadataView:
      type: object
      additionalProperties: false
      required:
        - supported
        - boundary
        - source
      properties:
        supported:
          type: boolean
          enum:
            - false
        boundary:
          type: string
          description: Query Plane v1 boundary. Simulation and signed-write execution remain on the JSON-RPC compatibility plane.
        source:
          type: string
          enum:
            - starkscan_query_plane_contract
    SupportProofBundleData:
      type: object
      additionalProperties: false
      required:
        - incident
      properties:
        incident:
          $ref: "#/components/schemas/SupportProofIncidentView"
        transaction:
          oneOf:
            - $ref: "#/components/schemas/TransactionDetailView"
            - type: "null"
          description: Present when requested and the incident selector is a transaction hash.
        protocolMessages:
          oneOf:
            - $ref: "#/components/schemas/MessagePage"
            - type: "null"
          description: Protocol-message lifecycle rows for the incident selector.
        starkgate:
          oneOf:
            - $ref: "#/components/schemas/StarkgateTransferResolutionView"
            - type: "null"
          description: StarkGate transfer resolution for the incident selector.
        finality:
          oneOf:
            - $ref: "#/components/schemas/SupportProofFinalityView"
            - type: "null"
    SupportProofIncidentView:
      type: object
      additionalProperties: false
      required:
        - txHash
        - messageHash
        - supportCorrelationId
      properties:
        txHash:
          type:
            - string
            - "null"
        messageHash:
          type:
            - string
            - "null"
        supportCorrelationId:
          type:
            - string
            - "null"
    SupportProofFinalityView:
      type: object
      additionalProperties: false
      required:
        - latestL1AcceptedBlockNumber
        - source
        - bundleFinalityStatus
      properties:
        latestL1AcceptedBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        source:
          type:
            - string
            - "null"
        bundleFinalityStatus:
          type: string
          enum:
            - l1_accepted
            - l2_accepted
            - unknown
    ContractVerificationView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - contractAddress
        - classHash
        - sourceRef
        - language
        - compilerVersion
        - verificationStatus
        - verificationError
        - requestedAtIso
        - verifiedAtIso
        - updatedAtIso
        - metadata
      properties:
        chainId:
          type: string
        contractAddress:
          type: string
        classHash:
          type:
            - string
            - "null"
        sourceRef:
          type:
            - string
            - "null"
        language:
          type:
            - string
            - "null"
        compilerVersion:
          type:
            - string
            - "null"
        verificationStatus:
          type: string
          enum:
            - pending
            - verified
            - failed
        verificationError:
          type:
            - string
            - "null"
        requestedAtIso:
          type: string
        verifiedAtIso:
          type:
            - string
            - "null"
        updatedAtIso:
          type: string
        metadata:
          type: object
    ContractVerificationUpsertRequest:
      type: object
      additionalProperties: false
      required:
        - verificationStatus
      properties:
        classHash:
          type:
            - string
            - "null"
        sourceRef:
          type:
            - string
            - "null"
        language:
          type:
            - string
            - "null"
        compilerVersion:
          type:
            - string
            - "null"
        verificationStatus:
          type: string
          enum:
            - pending
            - verified
            - failed
        verificationError:
          type:
            - string
            - "null"
        requestedAtIso:
          type:
            - string
            - "null"
        verifiedAtIso:
          type:
            - string
            - "null"
        metadata:
          type: object
    ContractEntrypointItem:
      type: object
      additionalProperties: false
      required:
        - selector
        - name
        - stateMutability
      properties:
        selector:
          type: string
        name:
          type:
            - string
            - "null"
        stateMutability:
          type:
            - string
            - "null"
    ContractEntrypointsView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - contractAddress
        - external
        - constructor
        - l1Handler
      properties:
        chainId:
          type: string
        contractAddress:
          type: string
        external:
          type: array
          maxItems: 256
          items:
            $ref: "#/components/schemas/ContractEntrypointItem"
        constructor:
          type: array
          maxItems: 16
          items:
            $ref: "#/components/schemas/ContractEntrypointItem"
        l1Handler:
          type: array
          maxItems: 16
          items:
            $ref: "#/components/schemas/ContractEntrypointItem"
    EventDecodedField:
      type: object
      additionalProperties: false
      required:
        - label
        - type
        - source
        - kind
        - status
        - rawValues
        - originIndexes
        - displayValue
        - addressValue
        - numericValue
        - textValue
        - boolValue
      properties:
        label:
          type: string
        type:
          type:
            - string
            - "null"
          description: Cairo ABI type used for this decoded field when available.
        source:
          type: string
          enum:
            - key
            - data
        kind:
          type: string
          enum:
            - address
            - hash
            - bool
            - u256
            - felt
            - text
        status:
          type: string
          enum:
            - decoded
            - partial
            - raw
        rawValues:
          type: array
          maxItems: 8
          items:
            type: string
        originIndexes:
          type: array
          maxItems: 8
          items:
            type: integer
            minimum: 0
        displayValue:
          type: string
        addressValue:
          type:
            - string
            - "null"
        numericValue:
          type:
            - string
            - "null"
        textValue:
          type:
            - string
            - "null"
        boolValue:
          type:
            - boolean
            - "null"
    ContractEventItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - timestampIso
        - txHash
        - txIndex
        - logIndex
        - address
        - topic0
        - topic1
        - topic2
        - topic3
        - data
      properties:
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type: string
          format: date-time
        txHash:
          type: string
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        address:
          type: string
        topic0:
          type:
            - string
            - "null"
        topic1:
          type:
            - string
            - "null"
        topic2:
          type:
            - string
            - "null"
        topic3:
          type:
            - string
            - "null"
        data:
          type: array
          maxItems: 1024
          items:
            type: string
        eventName:
          type:
            - string
            - "null"
          description: Reviewed or ABI-derived event name when Starkscan can attribute topic0.
        eventNameSource:
          type:
            - string
            - "null"
          description: Attribution source for eventName. Current values include verified_abi, class_abi, selector_unique, and curated_selector; clients should treat unknown strings as forward-compatible provenance labels.
        eventNameUnavailableReason:
          type:
            - string
            - "null"
          enum:
            - event_time_class_epoch_unavailable
            - null
          description: Reason eventName is omitted even though Starkscan has contract-scoped epoch facts for this event. Raw topic/data fields remain authoritative.
        decodedFields:
          type: array
          maxItems: 128
          items:
            $ref: "#/components/schemas/EventDecodedField"
          description: Best-effort decoded key/data fields when Starkscan has an exact materialized ABI schema match for this event. Raw topic/data fields remain authoritative.
        decodedFieldsSource:
          type:
            - string
            - "null"
          description: Attribution source used for decodedFields when present.
        decodedFieldsUnavailableReason:
          type:
            - string
            - "null"
          enum:
            - schema_unavailable
            - selector_only_attribution
            - payload_shape_mismatch
            - schema_shape_unsupported
            - null
          description: Reason decodedFields is omitted for an attributed event. Selector-only attribution names the event but does not prove the field layout; raw topic/data fields remain authoritative.
    ContractEventPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/ContractEventItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+$
    ContractAdvancedCoverageView:
      type: object
      additionalProperties: false
      required:
        - status
        - source
        - reasonCode
        - message
      properties:
        status:
          type: string
          enum:
            - exact
            - partial
            - unavailable
        source:
          type: string
          enum:
            - trace_facts
            - l2_bridge_signals
            - bridge_adapter_events
            - bridge_message_facts
        reasonCode:
          type: string
          enum:
            - indexed_trace_facts
            - no_matching_trace_rows
            - trace_tables_unavailable
            - trace_extraction_truncated
            - trace_projection_stale
            - indexed_bridge_pairing_facts
            - l1_pairing_not_indexed
            - bridge_message_facts_unavailable
            - adapter_pairing_facts_unavailable
            - query_timeout
        message:
          type: string
        latestIndexedBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        chainHeadBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        lagBlocks:
          type:
            - integer
            - "null"
          format: int64
    ContractAccountCallItem:
      type: object
      additionalProperties: false
      required:
        - id
        - blockNumber
        - timestampIso
        - txIndex
        - callIndex
        - tracePath
        - txHash
        - methodName
        - entryPointSelector
        - senderAddress
        - callerAddress
        - calleeAddress
        - executionStatus
        - finalityStatus
        - sourceTier
        - extractionTruncated
      properties:
        id:
          type: string
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
        txIndex:
          type: integer
          format: int32
        callIndex:
          type: integer
          format: int32
        tracePath:
          type:
            - string
            - "null"
        txHash:
          type: string
        methodName:
          type:
            - string
            - "null"
        entryPointSelector:
          type:
            - string
            - "null"
        senderAddress:
          type:
            - string
            - "null"
        callerAddress:
          type:
            - string
            - "null"
        calleeAddress:
          type: string
        executionStatus:
          type:
            - string
            - "null"
        finalityStatus:
          type:
            - string
            - "null"
        sourceTier:
          type: string
          enum:
            - head
            - finalized
        extractionTruncated:
          type: boolean
    ContractAccountCallPage:
      type: object
      additionalProperties: false
      required:
        - chainId
        - contractAddress
        - items
        - nextCursor
        - coverage
      properties:
        chainId:
          type: string
        contractAddress:
          type: string
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/ContractAccountCallItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+$
        coverage:
          $ref: "#/components/schemas/ContractAdvancedCoverageView"
    ContractBridgeTransactionItem:
      type: object
      additionalProperties: false
      required:
        - id
        - blockNumber
        - timestampIso
        - txIndex
        - logIndex
        - transferIndex
        - txHash
        - status
        - direction
        - messageHash
        - l1Hash
        - l2Hash
        - l1ContractAddress
        - l2ContractAddress
        - tokenAddress
        - tokenSymbol
        - tokenDecimals
        - amountRaw
        - fromAddress
        - toAddress
        - pairingConfidence
        - sourceTier
      properties:
        id:
          type: string
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        transferIndex:
          type: integer
          format: int32
        txHash:
          type: string
        status:
          type: string
        direction:
          type:
            - string
            - "null"
          enum:
            - inbound
            - outbound
            - null
        messageHash:
          type:
            - string
            - "null"
        l1Hash:
          type:
            - string
            - "null"
        l2Hash:
          type:
            - string
            - "null"
        l1ContractAddress:
          type:
            - string
            - "null"
        l2ContractAddress:
          type:
            - string
            - "null"
        tokenAddress:
          type:
            - string
            - "null"
        tokenSymbol:
          type:
            - string
            - "null"
        tokenDecimals:
          type:
            - integer
            - "null"
          format: int32
        amountRaw:
          type:
            - string
            - "null"
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        pairingConfidence:
          type: string
          enum:
            - message_pairing_fact
            - adapter_pairing_fact
            - unpaired_l2_only
        sourceTier:
          type: string
          enum:
            - head
            - finalized
    ContractBridgeTransactionPage:
      type: object
      additionalProperties: false
      required:
        - chainId
        - contractAddress
        - items
        - nextCursor
        - coverage
      properties:
        chainId:
          type: string
        contractAddress:
          type: string
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/ContractBridgeTransactionItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+(:[0-9]+)?$
        coverage:
          $ref: "#/components/schemas/ContractAdvancedCoverageView"
    StarkgateTransferCoverageView:
      type: object
      additionalProperties: false
      required:
        - status
        - source
        - reasonCode
        - message
      properties:
        status:
          type: string
        source:
          type: string
        reasonCode:
          type: string
        message:
          type: string
    StarkgateTransferStageView:
      type: object
      additionalProperties: false
      required:
        - key
        - label
        - status
        - chain
        - txHash
        - blockNumber
      properties:
        key:
          type: string
        label:
          type: string
        status:
          type: string
        chain:
          type: string
        txHash:
          type:
            - string
            - "null"
        blockNumber:
          type:
            - integer
            - "null"
          format: int64
    StarkgateTransferItem:
      type: object
      additionalProperties: false
      required:
        - id
        - messageHash
        - direction
        - status
        - statusLabel
        - nextAction
        - tokenAddress
        - tokenSymbol
        - tokenDecimals
        - amountRaw
        - l1BridgeAddress
        - l2BridgeAddress
        - l1SenderAddress
        - l1RecipientAddress
        - l2SenderAddress
        - l2RecipientAddress
        - l1TxHash
        - l2TxHash
        - l1BlockNumber
        - l2BlockNumber
        - readyToClaimOnL1
        - completedOnL1
        - l1AcceptedBlockNumber
        - proofSource
        - proofL1BlockNumber
        - proofL1TxHash
        - proofEthereumFinality
        - proofUpdatedAt
        - selector
        - nonce
        - payload
        - payloadTruncated
        - sourceTier
        - evidence
        - missingFacts
        - stages
      properties:
        id:
          type: string
        messageHash:
          type: string
        direction:
          type: string
        status:
          type: string
        statusLabel:
          type: string
        nextAction:
          type: string
        tokenAddress:
          type:
            - string
            - "null"
        tokenSymbol:
          type:
            - string
            - "null"
        tokenDecimals:
          type:
            - integer
            - "null"
          format: int32
        amountRaw:
          type:
            - string
            - "null"
        l1BridgeAddress:
          type:
            - string
            - "null"
        l2BridgeAddress:
          type:
            - string
            - "null"
        l1SenderAddress:
          type:
            - string
            - "null"
        l1RecipientAddress:
          type:
            - string
            - "null"
        l2SenderAddress:
          type:
            - string
            - "null"
        l2RecipientAddress:
          type:
            - string
            - "null"
        l1TxHash:
          type:
            - string
            - "null"
        l2TxHash:
          type:
            - string
            - "null"
        l1BlockNumber:
          type:
            - integer
            - "null"
          format: int64
        l2BlockNumber:
          type:
            - integer
            - "null"
          format: int64
        readyToClaimOnL1:
          type: boolean
        completedOnL1:
          type: boolean
        l1AcceptedBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        proofSource:
          type:
            - string
            - "null"
          description: Latest indexed proof source used for L1 readiness decisions.
        proofL1BlockNumber:
          type:
            - integer
            - "null"
          format: int64
          description: Ethereum block number for the latest indexed StarknetCore state-update proof.
        proofL1TxHash:
          type:
            - string
            - "null"
          description: Ethereum transaction hash for the latest indexed StarknetCore state-update proof.
        proofEthereumFinality:
          type:
            - string
            - "null"
          description: Ethereum consensus finality level required by Starkscan before marking ready-to-claim state.
        proofUpdatedAt:
          type:
            - string
            - "null"
          format: date-time
          description: Timestamp when Starkscan last updated the indexed proof row.
        selector:
          type:
            - string
            - "null"
        nonce:
          type:
            - string
            - "null"
        payload:
          type: array
          maxItems: 256
          items:
            type: string
        payloadTruncated:
          type: boolean
        sourceTier:
          type: string
        evidence:
          type: array
          maxItems: 32
          items:
            type: string
        missingFacts:
          type: array
          maxItems: 32
          items:
            type: string
        stages:
          type: array
          maxItems: 8
          items:
            $ref: "#/components/schemas/StarkgateTransferStageView"
    StarkgateTransferQueryView:
      type: object
      additionalProperties: false
      required:
        - txHash
        - messageHash
        - address
        - token
        - bridge
        - status
        - cursor
        - direction
        - limit
      properties:
        txHash:
          type:
            - string
            - "null"
        messageHash:
          type:
            - string
            - "null"
        address:
          type:
            - string
            - "null"
        token:
          type:
            - string
            - "null"
        bridge:
          type:
            - string
            - "null"
        status:
          type:
            - string
            - "null"
        cursor:
          type:
            - string
            - "null"
        direction:
          type:
            - string
            - "null"
        limit:
          type: integer
          format: int64
    StarkgateTransferResolutionView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - query
        - items
        - coverage
      properties:
        chainId:
          type: string
        query:
          $ref: "#/components/schemas/StarkgateTransferQueryView"
        items:
          type: array
          maxItems: 25
          items:
            $ref: "#/components/schemas/StarkgateTransferItem"
        coverage:
          $ref: "#/components/schemas/StarkgateTransferCoverageView"
    StarkgateTransferPageView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - query
        - items
        - nextCursor
        - coverage
      properties:
        chainId:
          type: string
        query:
          $ref: "#/components/schemas/StarkgateTransferQueryView"
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/StarkgateTransferItem"
        nextCursor:
          type:
            - string
            - "null"
        coverage:
          $ref: "#/components/schemas/StarkgateTransferCoverageView"
    MessageCoverageView:
      type: object
      additionalProperties: false
      required:
        - status
        - source
        - reasonCode
        - message
      properties:
        status:
          type: string
          enum:
            - exact
            - partial
            - unavailable
        source:
          type: string
          enum:
            - starknet_protocol_messages
        reasonCode:
          type: string
          enum:
            - indexed_protocol_message_facts
            - no_matching_message_rows
            - message_not_found
            - message_detail_page_exhausted
            - message_facts_unavailable
            - message_detail_truncated
            - transaction_messages_truncated
            - query_timeout
        message:
          type: string
    MessageItem:
      type: object
      additionalProperties: false
      required:
        - id
        - blockNumber
        - timestampIso
        - txIndex
        - logIndex
        - messageHash
        - direction
        - fromAddress
        - toAddress
        - txHash
        - l1Hash
        - l2Hash
        - l1BlockNumber
        - l1Fee
        - l1ContractAddress
        - l2ContractAddress
        - bridgeContractAddress
        - status
        - l1SentCount
        - l2SentCount
        - l1ConsumedCount
        - pendingCount
        - nonce
        - selector
        - payload
        - payloadTruncated
        - sourceTier
      properties:
        id:
          type: string
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        messageHash:
          type: string
        direction:
          type: string
          enum:
            - l1_to_l2
            - l2_to_l1
            - unknown
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        txHash:
          type: string
        l1Hash:
          type:
            - string
            - "null"
        l2Hash:
          type:
            - string
            - "null"
        l1BlockNumber:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: |
            Latest indexed canonical Ethereum block associated with this message hash. For L1-to-L2 messages where l1SentCount > 1, this is the latest indexed L1 send block. Null when the relevant L1 origin or consumption fact has not been indexed.
        l1Fee:
          type:
            - string
            - "null"
          pattern: ^0[xX][0-9a-fA-F]{1,64}$
          description: |
            Canonical StarknetCore LogMessageToL2 fee for L1-to-L2 origins, encoded as a hex quantity when indexed. When l1SentCount > 1, this is the fee from the latest indexed L1 send, the same send reflected by l1BlockNumber. Null for L2-to-L1 messages or when no L1 origin has been indexed.
        l1ContractAddress:
          type:
            - string
            - "null"
        l2ContractAddress:
          type:
            - string
            - "null"
        bridgeContractAddress:
          type:
            - string
            - "null"
        status:
          type: string
        l1SentCount:
          type: integer
          format: int64
          minimum: 0
          description: Count of indexed canonical StarknetCore L1 origin logs sharing this L1-to-L2 message hash.
        l2SentCount:
          type: integer
          format: int64
          minimum: 0
          description: Count of indexed canonical L2 emissions sharing this message hash.
        l1ConsumedCount:
          type: integer
          format: int64
          minimum: 0
          description: Count of indexed canonical StarknetCore L1 consumption logs sharing this message hash.
        pendingCount:
          type: integer
          format: int64
          minimum: 0
          description: "Non-negative pending lifecycle count for this message hash: L1 origins minus L2 consumptions for L1-to-L2, or L2 emissions minus canonical L1 consumptions for L2-to-L1."
        nonce:
          type:
            - string
            - "null"
        selector:
          type:
            - string
            - "null"
        payload:
          type: array
          maxItems: 1024
          items:
            type: string
        payloadTruncated:
          type: boolean
        sourceTier:
          type: string
          enum:
            - head
            - finalized
    MessagePage:
      type: object
      additionalProperties: false
      required:
        - chainId
        - contractAddress
        - items
        - nextCursor
        - coverage
      properties:
        chainId:
          type: string
        contractAddress:
          type:
            - string
            - "null"
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/MessageItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)$
        coverage:
          $ref: "#/components/schemas/MessageCoverageView"
    MessageDetailView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - messageHash
        - items
        - nextCursor
        - coverage
      properties:
        chainId:
          type: string
        messageHash:
          type: string
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/MessageItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)$
        coverage:
          $ref: "#/components/schemas/MessageCoverageView"
    ContractReadResultView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - contractAddress
        - selector
        - blockTag
        - result
      properties:
        chainId:
          type: string
        contractAddress:
          type: string
        selector:
          type: string
        blockTag:
          allOf:
            - $ref: "#/components/schemas/BlockReference"
          description: Echoed validated caller text used for execution (`latest`, `pending`, block number, or block hash).
        result:
          type: array
          maxItems: 1024
          items:
            type: string
    ContractWritePayloadRequest:
      type: object
      additionalProperties: false
      required:
        - selector
      properties:
        selector:
          type: string
        calldata:
          type: array
          default: []
          maxItems: 1024
          items:
            type: string
    ContractWritePayloadView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - contractAddress
        - selector
        - calldata
        - call
      properties:
        chainId:
          type: string
        contractAddress:
          type: string
        selector:
          type: string
        calldata:
          type: array
          maxItems: 1024
          items:
            type: string
        call:
          type: object
    ContractTransactionTraceView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - txHash
        - trace
      properties:
        chainId:
          type: string
        txHash:
          type: string
        trace:
          type: object
    AddressActivityItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - timestampIso
        - txIndex
        - logIndex
        - transferIndex
        - txHash
        - txCursor
        - kind
        - counterparty
        - tokenAddress
        - amount
        - tokenId
      properties:
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
        txIndex:
          type: integer
          format: int32
        logIndex:
          type:
            - integer
            - "null"
          format: int32
        transferIndex:
          type:
            - integer
            - "null"
          format: int32
        txHash:
          type: string
        txCursor:
          type: string
        kind:
          type: string
        counterparty:
          type:
            - string
            - "null"
        tokenAddress:
          type:
            - string
            - "null"
        amount:
          type:
            - string
            - "null"
        tokenId:
          type:
            - string
            - "null"
    AddressActivityPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/AddressActivityItem"
        nextCursor:
          type:
            - string
            - "null"
    AddressTransactionListItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - timestampIso
        - txIndex
        - txHash
        - kinds
        - counterparty
        - txType
        - executionStatus
        - finalityStatus
        - fromAddress
        - toAddress
        - primaryMethod
        - callCount
        - methodsDiffer
        - transferCount
        - topTransferTokenAddress
        - topTransferAmount
        - topTransferStandard
      properties:
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
        txIndex:
          type: integer
          format: int32
        txHash:
          type: string
        kinds:
          type: array
          maxItems: 16
          items:
            type: string
        counterparty:
          type:
            - string
            - "null"
        txType:
          type:
            - string
            - "null"
        executionStatus:
          type:
            - string
            - "null"
        finalityStatus:
          type:
            - string
            - "null"
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        primaryMethod:
          type:
            - string
            - "null"
        callCount:
          type:
            - integer
            - "null"
          format: int32
        methodsDiffer:
          type:
            - boolean
            - "null"
        transferCount:
          type:
            - integer
            - "null"
          format: int32
        topTransferTokenAddress:
          type:
            - string
            - "null"
        topTransferAmount:
          type:
            - string
            - "null"
        topTransferStandard:
          type:
            - string
            - "null"
    AddressTransactionPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/AddressTransactionListItem"
        nextCursor:
          type:
            - string
            - "null"
    AddressTokenHoldingItemView:
      type: object
      additionalProperties: false
      required:
        - tokenAddress
        - normalizedTokenAddress
        - indexedBalanceRaw
        - symbol
        - name
        - decimals
      properties:
        tokenAddress:
          type: string
          description: Token contract address as stored by the indexed balance source.
        normalizedTokenAddress:
          type: string
          description: Lowercase compact `0x` token address for stable agent comparisons.
        indexedBalanceRaw:
          type: string
          description: Decimal (base-10) indexed balance string.
        symbol:
          type:
            - string
            - "null"
          description: Token symbol from trusted token-metadata data (token metadata indexes) or from known safe defaults when available.
        name:
          type:
            - string
            - "null"
          description: Token name from trusted token-metadata data (token metadata indexes) or from known safe defaults when available.
        decimals:
          type:
            - integer
            - "null"
          format: int32
          description: Token decimals from trusted token-metadata data (token metadata indexes) or from known safe defaults when available.
    TokenHoldingsCompletenessReasonCode:
      type: string
      enum:
        - complete
        - indexLag
        - boundedComputation
        - responseCap
        - metadataPending
        - degradedFallback
        - unknown
      description: |
        `complete` means the holdings snapshot is complete enough for portfolio parity checks. Other values are useful evidence but not exact portfolio ground truth. `lagBlocks` is populated when incompleteness can be attributed to indexed-source lag.
    AddressTokenHoldingsCompletenessView:
      type: object
      additionalProperties: false
      required:
        - exact
        - truncated
        - complete
        - reasonCode
        - reason
        - lagBlocks
        - capped
        - cap
      properties:
        exact:
          type: boolean
          description: Mirrors the top-level `exact` field.
        truncated:
          type: boolean
          description: Mirrors the top-level `truncated` field.
        complete:
          type: boolean
          description: |
            True only when the response is exact, not truncated, and `reasonCode=complete`.
        reasonCode:
          $ref: "#/components/schemas/TokenHoldingsCompletenessReasonCode"
        reason:
          type: string
          description: Human-readable explanation for the current completeness state.
        lagBlocks:
          type:
            - integer
            - "null"
          format: int64
          description: Indexed lag in blocks when known. Null means the route cannot attribute lag for this response.
        capped:
          type: boolean
          description: True when a response cap affected the result.
        cap:
          type:
            - integer
            - "null"
          format: int32
          description: Effective response cap when capped, otherwise null.
    AddressTokenHoldingsView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - ownerAddress
        - items
        - exact
        - truncated
        - completeness
      properties:
        chainId:
          type: string
        ownerAddress:
          type: string
        items:
          description: |
            Holdings are capped at 256 items. When `truncated` is true, older or lower-priority holdings were omitted from this response.
          type: array
          maxItems: 256
          items:
            $ref: "#/components/schemas/AddressTokenHoldingItemView"
        exact:
          description: |
            Indexed portfolio-completeness flag. This is not the same as a fresh on-chain `balanceOf` read. Treat holdings as exact only when this is true, `truncated=false`, and `completeness.reasonCode=complete`.
          type: boolean
        truncated:
          description: True when the holdings list hit the 256-item safety cap.
          type: boolean
        completeness:
          $ref: "#/components/schemas/AddressTokenHoldingsCompletenessView"
    AddressPortfolioLiveRequest:
      type: object
      additionalProperties: false
      required:
        - tokenAddresses
      properties:
        tokenAddresses:
          type: array
          minItems: 1
          maxItems: 16
          items:
            type: string
        blockTag:
          oneOf:
            - type: string
              enum:
                - latest
                - pending
            - type: "null"
    PortfolioLiveBalanceStatus:
      type: string
      enum:
        - ok
        - unsupported
        - timeout
        - error
    PortfolioLiveBalanceItemView:
      type: object
      additionalProperties: false
      required:
        - tokenAddress
        - balanceRaw
        - status
      properties:
        tokenAddress:
          type: string
        balanceRaw:
          type:
            - string
            - "null"
        status:
          $ref: "#/components/schemas/PortfolioLiveBalanceStatus"
    AddressPortfolioLiveView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - ownerAddress
        - blockTag
        - items
        - failedCount
        - partial
      properties:
        chainId:
          type: string
        ownerAddress:
          type: string
        blockTag:
          allOf:
            - $ref: "#/components/schemas/BlockReference"
        items:
          type: array
          maxItems: 16
          items:
            $ref: "#/components/schemas/PortfolioLiveBalanceItemView"
        failedCount:
          type: integer
          format: int64
        partial:
          type: boolean
    ContractSnapshotView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - address
        - summary
        - activityPage
        - transactionsPage
        - tokenHoldings
        - summaryCompleteness
        - activityCompleteness
        - holdingsCompleteness
      properties:
        chainId:
          type: string
        address:
          type: string
        summary:
          $ref: "#/components/schemas/AddressSummaryView"
        activityPage:
          $ref: "#/components/schemas/AddressActivityPage"
        transactionsPage:
          $ref: "#/components/schemas/AddressTransactionPage"
        tokenHoldings:
          $ref: "#/components/schemas/AddressTokenHoldingsView"
        summaryCompleteness:
          type: boolean
        activityCompleteness:
          type: boolean
        holdingsCompleteness:
          type: boolean
    TokenSummaryView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - tokenAddress
        - symbol
        - name
        - decimals
        - standard
        - metadataUpdatedAtIso
        - summaryVersion
        - summaryVersionUpdatedAtIso
        - summaryCacheStatus
        - summaryCacheUpdatedAtIso
        - transferCount
        - distinctFromCount
        - distinctToCount
        - latestTransferBlock
        - totalSupplyRaw
        - totalSupplySource
        - totalSupplyBlockNumber
        - totalSupplyUpdatedAtIso
      properties:
        chainId:
          type: string
        tokenAddress:
          type: string
        symbol:
          type:
            - string
            - "null"
        name:
          type:
            - string
            - "null"
        decimals:
          type:
            - integer
            - "null"
          format: int32
        standard:
          type: string
        metadataUpdatedAtIso:
          type:
            - string
            - "null"
          format: date-time
        summaryVersion:
          type: integer
          format: int64
        summaryVersionUpdatedAtIso:
          type:
            - string
            - "null"
          format: date-time
        summaryCacheStatus:
          type: string
          enum:
            - current
            - stale
            - metadata_only
            - computed
        summaryCacheUpdatedAtIso:
          type:
            - string
            - "null"
          format: date-time
        transferCount:
          type: integer
          format: int64
        distinctFromCount:
          type: integer
          format: int64
        distinctToCount:
          type: integer
          format: int64
        latestTransferBlock:
          type:
            - integer
            - "null"
          format: int64
        totalSupplyRaw:
          type:
            - string
            - "null"
          description: Decimal string from the row-backed token_supply_snapshot read model when available.
        totalSupplySource:
          type:
            - string
            - "null"
          description: Source label for the row-backed total supply snapshot.
        totalSupplyBlockNumber:
          type:
            - integer
            - "null"
          format: int64
          description: Block number associated with the total supply snapshot when available.
        totalSupplyUpdatedAtIso:
          type:
            - string
            - "null"
          format: date-time
          description: Timestamp when the total supply snapshot row was last updated.
      allOf:
        - oneOf:
            - required:
                - totalSupplyRaw
                - totalSupplySource
                - totalSupplyBlockNumber
                - totalSupplyUpdatedAtIso
              properties:
                totalSupplyRaw:
                  type: string
                totalSupplySource:
                  type: string
                totalSupplyBlockNumber:
                  type: integer
                  format: int64
                totalSupplyUpdatedAtIso:
                  type: string
                  format: date-time
            - required:
                - totalSupplyRaw
                - totalSupplySource
                - totalSupplyBlockNumber
                - totalSupplyUpdatedAtIso
              properties:
                totalSupplyRaw:
                  type: "null"
                totalSupplySource:
                  type: "null"
                totalSupplyBlockNumber:
                  type: "null"
                totalSupplyUpdatedAtIso:
                  type: "null"
    TokenBalanceOfView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - tokenAddress
        - ownerAddress
        - blockTag
        - balanceRaw
      properties:
        chainId:
          type: string
        tokenAddress:
          type: string
        ownerAddress:
          type: string
        blockTag:
          allOf:
            - $ref: "#/components/schemas/BlockReference"
          description: Echoed validated caller text used for execution (`latest`, `pending`, block number, or block hash).
        balanceRaw:
          type: string
          description: Decimal (base-10) string representation of the U256 balanceOf result.
    TokenTotalSupplyView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - tokenAddress
        - blockTag
        - totalSupplyRaw
      properties:
        chainId:
          type: string
        tokenAddress:
          type: string
        blockTag:
          allOf:
            - $ref: "#/components/schemas/BlockReference"
          description: Echoed validated caller text used for execution (`latest`, `pending`, block number, or block hash).
        totalSupplyRaw:
          type: string
          description: Decimal (base-10) string representation of the U256 totalSupply result.
    TokenHolderItem:
      type: object
      additionalProperties: false
      required:
        - rank
        - address
        - balanceRaw
        - lastUpdatedBlock
        - lastUpdatedTimestampIso
      properties:
        rank:
          type: integer
          format: int64
          description: One-based rank by descending indexed balance, then address ascending.
        address:
          type: string
        balanceRaw:
          type: string
          description: Decimal (base-10) indexed balance string.
        lastUpdatedBlock:
          type: integer
          format: int64
        lastUpdatedTimestampIso:
          type:
            - string
            - "null"
          format: date-time
    TokenHolderSnapshot:
      type: object
      additionalProperties: false
      required:
        - asOfBlock
        - source
        - freshness
      properties:
        asOfBlock:
          type:
            - integer
            - "null"
          format: int64
        source:
          type: string
          enum:
            - materialized_fungible_balances
        freshness:
          type: string
          enum:
            - head_plus_finalized
            - analytics_snapshot
    TokenHolderCompleteness:
      type: object
      additionalProperties: false
      required:
        - exact
        - truncated
        - reasonCode
      properties:
        exact:
          type: boolean
          description: True only when the holder snapshot for this response has current certification evidence.
        truncated:
          type: boolean
          description: |
            True only when the holder evidence/result was capped before a complete snapshot could be represented. Normal pagination is represented by `nextCursor` and does not make this field true.
        reasonCode:
          type: string
          enum:
            - materialized_snapshot
            - uncertified_materialized_snapshot
            - certification_not_run
            - certification_table_missing
            - revoked
            - stale
            - unavailable
            - audit_failed
            - cursor_snapshot_drift
    TokenHolderCertification:
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - status
            - validatedAgainst
            - checkedAt
            - reasonCode
          properties:
            status:
              type: string
              enum:
                - certified
            validatedAgainst:
              type: string
              enum:
                - starknet_rpc_balanceOf
            checkedAt:
              type: string
              format: date-time
            reasonCode:
              type: string
              enum:
                - materialized_snapshot
        - type: object
          additionalProperties: false
          required:
            - status
            - validatedAgainst
            - checkedAt
            - reasonCode
          properties:
            status:
              type: string
              enum:
                - uncertified
            validatedAgainst:
              type:
                - string
                - "null"
              enum:
                - starknet_rpc_balanceOf
                - null
            checkedAt:
              type:
                - string
                - "null"
              format: date-time
            reasonCode:
              type: string
              enum:
                - uncertified_materialized_snapshot
                - certification_not_run
                - certification_table_missing
        - type: object
          additionalProperties: false
          required:
            - status
            - validatedAgainst
            - checkedAt
            - reasonCode
          properties:
            status:
              type: string
              enum:
                - revoked
            validatedAgainst:
              type:
                - string
                - "null"
              enum:
                - starknet_rpc_balanceOf
                - null
            checkedAt:
              type:
                - string
                - "null"
              format: date-time
            reasonCode:
              type: string
              enum:
                - revoked
        - type: object
          additionalProperties: false
          required:
            - status
            - validatedAgainst
            - checkedAt
            - reasonCode
          properties:
            status:
              type: string
              enum:
                - stale
            validatedAgainst:
              type:
                - string
                - "null"
              enum:
                - starknet_rpc_balanceOf
                - null
            checkedAt:
              type:
                - string
                - "null"
              format: date-time
            reasonCode:
              type: string
              enum:
                - stale
        - type: object
          additionalProperties: false
          required:
            - status
            - validatedAgainst
            - checkedAt
            - reasonCode
          properties:
            status:
              type: string
              enum:
                - unavailable
            validatedAgainst:
              type:
                - string
                - "null"
              enum:
                - starknet_rpc_balanceOf
                - null
            checkedAt:
              type:
                - string
                - "null"
              format: date-time
            reasonCode:
              type: string
              enum:
                - unavailable
        - type: object
          additionalProperties: false
          required:
            - status
            - validatedAgainst
            - checkedAt
            - reasonCode
          properties:
            status:
              type: string
              enum:
                - audit_failed
            validatedAgainst:
              type:
                - string
                - "null"
              enum:
                - starknet_rpc_balanceOf
                - null
            checkedAt:
              type:
                - string
                - "null"
              format: date-time
            reasonCode:
              type: string
              enum:
                - audit_failed
    TokenHolderLimits:
      type: object
      additionalProperties: false
      required:
        - maxPageSize
        - tier
      properties:
        maxPageSize:
          type: integer
          format: int64
          maximum: 100
        tier:
          type: string
          enum:
            - partner
    TokenHolderPage:
      type: object
      additionalProperties: false
      required:
        - chainId
        - tokenAddress
        - snapshot
        - holderCount
        - holderBalanceTotalRaw
        - items
        - nextCursor
        - completeness
        - certification
        - limits
      properties:
        chainId:
          type: string
        tokenAddress:
          type: string
        snapshot:
          $ref: "#/components/schemas/TokenHolderSnapshot"
        holderCount:
          type: integer
          format: int64
        holderBalanceTotalRaw:
          type:
            - string
            - "null"
          description: Snapshot-aligned sum of positive holder balances used as the row-share denominator. Null when holder rows are redacted.
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/TokenHolderItem"
        nextCursor:
          type:
            - string
            - "null"
          description: Opaque cursor for the next holder page. Non-null means more rows are available.
        completeness:
          $ref: "#/components/schemas/TokenHolderCompleteness"
        certification:
          $ref: "#/components/schemas/TokenHolderCertification"
        limits:
          $ref: "#/components/schemas/TokenHolderLimits"
    TokenControlFact:
      type: object
      additionalProperties: false
      required:
        - status
        - actor
      properties:
        status:
          type: string
          enum:
            - fixed
            - mintable
            - minter_detected
            - pausable
            - freezable
            - blocklist_detected
            - not_detected
            - admin_detected
            - renounced
            - proxy_admin_detected
            - immutable_class
            - unknown
        actor:
          type:
            - string
            - "null"
          description: Indexed actor address when the status has a proven controlling actor.
    TokenSupplyControlFact:
      allOf:
        - $ref: "#/components/schemas/TokenControlFact"
        - type: object
          properties:
            status:
              type: string
              enum:
                - fixed
                - mintable
                - minter_detected
                - unknown
    TokenTransferControlFact:
      allOf:
        - $ref: "#/components/schemas/TokenControlFact"
        - type: object
          properties:
            status:
              type: string
              enum:
                - pausable
                - freezable
                - blocklist_detected
                - not_detected
                - unknown
    TokenMetadataAdminControlFact:
      allOf:
        - $ref: "#/components/schemas/TokenControlFact"
        - type: object
          properties:
            status:
              type: string
              enum:
                - admin_detected
                - renounced
                - unknown
    TokenUpgradeControlFact:
      allOf:
        - $ref: "#/components/schemas/TokenControlFact"
        - type: object
          properties:
            status:
              type: string
              enum:
                - proxy_admin_detected
                - immutable_class
                - unknown
    TokenControlEvidenceItem:
      type: object
      additionalProperties: true
      required:
        - kind
      properties:
        kind:
          type: string
          description: Evidence record kind, for example cached selector read, ABI scan, or operator proof.
        source:
          type:
            - string
            - "null"
        contractAddress:
          type:
            - string
            - "null"
        selector:
          type:
            - string
            - "null"
        txHash:
          type:
            - string
            - "null"
        blockNumber:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        block:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        actor:
          type:
            - string
            - "null"
        status:
          type:
            - string
            - "null"
        note:
          type:
            - string
            - "null"
    TokenControlsSnapshot:
      type: object
      additionalProperties: false
      required:
        - supplyControl
        - transferControl
        - metadataAdmin
        - upgradeControl
        - evidence
        - asOfBlock
        - source
        - indexedAtIso
      properties:
        supplyControl:
          $ref: "#/components/schemas/TokenSupplyControlFact"
        transferControl:
          $ref: "#/components/schemas/TokenTransferControlFact"
        metadataAdmin:
          $ref: "#/components/schemas/TokenMetadataAdminControlFact"
        upgradeControl:
          $ref: "#/components/schemas/TokenUpgradeControlFact"
        evidence:
          type: array
          description: Compact provenance records collected outside the request path.
          items:
            $ref: "#/components/schemas/TokenControlEvidenceItem"
        asOfBlock:
          type: integer
          format: int64
          minimum: 0
        source:
          type: string
        indexedAtIso:
          type: string
          format: date-time
    TokenControlsView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - tokenAddress
        - indexed
        - reasonCode
        - snapshot
      properties:
        chainId:
          type: string
        tokenAddress:
          type: string
        indexed:
          type: boolean
        reasonCode:
          type: string
          enum:
            - materialized_controls_snapshot
            - controls_snapshot_missing
        snapshot:
          oneOf:
            - $ref: "#/components/schemas/TokenControlsSnapshot"
            - type: "null"
    TokenMarketPoolItem:
      type: object
      additionalProperties: false
      required:
        - marketId
        - marketKind
        - poolKey
        - displayName
        - protocolSlug
        - protocolName
        - poolType
        - dex
        - poolAddress
        - pairedTokenAddress
        - pairedTokenSymbol
        - feeBps
        - priceUsd
        - tvlUsd
        - volume24hUsd
        - volume24hPrevUsd
        - volume24hChangeBps
        - volumeWindowStartUnix
        - volumeWindowEndUnix
        - trades24h
        - traders24h
        - lastTradeBlock
        - snapshotBlock
        - source
        - updatedAtIso
      properties:
        marketId:
          type: string
          description: Stable market identity. For singleton protocols this can identify a market inside the same pool contract.
        marketKind:
          type: string
          enum:
            - pool_contract
            - singleton_pool
            - orderbook
        poolKey:
          type:
            - string
            - "null"
          description: Protocol-native pool or market key when distinct from the contract address.
        displayName:
          type:
            - string
            - "null"
          description: Human label for the market when materialized offline.
        protocolSlug:
          type:
            - string
            - "null"
        protocolName:
          type: string
        poolType:
          type:
            - string
            - "null"
          enum:
            - cl
            - cpmm
            - stable
            - orderbook
            - unknown
            - null
        dex:
          type: string
          description: Legacy DEX label retained for compatibility; prefer protocolName/protocolSlug for new clients.
        poolAddress:
          type: string
        pairedTokenAddress:
          type:
            - string
            - "null"
        pairedTokenSymbol:
          type:
            - string
            - "null"
        feeBps:
          type:
            - integer
            - "null"
          format: int32
          minimum: 0
        priceUsd:
          type:
            - string
            - "null"
          description: Decimal USD price string from the materialized snapshot.
        tvlUsd:
          type:
            - string
            - "null"
          description: Decimal USD TVL string from the materialized snapshot.
          pattern: ^[0-9]+(\.[0-9]+)?$
        volume24hUsd:
          type:
            - string
            - "null"
          description: Decimal USD 24h volume string from the materialized snapshot.
          pattern: ^[0-9]+(\.[0-9]+)?$
        volume24hPrevUsd:
          type:
            - string
            - "null"
          description: Decimal USD previous-window 24h volume used for delta display.
        volume24hChangeBps:
          type:
            - integer
            - "null"
          format: int32
          description: Signed basis-point change from previous 24h volume to current 24h volume.
        volumeWindowStartUnix:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: Unix timestamp for the inclusive start of the indexed 24h metric window.
        volumeWindowEndUnix:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: Unix timestamp for the exclusive end of the indexed 24h metric window.
        trades24h:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        traders24h:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        lastTradeBlock:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        snapshotBlock:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        source:
          type: string
        updatedAtIso:
          type: string
          format: date-time
    TokenMarketPoolCoverage:
      type: object
      additionalProperties: false
      required:
        - exact
        - reasonCode
      properties:
        exact:
          type: boolean
        reasonCode:
          type: string
          enum:
            - materialized_pool_snapshot
            - pool_snapshot_missing
            - pool_rollup_missing
    TokenMarketPoolLimits:
      type: object
      additionalProperties: false
      required:
        - maxPageSize
        - tier
      properties:
        maxPageSize:
          type: integer
          format: int64
          maximum: 100
        tier:
          type: string
          enum:
            - partner
    TokenMarketPoolPage:
      type: object
      additionalProperties: false
      required:
        - chainId
        - tokenAddress
        - totalPairs
        - totalTvlUsd
        - totalVolume24hUsd
        - snapshotBlock
        - updatedAtIso
        - volumeWindowStartUnix
        - volumeWindowEndUnix
        - items
        - coverage
        - limits
      properties:
        chainId:
          type: string
        tokenAddress:
          type: string
        totalPairs:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        totalTvlUsd:
          type:
            - string
            - "null"
          description: Indexed total TVL from the materialized token market pool rollup for this token, or null when that rollup value is not materialized.
        totalVolume24hUsd:
          type:
            - string
            - "null"
          description: Indexed total 24h volume from the materialized token market pool rollup for this token, or null when that rollup window is not materialized.
        snapshotBlock:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: Highest pool snapshot block included in the token-level rollup.
        updatedAtIso:
          type:
            - string
            - "null"
          format: date-time
          description: Latest indexed pool snapshot timestamp included in the token-level rollup.
        volumeWindowStartUnix:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: Earliest imported 24h metric window start across pool rows in the rollup.
        volumeWindowEndUnix:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: Latest imported 24h metric window end across pool rows in the rollup.
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/TokenMarketPoolItem"
        coverage:
          $ref: "#/components/schemas/TokenMarketPoolCoverage"
        limits:
          $ref: "#/components/schemas/TokenMarketPoolLimits"
    TokenHolderTierDistributionItem:
      type: object
      additionalProperties: false
      required:
        - tier
        - minShareBps
        - holderCount
        - shareBps
      properties:
        tier:
          type: string
        minShareBps:
          type: integer
          format: int64
        holderCount:
          type: integer
          format: int64
        shareBps:
          type: integer
          format: int64
    TokenHolderThresholdCountItem:
      type: object
      additionalProperties: false
      required:
        - label
        - thresholdBps
        - holderCount
      properties:
        label:
          type: string
        thresholdBps:
          type: integer
          format: int64
        holderCount:
          type: integer
          format: int64
    TokenHolderAnalyticsMetrics:
      type: object
      additionalProperties: false
      required:
        - holderBalanceTotalRaw
        - top5BalanceRaw
        - top10BalanceRaw
        - top100BalanceRaw
        - top5ShareBps
        - top10ShareBps
        - top100ShareBps
        - whaleCount
        - whaleShareBps
        - giniScorePpm
        - nakamoto50Count
        - holdersAbove1Percent
        - tierDistribution
        - thresholdCounts
      properties:
        holderBalanceTotalRaw:
          type: string
        top5BalanceRaw:
          type: string
        top10BalanceRaw:
          type: string
        top100BalanceRaw:
          type: string
        top5ShareBps:
          type: integer
          format: int64
        top10ShareBps:
          type: integer
          format: int64
        top100ShareBps:
          type: integer
          format: int64
        whaleCount:
          type: integer
          format: int64
        whaleShareBps:
          type: integer
          format: int64
        giniScorePpm:
          type: integer
          format: int64
        nakamoto50Count:
          type:
            - integer
            - "null"
          format: int64
        holdersAbove1Percent:
          type: integer
          format: int64
        tierDistribution:
          type: array
          maxItems: 4
          description: Fixed four-bucket holder concentration distribution.
          items:
            $ref: "#/components/schemas/TokenHolderTierDistributionItem"
        thresholdCounts:
          type: array
          maxItems: 3
          description: Fixed three-threshold holder counts for >=1%, >=0.1%, and >=0.01%.
          items:
            $ref: "#/components/schemas/TokenHolderThresholdCountItem"
    TokenHolderAnalyticsSnapshot:
      type: object
      additionalProperties: false
      required:
        - chainId
        - tokenAddress
        - snapshot
        - holderCount
        - computedAt
        - metrics
        - completeness
      properties:
        chainId:
          type: string
        tokenAddress:
          type: string
        snapshot:
          $ref: "#/components/schemas/TokenHolderSnapshot"
        holderCount:
          type: integer
          format: int64
        computedAt:
          type:
            - string
            - "null"
          format: date-time
        metrics:
          oneOf:
            - $ref: "#/components/schemas/TokenHolderAnalyticsMetrics"
            - type: "null"
        completeness:
          $ref: "#/components/schemas/TokenHolderCompleteness"
    SelfServeApiRateLimitPolicySummary:
      type: object
      additionalProperties: false
      required:
        - policyKey
        - policyDisplayName
        - lightPerMinute
        - heavyPerMinute
        - burst
        - maxActiveKeys
      properties:
        policyKey:
          type: string
        policyDisplayName:
          type: string
        lightPerMinute:
          type: integer
          format: int64
        heavyPerMinute:
          type: integer
          format: int64
        burst:
          type: integer
          format: int64
        maxActiveKeys:
          type: integer
          format: int64
    SelfServeApiKeySummary:
      type: object
      additionalProperties: false
      required:
        - publicId
        - label
        - environment
        - scopes
        - status
        - secretHint
        - maskedKey
        - rateLimitPolicy
        - createdAt
        - lastUsedAt
        - expiresAt
        - revokedAt
      properties:
        publicId:
          type: string
        label:
          type: string
        environment:
          type: string
          enum:
            - test
            - live
        scopes:
          type: array
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
              - read
              - batch
        status:
          type: string
          enum:
            - active
            - revoked
        secretHint:
          type: string
        maskedKey:
          type: string
        rateLimitPolicy:
          $ref: "#/components/schemas/SelfServeApiRateLimitPolicySummary"
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type:
            - string
            - "null"
          format: date-time
        expiresAt:
          type:
            - string
            - "null"
          format: date-time
        revokedAt:
          type:
            - string
            - "null"
          format: date-time
    SelfServeIssueApiKeyResult:
      type: object
      additionalProperties: false
      required:
        - action
        - plaintextKey
        - apiKey
        - revokedPublicIds
      properties:
        action:
          type: string
          enum:
            - created
            - rotated
        plaintextKey:
          type: string
        apiKey:
          $ref: "#/components/schemas/SelfServeApiKeySummary"
        revokedPublicIds:
          type: array
          maxItems: 1
          items:
            type: string
    SelfServeRateLimitState:
      type: object
      additionalProperties: false
      required:
        - loadClass
        - limitPerMinute
        - remaining
        - policy
        - retryAfterSeconds
        - observedAt
      properties:
        loadClass:
          type: string
        limitPerMinute:
          type: integer
          format: int64
        remaining:
          type: integer
          format: int64
        policy:
          type: string
        retryAfterSeconds:
          type:
            - integer
            - "null"
          format: int64
        observedAt:
          type: string
          format: date-time
    SelfServeUsageEvent:
      type: object
      additionalProperties: false
      required:
        - requestId
        - apiKeyPublicId
        - apiKeyLabel
        - apiKeyEnvironment
        - apiKeyScopes
        - method
        - routePath
        - loadClass
        - statusCode
        - latencyMs
        - rateLimitState
        - observedAt
      properties:
        requestId:
          type: string
        apiKeyPublicId:
          type: string
        apiKeyLabel:
          type: string
        apiKeyEnvironment:
          type: string
          enum:
            - test
            - live
        apiKeyScopes:
          type: array
          maxItems: 2
          uniqueItems: true
          items:
            type: string
            enum:
              - read
              - batch
        method:
          type: string
        routePath:
          type: string
        loadClass:
          type: string
        statusCode:
          type: integer
          format: int64
        latencyMs:
          oneOf:
            - type: integer
              format: int64
              minimum: 0
            - type: "null"
        rateLimitState:
          oneOf:
            - $ref: "#/components/schemas/SelfServeRateLimitState"
            - type: "null"
        observedAt:
          type: string
          format: date-time
    SelfServePerKeyUsage:
      type: object
      additionalProperties: false
      required:
        - apiKey
        - totalRequests
        - successCount
        - failureCount
        - lastRequestAt
        - lastFailureAt
        - latestRateLimitState
      properties:
        apiKey:
          $ref: "#/components/schemas/SelfServeApiKeySummary"
        totalRequests:
          type: integer
          format: int64
        successCount:
          type: integer
          format: int64
        failureCount:
          type: integer
          format: int64
        lastRequestAt:
          type:
            - string
            - "null"
          format: date-time
        lastFailureAt:
          type:
            - string
            - "null"
          format: date-time
        latestRateLimitState:
          oneOf:
            - $ref: "#/components/schemas/SelfServeRateLimitState"
            - type: "null"
    SelfServeUsageSnapshot:
      type: object
      additionalProperties: false
      required:
        - windowStart
        - windowEnd
        - totalRequests
        - totalFailures
        - perKey
        - perKeyTruncated
        - recentRequests
        - recentRequestsTruncated
        - recentFailures
        - recentFailuresTruncated
      properties:
        windowStart:
          type: string
          format: date-time
        windowEnd:
          type: string
          format: date-time
        totalRequests:
          type: integer
          format: int64
        totalFailures:
          type: integer
          format: int64
        perKey:
          type: array
          maxItems: 100
          description: Per-key aggregates for the bounded recent usage window.
          items:
            $ref: "#/components/schemas/SelfServePerKeyUsage"
        perKeyTruncated:
          type: boolean
          description: True when older keys fell outside the bounded per-key window.
        recentRequests:
          type: array
          maxItems: 100
          description: Most recent request events in the bounded usage window.
          items:
            $ref: "#/components/schemas/SelfServeUsageEvent"
        recentRequestsTruncated:
          type: boolean
          description: True when more recent request events exist outside the returned slice.
        recentFailures:
          type: array
          maxItems: 25
          description: Most recent failure events in the bounded usage window.
          items:
            $ref: "#/components/schemas/SelfServeUsageEvent"
        recentFailuresTruncated:
          type: boolean
          description: True when more failure events exist outside the returned slice.
    SelfServeApiKeyListResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - truncated
      properties:
        items:
          type: array
          maxItems: 100
          description: Newest-first self-serve API key metadata slice for the authenticated workspace.
          items:
            $ref: "#/components/schemas/SelfServeApiKeySummary"
        truncated:
          type: boolean
          description: True when older historical keys exist outside the returned slice.
    SelfServeApiKeyDeleteResponse:
      type: object
      additionalProperties: false
      required:
        - apiKey
      properties:
        apiKey:
          $ref: "#/components/schemas/SelfServeApiKeySummary"
    TokenTransferActionContext:
      type: object
      additionalProperties: false
      required:
        - actionKind
        - actionLabel
        - methodLabel
        - protocolSlug
        - protocolName
        - reasonCode
        - confidence
        - isInternalRouting
        - source
        - indexedAt
      properties:
        actionKind:
          type: string
          enum:
            - transfer
            - mint
            - burn
            - swap_leg
            - bridge_leg
            - lp_add
            - lp_remove
            - fee
            - internal_routing
            - unknown
        actionLabel:
          type: string
        methodLabel:
          type:
            - string
            - "null"
        protocolSlug:
          type:
            - string
            - "null"
        protocolName:
          type:
            - string
            - "null"
        reasonCode:
          type: string
        confidence:
          type: string
          enum:
            - exact
            - partial
            - heuristic
            - unknown
        isInternalRouting:
          type: boolean
        source:
          type: string
        indexedAt:
          type:
            - string
            - "null"
          format: date-time
    TokenTransferItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - timestampIso
        - txIndex
        - logIndex
        - transferIndex
        - txHash
        - fromAddress
        - toAddress
        - amount
        - rawValue
        - tokenId
        - standard
        - tokenSymbol
        - tokenName
        - tokenDecimals
        - actionContext
        - historicalUsd
        - sourceTier
      properties:
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        transferIndex:
          type: integer
          format: int32
        txHash:
          type: string
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        amount:
          type:
            - string
            - "null"
        rawValue:
          type:
            - string
            - "null"
        tokenId:
          type:
            - string
            - "null"
        standard:
          type: string
        tokenSymbol:
          type:
            - string
            - "null"
          description: Indexed or reviewed token symbol for display; null when unavailable.
        tokenName:
          type:
            - string
            - "null"
          description: Indexed or reviewed token display name; null when unavailable.
        tokenDecimals:
          type:
            - integer
            - "null"
          format: int32
          minimum: -2147483648
          maximum: 2147483647
          description: Indexed or reviewed token decimals for amount formatting; null when unavailable.
        actionContext:
          oneOf:
            - $ref: "#/components/schemas/TokenTransferActionContext"
            - type: "null"
        historicalUsd:
          description: Indexed transaction-time USD valuation when materialized; null when no priced historical fact is available. Do not treat this as a live/current market price.
          oneOf:
            - $ref: "#/components/schemas/TokenTransferHistoricalUsd"
            - type: "null"
        sourceTier:
          type: string
          enum:
            - head
            - finalized
    TokenTransferPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/TokenTransferItem"
        nextCursor:
          type:
            - string
            - "null"
    GlobalTransferItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - timestampIso
        - txIndex
        - logIndex
        - transferIndex
        - txHash
        - tokenAddress
        - fromAddress
        - toAddress
        - amount
        - rawValue
        - tokenId
        - standard
        - tokenSymbol
        - tokenName
        - tokenDecimals
        - sourceTier
        - actionContext
      properties:
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        transferIndex:
          type: integer
          format: int32
        txHash:
          type: string
        tokenAddress:
          type: string
        fromAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        amount:
          type:
            - string
            - "null"
        rawValue:
          type:
            - string
            - "null"
        tokenId:
          type:
            - string
            - "null"
        standard:
          type: string
        tokenSymbol:
          type:
            - string
            - "null"
          description: Indexed or reviewed token symbol for display; null when unavailable.
        tokenName:
          type:
            - string
            - "null"
          description: Indexed or reviewed token display name; null when unavailable.
        tokenDecimals:
          type:
            - integer
            - "null"
          format: int32
          minimum: -2147483648
          maximum: 2147483647
          description: Indexed or reviewed token decimals for amount formatting; null when unavailable.
        sourceTier:
          type: string
          enum:
            - head
            - finalized
        actionContext:
          oneOf:
            - $ref: "#/components/schemas/TokenTransferActionContext"
            - type: "null"
    GlobalTransferPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/GlobalTransferItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$
    GlobalEventItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - timestampIso
        - txIndex
        - logIndex
        - txHash
        - address
        - topic0
        - topic1
        - topic2
        - topic3
        - data
        - sourceTier
      properties:
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        txHash:
          type: string
        address:
          type: string
        topic0:
          type:
            - string
            - "null"
        topic1:
          type:
            - string
            - "null"
        topic2:
          type:
            - string
            - "null"
        topic3:
          type:
            - string
            - "null"
        data:
          type: array
          maxItems: 1024
          items:
            type: string
        eventName:
          type:
            - string
            - "null"
          description: Reviewed or ABI-derived event name when Starkscan can attribute topic0.
        eventNameSource:
          type:
            - string
            - "null"
          description: Attribution source for eventName. Current values include verified_abi, class_abi, selector_unique, and curated_selector; clients should treat unknown strings as forward-compatible provenance labels.
        eventNameUnavailableReason:
          type:
            - string
            - "null"
          enum:
            - event_time_class_epoch_unavailable
            - null
          description: Reason eventName is omitted even though Starkscan has contract-scoped epoch facts for this event. Raw topic/data fields remain authoritative.
        decodedFields:
          type: array
          maxItems: 128
          items:
            $ref: "#/components/schemas/EventDecodedField"
          description: Best-effort decoded key/data fields when Starkscan has an exact materialized ABI schema match for this event. Raw topic/data fields remain authoritative.
        decodedFieldsSource:
          type:
            - string
            - "null"
          description: Attribution source used for decodedFields when present.
        decodedFieldsUnavailableReason:
          type:
            - string
            - "null"
          enum:
            - schema_unavailable
            - selector_only_attribution
            - payload_shape_mismatch
            - schema_shape_unsupported
            - null
          description: Reason decodedFields is omitted for an attributed event. Selector-only attribution names the event but does not prove the field layout; raw topic/data fields remain authoritative.
        sourceTier:
          type: string
          enum:
            - head
            - finalized
    GlobalEventPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/GlobalEventItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+$
    StrkbtcShieldEventItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - txIndex
        - logIndex
        - txHash
        - contractAddress
        - topic0
        - direction
        - commitmentOrNullifier
        - publicAmount
      properties:
        blockNumber:
          type: integer
          format: int64
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        txHash:
          type: string
        contractAddress:
          type: string
        topic0:
          type: string
        direction:
          type: string
          enum:
            - shield
            - unshield
        commitmentOrNullifier:
          type: string
        publicAmount:
          type:
            - string
            - "null"
    StrkbtcShieldEventPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/StrkbtcShieldEventItem"
        nextCursor:
          type:
            - string
            - "null"
    StrkbtcCommitmentItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - txIndex
        - logIndex
        - txHash
        - commitmentHash
      properties:
        blockNumber:
          type: integer
          format: int64
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        txHash:
          type: string
        commitmentHash:
          type: string
    StrkbtcCommitmentPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/StrkbtcCommitmentItem"
        nextCursor:
          type:
            - string
            - "null"
    StrkbtcNullifierItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - txIndex
        - logIndex
        - txHash
        - nullifierHash
      properties:
        blockNumber:
          type: integer
          format: int64
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        txHash:
          type: string
        nullifierHash:
          type: string
    StrkbtcNullifierPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/StrkbtcNullifierItem"
        nextCursor:
          type:
            - string
            - "null"
    StrkbtcPoolStatusView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - commitmentCount
        - nullifierCount
        - netOpenCount
        - version
        - updatedAtIso
      properties:
        chainId:
          type: string
        commitmentCount:
          type: integer
          format: int64
        nullifierCount:
          type: integer
          format: int64
        netOpenCount:
          type: integer
          format: int64
        version:
          type: integer
          format: int64
        updatedAtIso:
          type: string
    PrivacyPoolPublicVisibility:
      type: string
      enum:
        - public
        - partial
        - hidden_by_design
    PrivacyPoolTokenView:
      type: object
      additionalProperties: false
      required:
        - address
        - symbol
        - name
        - decimals
      properties:
        address:
          type: string
        symbol:
          type:
            - string
            - "null"
        name:
          type:
            - string
            - "null"
        decimals:
          type:
            - integer
            - "null"
          format: int32
    PrivacyPoolPublicFieldsView:
      type: object
      additionalProperties: false
      required:
        - visibility
        - actorAddress
        - toAddress
        - token
        - amountRaw
        - noteId
        - nullifier
        - auditorPublicKey
      properties:
        visibility:
          $ref: "#/components/schemas/PrivacyPoolPublicVisibility"
        actorAddress:
          type:
            - string
            - "null"
        toAddress:
          type:
            - string
            - "null"
        token:
          oneOf:
            - $ref: "#/components/schemas/PrivacyPoolTokenView"
            - type: "null"
        amountRaw:
          type:
            - string
            - "null"
        noteId:
          type:
            - string
            - "null"
        nullifier:
          type:
            - string
            - "null"
        auditorPublicKey:
          type:
            - string
            - "null"
    PrivacyPoolFeeEvidenceView:
      type: object
      additionalProperties: false
      required:
        - tokenAddress
        - amountRaw
        - collectorAddress
        - transferLogIndex
        - transferIndex
        - feeCollectorConfigBlockNumber
        - feeCollectorConfigTxIndex
        - feeCollectorConfigLogIndex
        - feeAmountConfigBlockNumber
        - feeAmountConfigTxIndex
        - feeAmountConfigLogIndex
      properties:
        tokenAddress:
          type: string
        amountRaw:
          type: string
        collectorAddress:
          type: string
        transferLogIndex:
          type: integer
          format: int32
        transferIndex:
          type: integer
          format: int32
        feeCollectorConfigBlockNumber:
          type: integer
          format: int64
        feeCollectorConfigTxIndex:
          type: integer
          format: int32
        feeCollectorConfigLogIndex:
          type: integer
          format: int32
        feeAmountConfigBlockNumber:
          type: integer
          format: int64
        feeAmountConfigTxIndex:
          type: integer
          format: int32
        feeAmountConfigLogIndex:
          type: integer
          format: int32
    PrivacyPoolEventItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - timestampIso
        - txIndex
        - logIndex
        - txHash
        - contractAddress
        - topic0
        - eventName
        - key1
        - key2
        - data0
        - data1
        - data2
        - keys
        - data
        - publicFields
        - privacyFees
      properties:
        blockNumber:
          type: integer
          format: int64
        timestampIso:
          type:
            - string
            - "null"
          format: date-time
          description: UTC block timestamp when the indexed block is available.
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        txHash:
          type: string
        contractAddress:
          type: string
        topic0:
          type: string
        eventName:
          type: string
          description: Indexed snake_case privacy-pool event name.
          maxLength: 32
          pattern: ^[a-z0-9_]+$
          examples:
            - deposit
            - withdrawal
            - proof_validity_blocks_set
            - protocol_event
        key1:
          type:
            - string
            - "null"
        key2:
          type:
            - string
            - "null"
        data0:
          type:
            - string
            - "null"
        data1:
          type:
            - string
            - "null"
        data2:
          type:
            - string
            - "null"
        keys:
          type: array
          description: Raw Starknet event keys as stored by the indexer. Payload-backed rows expose the full receipt keys array with the selector at index 0. Legacy rows without payload arrays expose only the indexed selector/key subset and must not be treated as receipt-complete evidence until verified against the transaction receipt.
          minItems: 1
          maxItems: 1024
          items:
            type: string
        data:
          type: array
          description: Raw Starknet event data as stored by the indexer. Payload-backed rows expose the full receipt data array. Legacy rows without payload arrays expose only the indexed data subset and must not be treated as receipt-complete evidence until verified against the transaction receipt.
          maxItems: 1024
          items:
            type: string
        publicFields:
          $ref: "#/components/schemas/PrivacyPoolPublicFieldsView"
        privacyFees:
          type: array
          description: Public fee-transfer evidence for the same transaction, deduped per Activity row; empty when no configured privacy-pool fee transfer is present.
          maxItems: 64
          items:
            $ref: "#/components/schemas/PrivacyPoolFeeEvidenceView"
    PrivacyPoolEventPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/PrivacyPoolEventItem"
        nextCursor:
          type:
            - string
            - "null"
    PrivacyPoolCommitmentFactItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - txIndex
        - logIndex
        - txHash
        - poolContractAddress
        - eventName
        - commitmentHash
        - tokenAddress
        - amountRaw
      properties:
        blockNumber:
          type: integer
          format: int64
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        txHash:
          type: string
        poolContractAddress:
          type: string
        eventName:
          type: string
        commitmentHash:
          type: string
        tokenAddress:
          type:
            - string
            - "null"
        amountRaw:
          type:
            - string
            - "null"
    PrivacyPoolCommitmentFactPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/PrivacyPoolCommitmentFactItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+$
    PrivacyPoolNullifierFactItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - txIndex
        - logIndex
        - txHash
        - poolContractAddress
        - eventName
        - nullifierHash
      properties:
        blockNumber:
          type: integer
          format: int64
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        txHash:
          type: string
        poolContractAddress:
          type: string
        eventName:
          type: string
        nullifierHash:
          type: string
    PrivacyPoolNullifierFactPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/PrivacyPoolNullifierFactItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+$
    PrivacyPoolRootFactItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - txIndex
        - logIndex
        - txHash
        - poolContractAddress
        - eventName
        - rootHash
        - treeSize
      properties:
        blockNumber:
          type: integer
          format: int64
        txIndex:
          type: integer
          format: int32
        logIndex:
          type: integer
          format: int32
        txHash:
          type: string
        poolContractAddress:
          type: string
        eventName:
          type: string
        rootHash:
          type: string
        treeSize:
          type:
            - string
            - "null"
    PrivacyPoolRootFactPage:
      type: object
      additionalProperties: false
      required:
        - items
        - nextCursor
      properties:
        items:
          type: array
          maxItems: 100
          items:
            $ref: "#/components/schemas/PrivacyPoolRootFactItem"
        nextCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+$
    PrivacyPoolStatusView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - totalEvents
        - depositCount
        - withdrawalCount
        - openNoteCreatedCount
        - openNoteDepositedCount
        - encNoteCreatedCount
        - noteUsedCount
        - auditorPublicKeySetCount
        - viewingKeySetCount
        - registeredUserCount
        - noteState
        - eventBreakdown
        - latestEventBlock
        - latestEventTxIndex
        - latestEventLogIndex
        - latestEventCursor
        - latestDecodedEventBlock
        - latestDecodedEventTxIndex
        - latestDecodedEventLogIndex
        - latestDecodedEventCursor
        - latestRawEventBlock
        - latestRawEventTxIndex
        - latestRawEventLogIndex
        - latestRawEventCursor
        - eventLagBlocks
        - materializationFresh
      properties:
        chainId:
          type: string
        totalEvents:
          type: integer
          format: int64
        depositCount:
          type: integer
          format: int64
        withdrawalCount:
          type: integer
          format: int64
        openNoteCreatedCount:
          type: integer
          format: int64
        openNoteDepositedCount:
          type: integer
          format: int64
        encNoteCreatedCount:
          type: integer
          format: int64
        noteUsedCount:
          type: integer
          format: int64
        auditorPublicKeySetCount:
          type: integer
          format: int64
        viewingKeySetCount:
          type: integer
          format: int64
          description: Number of indexed public ViewingKeySet event rows.
        registeredUserCount:
          type: integer
          format: int64
          description: Distinct public user addresses that registered a viewing key.
        noteState:
          $ref: "#/components/schemas/PrivacyPoolNoteStateView"
        eventBreakdown:
          type: array
          description: Complete partition of indexed privacy-pool events by event name.
          items:
            $ref: "#/components/schemas/PrivacyPoolCountView"
        latestEventBlock:
          type:
            - integer
            - "null"
          format: int64
          description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event block.
        latestEventTxIndex:
          type:
            - integer
            - "null"
          format: int32
          description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event transaction index.
        latestEventLogIndex:
          type:
            - integer
            - "null"
          format: int32
          description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event log index.
        latestEventCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+$
          description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event cursor as block:tx:log.
        latestDecodedEventBlock:
          type:
            - integer
            - "null"
          format: int64
          description: Latest privacy-pool event block that has passed decoding and materialization.
        latestDecodedEventTxIndex:
          type:
            - integer
            - "null"
          format: int32
          description: Transaction index component of the latest decoded/materialized privacy-pool event cursor.
        latestDecodedEventLogIndex:
          type:
            - integer
            - "null"
          format: int32
          description: Log index component of the latest decoded/materialized privacy-pool event cursor.
        latestDecodedEventCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+$
          description: Exact latest decoded/materialized privacy-pool event cursor as block:tx:log.
        latestRawEventBlock:
          type:
            - integer
            - "null"
          format: int64
          description: Latest raw privacy-pool contract event block observed by the source-event filter, when available.
        latestRawEventTxIndex:
          type:
            - integer
            - "null"
          format: int32
          description: Transaction index component of the latest raw privacy-pool source-event cursor, when available.
        latestRawEventLogIndex:
          type:
            - integer
            - "null"
          format: int32
          description: Log index component of the latest raw privacy-pool source-event cursor, when available.
        latestRawEventCursor:
          type:
            - string
            - "null"
          pattern: ^[0-9]+:[0-9]+:[0-9]+$
          description: Exact latest raw privacy-pool source-event cursor as block:tx:log, when available.
        eventLagBlocks:
          type:
            - integer
            - "null"
          format: int64
          description: Raw-event block minus decoded/materialized event block when the raw source-event filter is available.
        materializationFresh:
          type:
            - boolean
            - "null"
          description: True when decoded privacy-pool materialization is caught up with raw event evidence; null when no raw source-event filter is configured.
    PrivacyPoolNoteStateView:
      type: object
      additionalProperties: false
      required:
        - commitmentCount
        - nullifierCount
        - openNoteCreatedCount
        - openNoteDepositedCount
        - encNoteCreatedCount
        - noteUsedCount
        - spentNoteProxyCount
        - unspentNoteProxyCount
        - source
        - caveat
      properties:
        commitmentCount:
          type: integer
          format: int64
          minimum: 0
          description: Count of public commitment facts indexed for the pool.
        nullifierCount:
          type: integer
          format: int64
          minimum: 0
          description: Count of public nullifier facts indexed for the pool.
        openNoteCreatedCount:
          type: integer
          format: int64
          minimum: 0
        openNoteDepositedCount:
          type: integer
          format: int64
          minimum: 0
        encNoteCreatedCount:
          type: integer
          format: int64
          minimum: 0
        noteUsedCount:
          type: integer
          format: int64
          minimum: 0
        spentNoteProxyCount:
          type: integer
          format: int64
          minimum: 0
          description: Public spent-note proxy equal to the nullifier count; notes are not linked.
        unspentNoteProxyCount:
          type: integer
          format: int64
          minimum: 0
          description: Public unspent-note proxy computed as commitments minus nullifiers, floored at zero.
        source:
          type: string
          enum:
            - public_decoded_event_rows
        caveat:
          type: string
          const: Public note/nullifier proxy only; not exact anonymity k; exact anonymity requires root-time state and denomination semantics.
          description: Explicit caveat that this is not exact anonymity k.
    PrivacyPoolCountView:
      type: object
      additionalProperties: false
      required:
        - name
        - count
      properties:
        name:
          type: string
          maxLength: 32
          pattern: ^[a-z0-9_]+$
          description: |
            Breakdown bucket name. Event breakdowns use indexed privacy-pool snake_case event names; visibility breakdowns use `public`, `partial`, or `hidden_by_design`.
          examples:
            - deposit
            - protocol_event
            - hidden_by_design
        count:
          type: integer
          format: int64
    PrivacyPoolTokenFlowView:
      type: object
      additionalProperties: false
      required:
        - token
        - eventCount
        - depositEventCount
        - withdrawalEventCount
        - observableDepositAmountRaw
        - observableWithdrawalAmountRaw
        - observableNetAmountRaw
        - missingAmountEventCount
      properties:
        token:
          $ref: "#/components/schemas/PrivacyPoolTokenView"
        eventCount:
          type: integer
          format: int64
        depositEventCount:
          type: integer
          format: int64
        withdrawalEventCount:
          type: integer
          format: int64
        observableDepositAmountRaw:
          type: string
        observableWithdrawalAmountRaw:
          type: string
        observableNetAmountRaw:
          type: string
        missingAmountEventCount:
          type: integer
          format: int64
    PrivacyPoolUnavailableMetricView:
      type: object
      additionalProperties: false
      required:
        - metric
        - reasonCode
        - reason
      properties:
        metric:
          type: string
          enum:
            - tvlUsd
            - privateSwapVolume
            - exactAnonymitySet
        reasonCode:
          type: string
          enum:
            - requires_balance_and_price_snapshots
            - volume_pricing_not_certified
            - commitment_state_materializer_required
        reason:
          type: string
    PrivacyPoolMetricBucketItem:
      type: object
      additionalProperties: false
      required:
        - bucketStartIso
        - bucketGranularity
        - newViewingKeyWallets
        - cumulativeViewingKeyWallets
        - visibleDeposits
        - visibleWithdrawals
        - noteUsedEvents
        - latestBlockNumber
      properties:
        bucketStartIso:
          type: string
          format: date-time
        bucketGranularity:
          type: string
          enum:
            - day
        newViewingKeyWallets:
          type: integer
          format: int64
          minimum: 0
        cumulativeViewingKeyWallets:
          type: integer
          format: int64
          minimum: 0
        visibleDeposits:
          type: integer
          format: int64
          minimum: 0
        visibleWithdrawals:
          type: integer
          format: int64
          minimum: 0
        noteUsedEvents:
          type: integer
          format: int64
          minimum: 0
        latestBlockNumber:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
    PrivacyPoolMetricBucketPage:
      type: object
      additionalProperties: false
      required:
        - chainId
        - bucketGranularity
        - items
      properties:
        chainId:
          type: string
        bucketGranularity:
          type: string
          enum:
            - day
        items:
          type: array
          maxItems: 90
          items:
            $ref: "#/components/schemas/PrivacyPoolMetricBucketItem"
    PrivacyPoolWalletMetricSeriesItem:
      type: object
      additionalProperties: false
      required:
        - bucketStartIso
        - bucketGranularity
        - newViewingKeyWallets
        - cumulativeViewingKeyWallets
        - latestBlockNumber
      properties:
        bucketStartIso:
          type: string
          format: date-time
        bucketGranularity:
          type: string
          enum:
            - hour
            - day
            - week
        newViewingKeyWallets:
          type: integer
          format: int64
          minimum: 0
        cumulativeViewingKeyWallets:
          type: integer
          format: int64
          minimum: 0
        latestBlockNumber:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
    PrivacyPoolShieldedSupplySeriesItem:
      type: object
      additionalProperties: false
      required:
        - bucketStartIso
        - bucketGranularity
        - tokenAddress
        - depositedRaw
        - withdrawnRaw
        - shieldedSupplyRaw
        - latestBlockNumber
      properties:
        bucketStartIso:
          type: string
          format: date-time
        bucketGranularity:
          type: string
          enum:
            - hour
            - day
            - week
        tokenAddress:
          type: string
        depositedRaw:
          type: string
          pattern: ^[0-9]+$
          maxLength: 80
        withdrawnRaw:
          type: string
          pattern: ^[0-9]+$
          maxLength: 80
        shieldedSupplyRaw:
          type: string
          pattern: ^[0-9]+$
          maxLength: 80
        latestBlockNumber:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
    PrivacyPoolFeeMetricSeriesItem:
      type: object
      additionalProperties: false
      required:
        - bucketStartIso
        - bucketGranularity
        - tokenAddress
        - feeAmountRaw
        - cumulativeFeeAmountRaw
        - feeTransferCount
        - latestBlockNumber
      properties:
        bucketStartIso:
          type: string
          format: date-time
        bucketGranularity:
          type: string
          enum:
            - hour
            - day
            - week
        tokenAddress:
          type: string
        feeAmountRaw:
          type: string
          pattern: ^[0-9]+$
          maxLength: 80
        cumulativeFeeAmountRaw:
          type: string
          pattern: ^[0-9]+$
          maxLength: 80
        feeTransferCount:
          type: integer
          format: int64
          minimum: 0
        latestBlockNumber:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
    PrivacyPoolMetricSeriesPage:
      type: object
      additionalProperties: false
      required:
        - chainId
        - range
        - bucketGranularity
        - token
        - walletSeries
        - shieldedSupplySeries
        - privacyFeeSeries
      properties:
        chainId:
          type: string
        range:
          type: string
          enum:
            - 24h
            - 7d
            - 30d
            - all
        bucketGranularity:
          type: string
          enum:
            - hour
            - day
            - week
        token:
          $ref: "#/components/schemas/PrivacyPoolTokenView"
        walletSeries:
          type: array
          maxItems: 720
          items:
            $ref: "#/components/schemas/PrivacyPoolWalletMetricSeriesItem"
        shieldedSupplySeries:
          type: array
          maxItems: 720
          items:
            $ref: "#/components/schemas/PrivacyPoolShieldedSupplySeriesItem"
        privacyFeeSeries:
          type: array
          maxItems: 720
          items:
            $ref: "#/components/schemas/PrivacyPoolFeeMetricSeriesItem"
    PrivacyPoolDashboardView:
      type: object
      additionalProperties: false
      required:
        - status
        - analytics
        - events
      properties:
        status:
          $ref: "#/components/schemas/PrivacyPoolStatusView"
        analytics:
          $ref: "#/components/schemas/PrivacyPoolAnalyticsView"
        events:
          $ref: "#/components/schemas/PrivacyPoolEventPage"
    PrivacyPoolPrivateActivityMetricView:
      type: object
      additionalProperties: false
      required:
        - activityKind
        - protocolSlug
        - protocolName
        - helperAddress
        - helperLabel
        - confidence
        - attributionRuleVersion
        - txCount
        - noteUsedEventCount
        - openNoteCreatedEventCount
        - openNoteDepositedEventCount
        - encNoteCreatedEventCount
        - helperWithdrawalEventCount
        - latestBlockNumber
        - latestTxHash
      properties:
        activityKind:
          type: string
          enum:
            - private_swap
        protocolSlug:
          type: string
        protocolName:
          type: string
        helperAddress:
          type: string
        helperLabel:
          type: string
        confidence:
          type: string
          enum:
            - certified
            - candidate
            - unavailable
        attributionRuleVersion:
          type: string
        txCount:
          type: integer
          format: int64
        noteUsedEventCount:
          type: integer
          format: int64
        openNoteCreatedEventCount:
          type: integer
          format: int64
        openNoteDepositedEventCount:
          type: integer
          format: int64
        encNoteCreatedEventCount:
          type: integer
          format: int64
        helperWithdrawalEventCount:
          type: integer
          format: int64
        latestBlockNumber:
          type:
            - integer
            - "null"
          format: int64
        latestTxHash:
          type:
            - string
            - "null"
    PrivacyPoolPrivateActivityView:
      type: object
      additionalProperties: false
      required:
        - source
        - caveat
        - totalPrivateActionTxCount
        - totalHelperWithdrawalEventCount
        - totalNoteUsedEventCount
        - totalOpenNoteDepositedEventCount
        - metricsLimit
        - metricsTruncated
        - metrics
      properties:
        source:
          type: string
        caveat:
          type: string
        totalPrivateActionTxCount:
          type: integer
          format: int64
        totalHelperWithdrawalEventCount:
          type: integer
          format: int64
        totalNoteUsedEventCount:
          type: integer
          format: int64
        totalOpenNoteDepositedEventCount:
          type: integer
          format: int64
        metricsLimit:
          type: integer
          format: int64
        metricsTruncated:
          type: boolean
        metrics:
          type: array
          items:
            $ref: "#/components/schemas/PrivacyPoolPrivateActivityMetricView"
    PrivacyPoolAnalyticsView:
      type: object
      additionalProperties: false
      required:
        - chainId
        - totalEvents
        - uniqueTransactionCount
        - contractCount
        - latestEventBlock
        - eventBreakdown
        - visibilityBreakdown
        - tokenFlows
        - tokenFlowsLimit
        - tokenFlowsTruncated
        - tokenFlowSourceEventLimit
        - tokenFlowSourceEventsTruncated
        - missingAmountEventCount
        - strkbtcObserved
        - unknownTokenCount
        - privateActivity
        - unavailableMetrics
      properties:
        chainId:
          type: string
        totalEvents:
          type: integer
          format: int64
        uniqueTransactionCount:
          type: integer
          format: int64
        contractCount:
          type: integer
          format: int64
        latestEventBlock:
          type:
            - integer
            - "null"
          format: int64
        eventBreakdown:
          type: array
          items:
            $ref: "#/components/schemas/PrivacyPoolCountView"
        visibilityBreakdown:
          type: array
          items:
            $ref: "#/components/schemas/PrivacyPoolCountView"
        tokenFlows:
          type: array
          items:
            $ref: "#/components/schemas/PrivacyPoolTokenFlowView"
        tokenFlowsLimit:
          type: integer
          format: int64
        tokenFlowsTruncated:
          type: boolean
        tokenFlowSourceEventLimit:
          type: integer
          format: int64
          description: |
            Source event window used to derive tokenFlows. A value of 0 means the route is using all-history indexed public token-flow facts instead of deriving metrics from a bounded recent event sample.
        tokenFlowSourceEventsTruncated:
          type: boolean
          description: |
            True when tokenFlows were derived from a clipped source event window. False for all-history fact-backed token-flow metrics.
        missingAmountEventCount:
          type: integer
          format: int64
        strkbtcObserved:
          type: boolean
        unknownTokenCount:
          type: integer
          format: int64
        privateActivity:
          $ref: "#/components/schemas/PrivacyPoolPrivateActivityView"
        unavailableMetrics:
          type: array
          items:
            $ref: "#/components/schemas/PrivacyPoolUnavailableMetricView"
    SearchBlockItem:
      type: object
      additionalProperties: false
      required:
        - blockNumber
        - blockHash
      properties:
        blockNumber:
          type: integer
          format: int64
        blockHash:
          type: string
    SearchTransactionItem:
      type: object
      additionalProperties: false
      required:
        - txHash
        - blockNumber
        - txIndex
      properties:
        txHash:
          type: string
        blockNumber:
          type: integer
          format: int64
        txIndex:
          type: integer
          format: int32
    SearchView:
      type: object
      additionalProperties: false
      required:
        - blocks
        - transactions
        - addresses
      properties:
        blocks:
          type: array
          maxItems: 5
          items:
            $ref: "#/components/schemas/SearchBlockItem"
        transactions:
          type: array
          maxItems: 10
          items:
            $ref: "#/components/schemas/SearchTransactionItem"
        addresses:
          type: array
          maxItems: 10
          items:
            type: string
  headers:
    RequestId:
      description: Canonical request correlation header for support and tracing.
      schema:
        type: string
    WwwAuthenticate:
      description: Authentication or scope hint when the request is rejected.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying this route class.
      schema:
        type: integer
        format: int64
    StarkscanRouteClass:
      description: Route budget class for class-specific backoff.
      schema:
        type: string
        enum:
          - light
          - list
          - heavy
          - profile
          - batch
    RateLimitLimit:
      description: Maximum request budget for the current route-class window.
      schema:
        type: integer
        format: int64
    RateLimitRemaining:
      description: Remaining request budget for the current route-class window.
      schema:
        type: integer
        format: int64
    RateLimitPolicy:
      description: Opaque rate-limit policy identifier for the current route class.
      schema:
        type: string
x-starkscan-audience: public-core
tags:
  - name: Account
    description: Session-authenticated self-serve API-key lifecycle and usage routes for workspace operators.
  - name: Addresses
  - name: Blocks
  - name: Contracts
  - name: Reference
    description: Low-level explorer read surfaces that stay public but sit outside the default block/transaction/address entrypoints.
  - name: Search
  - name: Status
  - name: Tokens
  - name: Transactions
  - name: Utilities
    description: Supported helper routes that remain external, but are not the default public API starting point and can require broader utility-access keys.