California Bitcoin A2a API

openapi: 3.2.0
info:
  title: California Bitcoin Agent Commerce A2a API
  version: 1.2.0
  description: California Bitcoin is source-backed Bitcoin research and verification infrastructure for AI agents. Start free with deterministic search and answers. When a difficult question requires a compact evidence-grade specialist answer, use the $1 answer-question product; claim verification, evidence packs, timelines, deep grounding, and batch research remain distinct paid jobs.
  x-guidance: 'START HERE: call start_bitcoin_research with the caller''s real Bitcoin question or task for a free deterministic answer and coverage check. Free answer_bitcoin_question and search_bitcoin_knowledge remain available for evaluation and retrieval. Use answer_bitcoin_question_with_evidence when the caller wants California Bitcoin to produce a compact source-backed answer to a difficult natural-language question with consensus/policy/version distinctions, contradiction handling, confidence, and primary-source evidence. Use verify_bitcoin_claim only when the caller already has one proposition to adjudicate; get_bitcoin_evidence_pack when the primary need is evidence rather than an answer; build_bitcoin_timeline for chronology; deep_ground_bitcoin for deeper multi-source investigation; and batch_bitcoin_research for multiple items. If a prior paid result carries evidenceCheckpoint, compare it for free before repurchasing covered historical research. If free coverage is insufficient or out of scope, do not pay. Only invoke a paid research tool when the caller has approved the exact spending budget. Paid HTTP research uses MPP: the first valid unpaid request returns HTTP 402 Payment Required. Fulfill the Payment challenge and retry the identical request with the payment credential.'
  x-not-for:
  - 'Live prices: use a market-data API.'
  - 'Current transactions, balances, blocks or fees: use a Bitcoin node or chain API.'
  - 'Breaking or uncovered facts: inspect current primary sources.'
  - 'Uncovered historical attribution: do not substitute a generic topical answer for evidence of what a person actually said or wrote.'
  - 'General web discovery: use search first, then use the smallest relevant specialist operation only when maintained coverage exists.'
  x-discovery-keywords:
  - free Bitcoin research MCP
  - free source-backed Bitcoin answers
  - Bitcoin research MCP for AI agents
  - Bitcoin agent research start here
  - source-backed Bitcoin question answering
  - Bitcoin consensus policy answer API
  - Bitcoin claim verification
  - Bitcoin fact verification API
  - source-backed Bitcoin API
  - Bitcoin primary-source research
  - Bitcoin evidence API
  - Bitcoin verification MCP
  - Bitcoin evidence MCP
  - Bitcoin timeline API
  - Bitcoin source evidence API
  - Bitcoin research tool for AI agents
  - deterministic Bitcoin research
  - Bitcoin protocol evidence API
  - Bitcoin claim verification service
  - pay-per-call Bitcoin research
  - primary-source Bitcoin evidence
  - Bitcoin evidence checkpoint
  x-use-when:
  - Start an unfamiliar AI agent on a real Bitcoin question with a useful free source-backed answer before any payment decision.
  - Get a compact evidence-grade answer to a difficult natural-language Bitcoin question with consensus, policy, implementation, version, contradiction, and primary-source distinctions.
  - Verify a specific Bitcoin claim against maintained evidence.
  - Retrieve source-backed Bitcoin evidence with provenance and exact source locators when available.
  - Build a sourced Bitcoin timeline from maintained historical evidence.
  - Ground an AI answer in maintained Bitcoin knowledge before using it downstream.
  - Check contradictions, caveats, and temporal validity around a Bitcoin proposition.
  - Evaluate Bitcoin protocol claims against primary-source and official evidence.
  - Compare a previously returned retained-evidence checkpoint for free before repurchasing covered historical research.
  x-differentiator: Free evaluation first, then maintained deterministic primary-source-first Bitcoin evidence infrastructure with explicit consensus-vs-policy distinctions, uncertainty, contradiction handling, temporal context, evidence specificity, exact locators where maintained, and a small integrity-checked retained-excerpt layer for narrow historical attribution questions.
  x-evidence-standard:
    version: 1.1.0
    principles:
    - Only maintained claims with status supported are eligible to produce an unqualified verification verdict.
    - Contextual, disputed, and outdated claims may be returned as context but cannot independently verify or falsify a proposition.
    - Primary and official sources are preferred when available, but source authority is reported separately from claim-match confidence.
    - Exact locator-backed evidence is distinguished from source-level evidence. A source URL alone is not represented as exact passage-level support.
    - Retained primary-source excerpts are integrity-checked and explicitly scoped. Their presence does not imply passage-level verification for the broader Fact Graph.
    - Historical attribution questions without a sufficiently matched retained dossier stop with an explicit evidence gap instead of receiving a generic topical answer.
    - Source count and publisher diversity are descriptive and must not be treated as proof of independent confirmation.
    - Contradiction review reports maintained conflicting evidence only; absence of a conflict does not prove that no contrary evidence exists elsewhere.
    - Currentness is represented through explicit asOf, validThrough, or reverifyAfter metadata when maintained. Dataset update time alone is not treated as a source verification date.
    - Insufficient evidence is a valid research result. Payment does not guarantee coverage or a favorable verdict.
    citationPrecision:
    - retained_excerpt
    - exact_locator
    - source_level
    verdicts:
    - supported
    - mostly_supported
    - 'false'
    - mixed
    - partially_verified
    - insufficient_evidence
  contact:
    email: hello@californiabitcoin.org
  x-source-freshness:
    schemaVersion: bitcoin-source-watch-summary.v1
    coverageEndpoint: https://californiabitcoin.org/api/agent/v1/coverage
    watchedAuthoritativeSources: 18
    trustRule: Source changes are detected and mapped to maintained claims, but never automatically promoted into trusted Bitcoin knowledge.
    persistenceBoundary: Discovery and paid responses report persisted reviewed source-watch state. The scheduled watcher alerts on upstream drift; it does not silently rewrite trusted state.
    lastCheckedMeaning: Time a machine successfully attempted or completed an upstream identity check. It is operational metadata only.
    lastAttemptedMeaning: Most recent persisted machine check attempt, successful or failed. Failed attempts do not advance lastChecked or semantic verification.
    lastVerifiedMeaning: Time maintained Bitcoin meaning was semantically verified against evidence. Machine availability or an unchanged hash must never advance it.
servers:
- url: https://californiabitcoin.org
tags:
- name: A2a
paths:
  /a2a:
    post:
      security: []
      operationId: californiaBitcoinA2a
      summary: Delegate synchronous Bitcoin specialist work through A2A 1.0 JSON-RPC
      description: A2A 1.0 synchronous direct-message delegation over the same maintained California Bitcoin evidence substrate. Supports grounded Bitcoin research, retained primary-source attribution when covered, and free evidence-checkpoint comparison. Streaming, push notifications, persistent tasks, and paid A2A execution are not advertised in v1.
      parameters:
      - name: A2A-Version
        in: header
        required: true
        schema:
          type: string
          const: '1.0'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
            example:
              jsonrpc: '2.0'
              id: 1
              method: SendMessage
              params:
                message:
                  messageId: client-message-1
                  role: ROLE_USER
                  parts:
                  - text: Did Satoshi ever describe Bitcoin as anonymous?
      responses:
        '200':
          description: A2A JSON-RPC response
        '400':
          description: Malformed JSON or invalid request envelope
      tags:
      - A2a
x-service-info:
  categories:
  - bitcoin
  - verification
  - evidence
  - research
  - knowledge
  - ai-agents
  - mcp
  - data
  - search
  - developer-tools
  - a2a
  - agent-to-agent
  - delegation
  docs:
    homepage: https://californiabitcoin.org/developers/
    apiReference: https://californiabitcoin.org/developers/
    llms: https://californiabitcoin.org/llms.txt
  a2a:
    agentCard: https://californiabitcoin.org/.well-known/agent-card.json
    endpoint: https://californiabitcoin.org/a2a
    protocolVersion: '1.0'
    protocolBinding: JSONRPC