satoshidata-ai Labels API

openapi: 3.2.0
info:
  title: Satoshidata Agent Labels 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: Labels
paths:
  /v1/labels/search:
    get:
      operationId: label_search
      summary: Search labeled entities
      description: 'Free operator-first search over satoshidata.ai''s label search view. Use exact mode for a normalized entity string or prefix mode for interactive agent discovery; substring and fuzzy modes are intentionally not accepted. Every result includes confidence_tier: verified, clustered, or reported. The tier annotates the same label corpus; clustered and reported are not custody or ownership attestations.'
      tags:
      - Labels
      x-satoshidata-surface:
        canonical_name: label_search
        pricing_capability: label_search
        access_tier: free
        mcp_mode: none
      responses:
        '200':
          description: Search labeled entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelSearchResponse'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Request validation failed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
        description: Entity query. Exact mode accepts a non-empty normalized query; prefix mode requires at least two normalized characters.
      - name: mode
        in: query
        required: false
        schema:
          type: string
          enum:
          - exact
          - prefix
          default: exact
        description: Search mode currently accepted by the live endpoint.
      - name: include_generic
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Include generic label values such as broad category terms.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 25
          default: 8
        description: Maximum number of label/entity rows to return.
components:
  schemas:
    LabelSearchResult:
      additionalProperties: false
      properties:
        entity:
          title: Entity
          type: string
        category:
          title: Category
          type: string
        address_count:
          title: Address Count
          type: integer
        strong_count:
          title: Strong Count
          type: integer
        source_count:
          title: Source Count
          type: integer
        dominant_source:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Dominant Source
        confidence:
          description: Legacy confidence bucket for this search result.
          enum:
          - verified
          - medium
          - heuristic
          title: Confidence
          type: string
        verified:
          description: True only when confidence_tier is verified.
          title: Verified
          type: boolean
        evidence_tier:
          description: Legacy A/B/C evidence bucket.
          enum:
          - A
          - B
          - C
          title: Evidence Tier
          type: string
        confidence_tier:
          description: 'Public confidence annotation for the label corpus: verified, clustered, or reported. Clustered and reported are not custody or ownership attestations.'
          enum:
          - verified
          - clustered
          - reported
          title: Confidence Tier
          type: string
        tier:
          description: Alias for confidence_tier.
          enum:
          - verified
          - clustered
          - reported
          title: Tier
          type: string
        generic_label:
          title: Generic Label
          type: boolean
        sample_addresses:
          items:
            type: string
          title: Sample Addresses
          type: array
        latest_seen_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          title: Latest Seen At
        updated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          title: Updated At
        cluster_recency:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          default: null
          title: Cluster Recency
      required:
      - entity
      - category
      - address_count
      - strong_count
      - source_count
      - confidence
      - verified
      - evidence_tier
      - confidence_tier
      - tier
      - generic_label
      title: LabelSearchResult
      type: object
    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
    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
    LabelSearchResponse:
      additionalProperties: false
      properties:
        query:
          title: Query
          type: string
        normalized_query:
          title: Normalized Query
          type: string
        mode:
          enum:
          - exact
          - prefix
          title: Mode
          type: string
        include_generic:
          title: Include Generic
          type: boolean
        scope:
          const: operator-first label entity search
          title: Scope
          type: string
        results:
          items:
            $ref: '#/components/schemas/LabelSearchResult'
          title: Results
          type: array
        _meta:
          anyOf:
          - $ref: '#/components/schemas/ResponseMeta'
          - type: 'null'
          default: null
        beta:
          anyOf:
          - type: boolean
          - type: 'null'
          default: null
          title: Beta
      required:
      - query
      - normalized_query
      - mode
      - include_generic
      - scope
      title: LabelSearchResponse
      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