BTCMatic for agents

Last updated: August 2026

An autonomous agent should not need a signup form, a credit card or an API key to ask what the Bitcoin network is doing. The agent API answers HTTP 402 with a Lightning invoice; pay it — about 21 sats — and retry with the payment preimage. That is the whole contract. What you get back is context: the open security incidents on the radar, where today's fee sits against the last 90 days, how the price moved, and how often a condition actually occurred. Never a recommendation.

What it sells — and what it does not

• Radar — open and corroborated self-custody incidents (the same timeline as /radar), per-product chatter counts with the number of distinct sources behind them, and the per-source precision ledger built from manually labeled items.
• Context — latest price with 1h/24h/7d change, next-block fee and its percentile over the trailing 90 days of hourly averages, mempool size. Values older than five minutes are withheld; missing history is reported as missing, not interpolated.
• Condition frequency — "how often did price_change_pct(24h) ≤ −5 happen in the last 90 days?" Counted at hourly resolution as rising edges, the way a throttled rule would have fired.
• Nothing else. The agent API is read-only. It cannot create rules, place orders, send notifications or touch any account. The notify-only wall that protects the security radar applies here in full — no signal, no execution, no hit-rate claims.

Per call: 402 → pay → retry

# 1. ask — no credentials
curl -s https://api.btcmatic.com/agent/context
# → 402 {"price_sats":21,"bolt11":"lnbc210n1…","payment_hash":"9f2c…","expires_at":"…"}
#   WWW-Authenticate: L402 invoice="lnbc210n1…", payment_hash="9f2c…"

# 2. pay the bolt11 with any Lightning wallet; it hands you the preimage

# 3. retry with the proof — single use
curl -s https://api.btcmatic.com/agent/context \
  -H 'Authorization: L402 9f2c…:<preimage>'
# → 200 {"price":{"value":…,"change_pct":{"1h":…,"24h":…,"7d":…}},
#        "fees":{"sat_vb_next":…,"percentile_90d":…},"data_quality":{…},"meta":{…}}

The credential is L402 <payment_hash>:<preimage>. We do not issue macaroons: the payment hash already names an invoice we minted, and sha256(preimage) = payment_hash is the proof of payment, verified in constant time. Each proof is accepted exactly once — a replay is 401, as is a wrong preimage, an unpaid invoice or a hash we never issued (one error code for all of them, on purpose). Invoices expire after ten minutes; minting is budgeted per IP.

Prepaid: top up once, call many times

# mint a top-up invoice (210–210 000 sats)
curl -s -X POST https://api.btcmatic.com/agent/topup \
  -H 'content-type: application/json' -d '{"amount_sats":2100}'
# → 201 {"payment_hash":"…","bolt11":"…"}

# pay it, then claim the credit with the preimage (the hash alone is never enough)
curl -s -X POST https://api.btcmatic.com/agent/topup/claim \
  -H 'content-type: application/json' \
  -d '{"payment_hash":"…","preimage":"…"}'
# → 201 {"token":"agt_…","balance_sats":2100}   ← shown once, store it

# every paid call now debits the balance; 402 again at zero
curl -s 'https://api.btcmatic.com/agent/context/frequency?metric=price_change_pct&window=24h&op=lte&value=-5' \
  -H 'Authorization: Bearer agt_…'

The bearer token is hashed at rest and shown exactly once. Anyone can see a payment hash (it is in the 402 body), so a hash alone never yields a token — the claim needs the preimage. GET /agent/credits with the token shows the balance, free.

MCP server

btcmatic-mcp-server wraps the flow as Model Context Protocol tools — btcmatic_quote, btcmatic_radar, btcmatic_context, btcmatic_condition_frequency, btcmatic_topup — so an LLM agent can discover the price, pay (through a wallet you control) and fetch without ever seeing raw HTTP. Add it to any MCP-capable client:

{
  "mcpServers": {
    "btcmatic": {
      "command": "npx",
      "args": ["-y", "btcmatic-mcp-server"],
      "env": { "BTCMATIC_AGENT_TOKEN": "agt_…" }
    }
  }
}

Without a prepaid token the tools still work: btcmatic_quote hands the agent a bolt11 to pay and the call completes with the preimage. The server holds no keys and signs nothing — paying is always your wallet's decision.

Honesty, in the response

• Every paid response carries a meta block: the price you paid, your remaining balance, a disclaimer, and a signup link. The same numbers are free with an account — the API exists for clients that cannot have one.
• Per-source precision is computed from labels we set by hand and publish on /radar; an unlabeled source shows no precision at all.
• Fee percentile, change windows and frequency are descriptive statistics over public series. They describe the past; they do not predict anything.

Reference

The discovery document at GET https://api.btcmatic.com/agent lists prices, endpoints and the flow in machine-readable form; the full OpenAPI spec lives at /docs on the API (tag agent). Need rules, backtests or notifications from an automation? That is the authenticated surface — API keys and the n8n node.