satoshidata-ai Community API

openapi: 3.2.0
info:
  title: Satoshidata Agent Community 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: Community
  description: Community-submitted wallet reports, payment-backed publishing, and voting.
paths:
  /v1/community/reports:
    post:
      tags:
      - Community
      summary: Create a payment-backed community report
      description: Creates a pending community report for a Bitcoin address and returns an anti-spam payment address.
      operationId: community_report_create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommunityReportCreateRequest'
        required: true
      responses:
        '200':
          description: Create a payment-backed community report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityReportCreateResponse'
        '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-surface:
        canonical_name: community_report_create
        pricing_capability: community_report_create
        access_tier: free
        mcp_mode: none
  /v1/community/reports/{report_id}/status:
    get:
      tags:
      - Community
      summary: Check community report payment status
      description: Polls the on-chain payment address and publishes the report after one confirmation.
      operationId: community_report_status
      parameters:
      - name: report_id
        in: path
        required: true
        schema:
          type: string
          title: Report Id
      responses:
        '200':
          description: Check community report payment status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityReportStatusResponse'
        '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-surface:
        canonical_name: community_report_status
        pricing_capability: community_report_status
        access_tier: free
        mcp_mode: none
  /v1/qr:
    get:
      tags:
      - Community
      summary: Render a QR code PNG for the supplied data
      operationId: qr_code_png
      parameters:
      - name: data
        in: query
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 4096
          title: Data
      responses:
        '200':
          description: Render a QR code PNG
          content:
            image/png:
              schema:
                type: string
                format: binary
        '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-surface:
        canonical_name: qr_code_png
        pricing_capability: qr_code_png
        access_tier: free
        mcp_mode: none
      description: Render a QR code PNG for the supplied data query parameter.
  /v1/community/reports/{report_id}/vote:
    post:
      tags:
      - Community
      summary: Vote on a published community report
      description: Free upvote or downvote for published community reports, limited to one vote per IP per 24 hours.
      operationId: community_report_vote
      parameters:
      - name: report_id
        in: path
        required: true
        schema:
          type: string
          title: Report Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommunityReportVoteRequest'
      responses:
        '200':
          description: Vote on a published community report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityReportVoteResponse'
        '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-surface:
        canonical_name: community_report_vote
        pricing_capability: community_report_vote
        access_tier: free
        mcp_mode: none
  /v1/community/reports/{address}:
    get:
      tags:
      - Community
      summary: List published community reports for a wallet
      description: Returns published community reports for a Bitcoin address, sorted by score and recency.
      operationId: community_reports
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          title: Address
      responses:
        '200':
          description: List published community reports for a wallet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommunityReportsResponse'
        '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-surface:
        canonical_name: community_reports
        pricing_capability: community_reports
        access_tier: free
        mcp_mode: none
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
    CommunityReportVoteRequest:
      additionalProperties: false
      properties:
        direction:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Direction
        vote:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Vote
      title: CommunityReportVoteRequest
      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
    CommunityReportCreateResponse:
      additionalProperties: false
      properties:
        status:
          title: Status
          type: string
        report_id:
          title: Report Id
          type: string
        payment_address:
          title: Payment Address
          type: string
        amount_sats:
          title: Amount Sats
          type: integer
        _meta:
          $ref: '#/components/schemas/ResponseMeta'
        beta:
          title: Beta
          type: boolean
      required:
      - status
      - report_id
      - payment_address
      - amount_sats
      - _meta
      - beta
      title: CommunityReportCreateResponse
      type: object
    CommunityReportStatusResponse:
      additionalProperties: false
      properties:
        report_id:
          title: Report Id
          type: string
        status:
          title: Status
          type: string
        _meta:
          $ref: '#/components/schemas/ResponseMeta'
        beta:
          title: Beta
          type: boolean
      required:
      - report_id
      - status
      - _meta
      - beta
      title: CommunityReportStatusResponse
      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.
    CommunityReportCreateRequest:
      additionalProperties: false
      properties:
        address:
          title: Address
          type: string
        category:
          title: Category
          type: string
        severity:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Severity
        comment:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Comment
        message:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Message
        evidence_url:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          title: Evidence Url
      required:
      - address
      - category
      title: CommunityReportCreateRequest
      type: object
    CommunityReportsResponse:
      additionalProperties: false
      properties:
        address:
          title: Address
          type: string
        reports:
          items:
            additionalProperties: true
            type: object
          title: Reports
          type: array
        total:
          title: Total
          type: integer
        _meta:
          $ref: '#/components/schemas/ResponseMeta'
        beta:
          title: Beta
          type: boolean
      required:
      - address
      - total
      - _meta
      - beta
      title: CommunityReportsResponse
      type: object
    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
    CommunityReportVoteResponse:
      additionalProperties: false
      properties:
        report_id:
          title: Report Id
          type: string
        upvotes:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Upvotes
        downvotes:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Downvotes
        score:
          anyOf:
          - type: integer
          - type: 'null'
          default: null
          title: Score
        _meta:
          $ref: '#/components/schemas/ResponseMeta'
        beta:
          title: Beta
          type: boolean
      required:
      - report_id
      - _meta
      - beta
      title: CommunityReportVoteResponse
      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