# 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 https://btcmatic.com/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

```sh
# 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":{…},"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

```sh
# 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` (https://github.com/btcmatic-com/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:

```json
{
  "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 https://btcmatic.com/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 https://api.btcmatic.com/docs (tag `agent`). Need rules, backtests or notifications from an automation? That is the authenticated surface — API keys and the n8n node: https://btcmatic.com/integrations/n8n

---

Canonical page: https://btcmatic.com/integrations/agents  
Machine index: https://btcmatic.com/llms.txt · Agent notes: https://btcmatic.com/agents.md