satoshidata-ai Sanctions API

openapi: 3.2.0
info:
  title: Satoshidata Agent Sanctions 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: sanctions
paths:
  /v1/sanctions/ofac/compliance-tier:
    get:
      tags:
      - sanctions
      summary: Verified OFAC sanctions compliance tier
      description: Free distinct OFAC sanctions compliance tier. The response is built from the approved sanctions-compliance-v1 publish set and intersects it with the current OFAC SDN_ADVANCED.XML feed before serving rows.
      operationId: sanctions_ofac_compliance_tier_v1_sanctions_ofac_compliance_tier_get
      responses:
        '200':
          description: Verified OFAC sanctions entities and addresses that remain present in current SDN Advanced data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SanctionsOfacComplianceTierV1SanctionsOfacComplianceTierGet200Response'
        '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'
        '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'
      x-satoshidata-pricing:
        capability: ofac_sanctions_compliance_tier
        access_tier: free
        live_access_model: free
        target_access_model: free
        future_native_l402_price_sats: 0
        price_unit: request
  /v1/sanctions/ofac/coverage:
    get:
      tags:
      - sanctions
      summary: OFAC sanctions coverage
      description: Free lead-gen endpoint summarizing satoshidata.ai's current verified OFAC address coverage. Sanctions-exposure scoring and path search remain separate premium surfaces.
      operationId: sanctions_ofac_coverage_v1_sanctions_ofac_coverage_get
      responses:
        '200':
          description: OFAC coverage counts, top entities by covered address count, and premium endpoint roadmap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SanctionsOfacCoverageV1SanctionsOfacCoverageGet200Response'
        '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'
        '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'
  /v1/wallets/{address}/sanctions-exposure:
    get:
      tags:
      - sanctions
      summary: Wallet sanctions exposure
      description: Premium endpoint returning bounded OFAC sanctions-exposure scoring for a Bitcoin wallet. Graph-derived exposure is evidentiary context, not a legal determination.
      operationId: wallet_sanctions_exposure_v1_wallets__address__sanctions_exposure_get
      parameters:
      - name: address
        in: path
        required: true
        schema:
          type: string
          title: Address
      - name: max_hops
        in: query
        required: false
        schema:
          type: integer
          maximum: 6
          minimum: 1
          default: 3
          title: Max Hops
      - name: aggregate
        in: query
        required: false
        schema:
          enum:
          - total
          - by_entity
          - by_path
          type: string
          default: total
          title: Aggregate
      - name: Authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Premium OFAC sanctions-exposure score with contributing entities and optional path evidence.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletSanctionsExposureV1WalletsAddressSanctionsExposureGet200Response'
        '402':
          description: Payment required for premium chain intelligence endpoints when no valid API key is supplied.
          headers:
            PAYMENT-REQUIRED:
              description: Machine-readable wallet checkout requirements as a compact JSON string.
              schema:
                type: string
              example: '{"amount_sats":null,"bridge_access":true,"catalog_url":"https://satoshidata.ai/v1/billing/catalog","checkout_url":"https://satoshidata.ai/v1/billing/checkout","currency":"BTC","description":"Agent API Bridge Pass - 31 day bridge access","future_native_l402_price_sats":5000,"future_native_price_unit":"request","header":"X-WR-API-Key","plan_id":"wallet-monthly","pricing_status":"price_unavailable","requested_capability":"sanctions_exposure","scheme":"api_key_bridge"}'
          content:
            application/json:
              example:
                error: payment_required
                detail: Payment required for /v1/wallets/{address}/sanctions-exposure.
                payment_required:
                  scheme: api_key_bridge
                  plan_id: wallet-monthly
                  header: X-WR-API-Key
                  currency: BTC
                  checkout_url: https://satoshidata.ai/v1/billing/checkout
                  catalog_url: https://satoshidata.ai/v1/billing/catalog
                  description: Agent API Bridge Pass - 31 day bridge access
                  bridge_access: true
                  requested_capability: sanctions_exposure
                  future_native_l402_price_sats: 5000
                  future_native_price_unit: request
                  pricing_status: price_unavailable
                how_to_access: To use /v1/wallets/{address}/sanctions-exposure, visit https://satoshidata.ai/v1/billing/catalog to see bridge plans, then POST https://satoshidata.ai/v1/billing/checkout to pay with Lightning or BTC on-chain for bridge/API-key access. If you already have bridge access, retry with the X-WR-API-Key header.
                getting_started_url: https://satoshidata.ai/v1/billing/catalog
                docs_url: https://satoshidata.ai/#docs
              schema:
                $ref: '#/components/schemas/PaymentRequiredResponse'
        '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: sanctions_exposure
        access_tier: premium
        live_access_model: beta_free
        target_access_model: 402_per_call
        future_native_l402_price_sats: 5000
        price_unit: request
        current_bridge_plan_id: wallet-monthly
        native_402_opening_stage: unknown
        native_402_opening_reason: No native-opening policy recorded yet.
      x-satoshidata-beta-access:
        auth_required: false
        auth_header: none
        mode: public_beta
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
    SanctionsOfacComplianceTierV1SanctionsOfacComplianceTierGet200Response:
      type: object
      description: Verified OFAC sanctions entities and addresses that remain present in current SDN Advanced data. This component documents the stable satoshidata.ai JSON response envelope for this operation; endpoint-specific dynamic sections may include additional properties.
      additionalProperties: false
      properties:
        _meta:
          $ref: '#/components/schemas/ResponseMetaDetail'
        beta:
          type: boolean
          description: True when the public beta envelope is active.
    SanctionsOfacCoverageV1SanctionsOfacCoverageGet200Response:
      type: object
      description: OFAC coverage counts, top entities by covered address count, and premium endpoint roadmap. This component documents the stable satoshidata.ai JSON response envelope for this operation; endpoint-specific dynamic sections may include additional properties.
      additionalProperties: false
      properties:
        _meta:
          $ref: '#/components/schemas/ResponseMetaDetail'
        beta:
          type: boolean
          description: True when the public beta envelope is active.
    PaymentRequiredResponse:
      type: object
      description: HTTP 402 payment challenge or hybrid payment instructions.
      additionalProperties: false
      properties:
        detail:
          description: Human-readable payment requirement or challenge detail.
        payment_request:
          description: Native payment request payload when available.
        payment_options:
          description: Available machine-payment options for the request.
        payment:
          description: Legacy or bridge payment details when present.
        beta:
          type: boolean
          description: True when the public beta envelope is active.
        _meta:
          $ref: '#/components/schemas/ResponseMetaDetail'
    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.
    WalletSanctionsExposureV1WalletsAddressSanctionsExposureGet200Response:
      type: object
      description: Premium OFAC sanctions-exposure score with contributing entities and optional path evidence. This component documents the stable satoshidata.ai JSON response envelope for this operation; endpoint-specific dynamic sections may include additional properties.
      additionalProperties: false
      properties:
        _meta:
          $ref: '#/components/schemas/ResponseMetaDetail'
        beta:
          type: boolean
          description: True when the public beta envelope is active.
    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