satoshidata-ai Metrics API

openapi: 3.2.0
info:
  title: Satoshidata Agent Metrics API
  description: Bitcoin agent API with chain intelligence, Bitcoin timestamping, and machine-readable discovery. Public beta general access is free while documented conditional limits, including Wallet P&L above 100 transactions outside the public showcase, remain active. The checkout code path is preserved for the post-beta access model.
  version: 0.3.0
tags:
- name: Metrics
  description: On-chain and lane-specific metric payloads.
paths:
  /v1/onchain:
    get:
      tags:
      - Metrics
      summary: Live on-chain intelligence snapshot
      description: Free explicitly dated historical daily-lane metrics plus a current node snapshot. The historical daily lane is paused and no refresh is expected.
      operationId: onchain_stats
      parameters:
      - name: view
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Optional response view. Set `view=compact` for a smaller agent-oriented payload.
          title: View
        description: Optional response view. Set `view=compact` for a smaller agent-oriented payload.
      responses:
        '200':
          description: Live on-chain intelligence snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OnchainStatsResponse'
        '422':
          description: Request validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/ErrorResponse'
                - $ref: '#/components/schemas/RouteRecoveryResponse'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-satoshidata-pricing:
        capability: onchain_snapshot
        access_tier: free
        live_access_model: free
        target_access_model: free
        future_native_l402_price_sats: 0
        price_unit: request
      x-satoshidata-surface:
        canonical_name: onchain_stats
        pricing_capability: onchain_snapshot
        access_tier: free
        mcp_mode: live
components:
  schemas:
    RouteRecoveryResponse:
      type: object
      description: Typo-friendly 404 help card returned when a missing GET /v1 path closely matches a documented endpoint.
      properties:
        error:
          type: string
          const: route_recovery
          description: Machine-readable recovery envelope marker.
        detail:
          type: string
          description: Human-readable explanation naming the likely intended route.
        did_you_mean:
          type: string
          description: Canonical documented endpoint path that most closely matches the request.
        docs_url:
          type: string
          description: OpenAPI document URL for route discovery.
        alternatives:
          type: array
          description: Additional close documented endpoint matches when more than one is plausible.
          items:
            type: string
        beta:
          type: boolean
          description: True when the public beta envelope is active.
      required:
      - error
      - detail
      - did_you_mean
      - docs_url
    ResponsePagination:
      additionalProperties: false
      properties:
        offset:
          title: Offset
          type: integer
        limit:
          title: Limit
          type: integer
        total_alerts:
          title: Total Alerts
          type: integer
        next_offset:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Offset
        has_more:
          title: Has More
          type: boolean
      required:
      - offset
      - limit
      - total_alerts
      - next_offset
      - has_more
      title: ResponsePagination
      type: object
    ResponseWarning:
      additionalProperties: false
      properties:
        code:
          title: Code
          type: string
        message:
          title: Message
          type: string
      required:
      - code
      - message
      title: ResponseWarning
      type: object
    OnchainStatsResponse:
      additionalProperties: false
      properties:
        data_date:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Data Date
        lane_as_of:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Lane As Of
        daily_lane_state:
          enum:
          - active
          - paused
          title: Daily Lane State
          type: string
        refresh_expected:
          title: Refresh Expected
          type: boolean
        source_freshness:
          additionalProperties: true
          title: Source Freshness
          type: object
        market_context:
          additionalProperties: true
          title: Market Context
          type: object
        metrics:
          additionalProperties: true
          title: Metrics
          type: object
        lane_scores:
          additionalProperties: true
          title: Lane Scores
          type: object
        supplemental_metrics:
          additionalProperties: true
          title: Supplemental Metrics
          type: object
        node_snapshot:
          additionalProperties: true
          title: Node Snapshot
          type: object
        _meta:
          $ref: '#/components/schemas/ResponseMeta'
        beta:
          title: Beta
          type: boolean
      required:
      - daily_lane_state
      - refresh_expected
      - _meta
      - beta
      title: OnchainStatsResponse
      type: object
    ResponseMetaDetail:
      type: object
      description: Machine-readable metadata added by satoshidata.ai JSON responses.
      additionalProperties: false
      properties:
        endpoint:
          type: string
          description: Canonical request path.
        freshness:
          type: string
          description: Best-known freshness timestamp for the payload.
        freshness_semantics:
          type: string
          enum:
          - internal_refresh
          - source_poll
          - claim_made
          description: 'Meaning of _meta.freshness for this response: internal_refresh, source_poll, or claim_made.'
        source:
          type: string
          description: Primary data source for the response.
        price_sats:
          type: integer
          description: Native BTC-denominated price for this response, when applicable.
        docs:
          type: string
          description: OpenAPI documentation URL.
        warnings:
          type: array
          description: Non-fatal response warnings. Empty when no caveat applies.
          items:
            $ref: '#/components/schemas/ResponseWarning'
        pagination:
          type: object
          description: Pagination metadata when an endpoint supports paged archive traversal.
          additionalProperties: false
          properties:
            offset:
              type: integer
              minimum: 0
            limit:
              type: integer
              minimum: 1
            total_alerts:
              type: integer
              minimum: 0
            next_offset:
              anyOf:
              - type: integer
                minimum: 0
              - type: 'null'
            has_more:
              type: boolean
          required:
          - offset
          - limit
          - total_alerts
          - next_offset
          - has_more
        field_semantics:
          type: object
          description: Machine-readable notes explaining field-level semantics for the payload.
          additionalProperties: true
        semantic_completeness:
          type: object
          description: Machine-readable completeness caveats for fields that can be partial or derived.
          additionalProperties: true
        price_usd:
          type: string
          description: USD-denominated x402 price when a per-call grant was used.
        view:
          type: string
          enum:
          - compact
          description: Response projection view, currently compact.
        bitcoin_backend:
          type: string
          description: Public label for the Bitcoin backend used by the response.
        beta:
          type: boolean
          description: Endpoint-specific beta flag when carried inside _meta.
        cache_seconds:
          type: integer
          description: Advertised response cache lifetime in seconds.
        cache_ttl_seconds:
          type: integer
          description: Advertised response cache TTL in seconds.
        cache_status:
          type: string
          description: Cache hit/miss/fresh/stale status for cached projections.
        cache_age_seconds:
          type: number
          description: Age in seconds for the cached projection served.
        cache_cached_at:
          type: string
          description: Timestamp when the served projection was cached.
        cached:
          type: boolean
          description: True when this response body came from a cache.
        cache_policy:
          type: string
          description: Stable cache policy label for the response.
        compute_ms:
          type: integer
          description: Server-side compute time in milliseconds.
        warning:
          type: string
          description: Single human-readable response warning when a legacy slot is used.
        refresh_warning:
          type: string
          description: Warning about background refresh state for cached dashboard data.
        last_refresh_started_at:
          type: string
          description: Timestamp for the last background refresh start.
        last_refresh_completed_at:
          type: string
          description: Timestamp for the last background refresh completion.
        last_refresh_status:
          type: string
          description: Status of the last background refresh.
        last_refresh_error:
          type: string
          description: Last background refresh error, when present.
        last_refresh_duration_ms:
          type: integer
          description: Last background refresh duration in milliseconds.
        feature_flag:
          type: string
          description: Runtime feature flag associated with an experimental endpoint.
        rollout_state:
          type: string
          description: Rollout state for hidden or beta backend features.
        schema_version:
          anyOf:
          - type: string
          - type: 'null'
          description: Endpoint-specific payload schema version, when declared.
        retention:
          type: string
          description: Retention policy label for ephemeral response artifacts.
        not_compliance_advice:
          type: boolean
          description: True when the response is explicitly not compliance advice.
        future_native_price_mode:
          type: string
          description: Future native-pricing mode for endpoints with dynamic fees.
        future_native_price_note:
          type: string
          description: Human-readable note for future native-pricing mode.
        future_native_quote_endpoint:
          type: string
          description: Endpoint that quotes a future dynamic native price.
        overview_activity_cache:
          type: object
          description: Metadata for wallet overview directional-activity cache reuse.
          additionalProperties: true
        attribution_confidence:
          type: string
          description: Attribution confidence label for pool-intel metadata.
        generated_at:
          type: string
          description: Timestamp when the source projection was generated.
        last_computed:
          type: string
          description: Timestamp when the source projection was last computed.
        snapshot_generated_at:
          type: string
          description: Timestamp embedded in the served persistent snapshot.
        snapshot_age_seconds:
          type: number
          description: Age in seconds for the served persistent snapshot.
        snapshot_stale_after_seconds:
          type: integer
          description: Staleness threshold in seconds for the served persistent snapshot.
        snapshot_status:
          type: string
          description: Freshness status for the served persistent snapshot.
        history_window_basis:
          type: string
          description: History-window basis used by pool-intel projections.
        history_window_start_height:
          type: integer
          description: Earliest block height covered by the pool-intel history window.
        first_block_mined_coverage:
          type: string
          description: Whether first_block_mined is full-history or partial-window constrained.
        first_block_mined_note:
          type: string
          description: Coverage caveat for first_block_mined when history is partial.
        total_blocks_last_24h:
          type: integer
          description: Pool-intel total block count in the current 24h window.
    ResponseMeta:
      additionalProperties: false
      properties:
        endpoint:
          title: Endpoint
          type: string
        freshness:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Freshness
        freshness_semantics:
          anyOf:
          - enum:
            - internal_refresh
            - source_poll
            - claim_made
            type: string
          - type: 'null'
          default: null
          title: Freshness Semantics
        source:
          title: Source
          type: string
        price_sats:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Price Sats
        price_usd:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Price Usd
        docs:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Docs
        warnings:
          items:
            $ref: '#/components/schemas/ResponseWarning'
          title: Warnings
          type: array
        pagination:
          anyOf:
          - $ref: '#/components/schemas/ResponsePagination'
          - type: 'null'
          default: null
        view:
          anyOf:
          - const: compact
            type: string
          - type: 'null'
          default: null
          title: View
        bitcoin_backend:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Bitcoin Backend
        beta:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Beta
        cache_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Cache Seconds
        cache_ttl_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Cache Ttl Seconds
        cache_status:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cache Status
        cache_age_seconds:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          title: Cache Age Seconds
        cache_cached_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cache Cached At
        cached:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Cached
        cache_policy:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Cache Policy
        compute_ms:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Compute Ms
        warning:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Warning
        refresh_warning:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Refresh Warning
        last_refresh_started_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Refresh Started At
        last_refresh_completed_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Refresh Completed At
        last_refresh_status:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Refresh Status
        last_refresh_error:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Refresh Error
        last_refresh_duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Last Refresh Duration Ms
        feature_flag:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Feature Flag
        rollout_state:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Rollout State
        schema_version:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Schema Version
        methodology_version:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Methodology Version
        materialized_source:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Materialized Source
        max_hops:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Max Hops
        retention:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Retention
        not_compliance_advice:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Not Compliance Advice
        future_native_price_mode:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Future Native Price Mode
        future_native_price_note:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Future Native Price Note
        future_native_quote_endpoint:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Future Native Quote Endpoint
        overview_activity_cache:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Overview Activity Cache
        attribution_confidence:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Attribution Confidence
        generated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Generated At
        last_computed:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Last Computed
        snapshot_generated_at:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Snapshot Generated At
        snapshot_age_seconds:
          anyOf:
          - type: number
          - type: 'null'
          default: null
          title: Snapshot Age Seconds
        snapshot_stale_after_seconds:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Snapshot Stale After Seconds
        snapshot_status:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Snapshot Status
        history_window_basis:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: History Window Basis
        total_blocks_last_24h:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Total Blocks Last 24H
        field_semantics:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Field Semantics
        semantic_completeness:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Semantic Completeness
      required:
      - endpoint
      - source
      title: ResponseMeta
      type: object
    ErrorResponse:
      type: object
      description: Error response envelope.
      additionalProperties: false
      properties:
        detail:
          description: Human-readable error detail or structured problem detail.
          anyOf:
          - type: string
          - type: object
            additionalProperties: true
          - type: 'null'
        errors:
          type: array
          description: Structured validation errors when request validation fails.
          items:
            type: object
            additionalProperties: true
        beta:
          type: boolean
          description: True when the public beta envelope is active.
        _meta:
          $ref: '#/components/schemas/ResponseMetaDetail'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-WR-API-Key