{
  "agentsJson": "0.1.0",
  "info": {
    "title": "SatoshiData.ai Agent API",
    "version": "2026-05-03",
    "description": "Bitcoin chain intelligence API for AI agents. Current product mode is public_beta: all documented endpoints are free during beta, billing is paused, and responses expose the current access/auth truth in their access and _meta blocks."
  },
  "name": "satoshidata-ai",
  "description": "Bitcoin wallet trust-safety, entity labels, on-chain network context, transaction lookup, timestamping, and payment-aware premium-design intelligence. Public beta currently makes the API free while preserving the post-beta payment metadata.",
  "homepage_url": "https://satoshidata.ai/",
  "base_url": "https://satoshidata.ai",
  "openapi_url": "https://satoshidata.ai/openapi.json",
  "llms_txt_url": "https://satoshidata.ai/llms.txt",
  "llms_full_url": "https://satoshidata.ai/llms-full.txt",
  "agent_card_url": "https://satoshidata.ai/.well-known/agent-card.json",
  "capabilities_url": "https://satoshidata.ai/v1/capabilities",
  "mcp": {
    "url": "https://satoshidata.ai/mcp/",
    "well_known_url": "https://satoshidata.ai/.well-known/mcp.json",
    "transport": "streamable-http"
  },
  "current_access": {
    "product_mode": "public_beta",
    "billing_mode": "beta_free",
    "auth_mode": "beta_public",
    "current_pricing_mode": "free_during_beta",
    "billing_paused": true,
    "api_key_required_during_beta": false,
    "native_l402_live_capabilities": [],
    "x402_live_capabilities": [],
    "x402_prepared_capabilities": [
      "wallet_summary",
      "mempool_stress_history"
    ]
  },
  "capability_tags": [
    "bitcoin",
    "on-chain-intelligence",
    "wallet-risk",
    "trust-safety",
    "entity-labels",
    "mempool",
    "fees",
    "transaction-lookup",
    "timestamping",
    "MCP"
  ],
  "authentication": [
    {
      "type": "none",
      "description": "Current public beta access. All documented endpoints are callable without payment or API key while product_mode is public_beta."
    },
    {
      "type": "api_key",
      "header": "X-WR-API-Key",
      "description": "Post-beta API-key bridge header. It may be accepted during beta but is not required while auth_mode is beta_public.",
      "obtain_url": "https://satoshidata.ai/v1/billing/checkout"
    },
    {
      "type": "L402",
      "protocol": "Lightning",
      "status": "not_live",
      "description": "No native L402 capabilities are live right now. Check /api/health before assuming L402 payment is available."
    },
    {
      "type": "x402",
      "protocol": "USDC on Base",
      "status": "prepared_not_live",
      "description": "x402 metadata is prepared for wallet_summary and mempool_stress_history, but no x402 endpoint is live while public beta is active."
    }
  ],
  "payment_options": [
    {
      "type": "beta_free",
      "status": "live",
      "description": "Public beta makes the documented API free. Responses expose access.auth_mode=beta_public."
    },
    {
      "type": "api_key",
      "status": "post_beta_bridge",
      "description": "Post-beta API-key bridge path. Not required during beta."
    },
    {
      "type": "x402",
      "asset": "USDC",
      "network": "Base",
      "status": "prepared_not_live",
      "prepared_capabilities": [
        "wallet_summary",
        "mempool_stress_history"
      ]
    }
  ],
  "sources": [
    {
      "id": "satoshidata-openapi",
      "path": "https://satoshidata.ai/openapi.json"
    },
    {
      "id": "satoshidata-capabilities",
      "path": "https://satoshidata.ai/v1/capabilities"
    }
  ],
  "overrides": [],
  "flows": [
    {
      "id": "wallet_trust_safety",
      "title": "Check Bitcoin Wallet Trust And Safety",
      "description": "Return the current trust-safety label evidence, consensus state, caveats, and risk block for a Bitcoin address.",
      "actions": [
        {
          "id": "wallet_trust_safety_action",
          "sourceId": "satoshidata-openapi",
          "operationId": "wallet_trust_safety_v1_wallets__address__trust_safety_get"
        }
      ],
      "links": [
        {
          "origin": {
            "actionId": "wallet_trust_safety",
            "fieldPath": "parameters"
          },
          "target": {
            "actionId": "wallet_trust_safety_action",
            "fieldPath": "parameters"
          }
        }
      ],
      "fields": {
        "parameters": [
          {
            "name": "address",
            "description": "Bitcoin address to check.",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "success": {
            "type": "object",
            "description": "Trust-safety response. Real top-level keys include address, label, claim_type, confidence, evidence_tier, evidence_types, source, source_ref, narrative, updated_at, caveats, access, kind, address_type, assessment, consensus, risk, premium_available, _meta, and beta.",
            "example": {
              "address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
              "label": {
                "value": "Example entity",
                "category": "exchange"
              },
              "confidence": "medium",
              "evidence_tier": "inferred",
              "assessment": {
                "state": "lead"
              },
              "consensus": {
                "state": "single_lead"
              },
              "risk": {
                "tier": "unknown"
              },
              "access": {
                "auth_mode": "beta_public"
              }
            }
          }
        }
      }
    },
    {
      "id": "wallet_summary",
      "title": "Get Wallet Summary",
      "description": "Return the current wallet summary shape. During public beta this endpoint is beta-free; post-beta it is a premium-design endpoint.",
      "actions": [
        {
          "id": "wallet_summary_action",
          "sourceId": "satoshidata-openapi",
          "operationId": "wallet_summary_v1_wallets__address__summary_get"
        }
      ],
      "links": [
        {
          "origin": {
            "actionId": "wallet_summary",
            "fieldPath": "parameters"
          },
          "target": {
            "actionId": "wallet_summary_action",
            "fieldPath": "parameters"
          }
        }
      ],
      "fields": {
        "parameters": [
          {
            "name": "address",
            "description": "Bitcoin address to summarize.",
            "required": true,
            "type": "string"
          }
        ],
        "responses": {
          "success": {
            "type": "object",
            "description": "Wallet summary response. Real top-level keys include address, label, confidence, evidence_tier, likely_category, likely_entity, label_count, unique_contributors, has_conflict, short_explanation, metadata, access, _meta, and beta.",
            "example": {
              "address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
              "likely_category": "exchange",
              "likely_entity": "Example entity",
              "label_count": 1,
              "access": {
                "auth_mode": "beta_public"
              }
            }
          }
        }
      }
    },
    {
      "id": "batch_trust_safety",
      "title": "Batch Wallet Trust Checks",
      "description": "Check multiple Bitcoin addresses in one request. Request bodies reject extra keys; send only addresses.",
      "actions": [
        {
          "id": "batch_trust_safety_action",
          "sourceId": "satoshidata-openapi",
          "operationId": "wallet_batch_trust_safety_v1_batch_trust_safety_post"
        }
      ],
      "links": [
        {
          "origin": {
            "actionId": "batch_trust_safety",
            "fieldPath": "requestBody"
          },
          "target": {
            "actionId": "batch_trust_safety_action",
            "fieldPath": "requestBody"
          }
        }
      ],
      "fields": {
        "requestBody": {
          "type": "object",
          "description": "JSON body with only an addresses array. Maximum 100 addresses.",
          "example": {
            "addresses": [
              "1BoatSLRHtKNngkdXEeobR76b53LETtpyT"
            ]
          }
        },
        "responses": {
          "success": {
            "type": "array",
            "description": "Array of per-address trust-safety objects.",
            "example": [
              {
                "address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
                "confidence": "medium",
                "evidence_tier": "inferred",
                "assessment": {
                  "state": "lead"
                }
              }
            ]
          }
        }
      }
    },
    {
      "id": "bitcoin_network_snapshot",
      "title": "Get Bitcoin Network Snapshot",
      "description": "Fetch current Bitcoin price, fee, mempool, hashrate, and chain context for a market or wallet answer.",
      "actions": [
        {
          "id": "network_summary_action",
          "sourceId": "satoshidata-openapi",
          "operationId": "free_network_summary_v1_network_summary_get"
        }
      ],
      "links": [],
      "fields": {
        "parameters": [],
        "responses": {
          "success": {
            "type": "object",
            "description": "Current network summary. Real top-level keys include btc_price_usd, price_change_24h_pct, fees, mempool, hashrate_eh, hashrate_method, difficulty, _meta, and beta.",
            "example": {
              "btc_price_usd": 78000,
              "fees": {},
              "mempool": {},
              "hashrate_method": "bitcoind_getnetworkhashps_2016blocks_difficulty_period"
            }
          }
        }
      }
    },
    {
      "id": "submit_feedback",
      "title": "Submit Data Correction Feedback",
      "description": "Let an agent report an address-label correction, endpoint issue, or evidence caveat for review.",
      "actions": [
        {
          "id": "feedback_action",
          "sourceId": "satoshidata-openapi",
          "operationId": "submit_feedback_v1_feedback_post"
        }
      ],
      "links": [],
      "fields": {
        "requestBody": {
          "type": "object",
          "description": "Machine-readable correction or issue report. Accepted type values: label_correction, label_missing, data_quality, general, general_feedback. For general feedback, message is accepted as an alias for summary.",
          "example": {
            "type": "general",
            "message": "The docs example for this endpoint appears stale.",
            "endpoint": "/v1/wallets/{address}/trust-safety"
          }
        },
        "responses": {
          "success": {
            "type": "object",
            "description": "Feedback receipt.",
            "example": {
              "status": "received",
              "feedback_id": "fb_example",
              "message": "Thank you. Feedback is reviewed by our team."
            }
          }
        }
      }
    }
  ]
}