btcmatic-mcp-server

MCP server for the BTCMatic agent API: pay-per-call Bitcoin context for autonomous agents — the self-custody security radar, fee percentile, price change windows and condition frequency — paid in sats over Lightning. No account, no API key, no credit card: the API answers 402 with an invoice, the agent's wallet pays, the tool call completes with the preimage.

BTCMatic is the Bitcoin event engine; this package is the agent's way in. Everything here is read-only context — it cannot create rules, place orders, notify anyone or touch funds.

Tools

Tool	Paid	What it does
btcmatic_discover	no	Prices, prepaid bounds and the payment flow — call first
btcmatic_radar	yes	Open/corroborated self-custody incidents, per-product chatter counts with distinct-source counts, per-source precision ledger
btcmatic_context	yes	Latest price with 1h/24h/7d change, next-block fee + its 90-day percentile, mempool size; stale values withheld, gaps reported
btcmatic_condition_frequency	yes	How often metric op value became true in the trailing 90 days (hourly resolution, rising edges) and how many hours it held
btcmatic_topup	no	Mint a prepaid top-up invoice
btcmatic_topup_claim	no	Prove the top-up with its preimage → bearer token (shown once)
btcmatic_credits	no	Prepaid balance and calls remaining

One paid call costs about 21 sats (the live price is in btcmatic_discover).

How payment works

1. Call a paid tool with no proof. The result is the 402 offer as data, not an error: { kind: "offer", price_sats, bolt11, payment_hash, next_step }.
2. Your wallet pays the bolt11 and shows the preimage.
3. Call the same tool again with { payment_hash, preimage }. The proof is single use.

Prepaid: btcmatic_topup → pay → btcmatic_topup_claim → token. Start the server with BTCMATIC_AGENT_TOKEN=agt_… and every paid tool debits the balance; at zero the tools answer { kind: "topup_needed" }.

This server never holds keys and never pays. It moves proofs; paying is always the decision of a wallet you control. The proof format is Authorization: L402 <payment_hash>:<preimage> — the payment hash names an invoice BTCMatic minted and sha256(preimage) = payment_hash is the proof, so no macaroon is needed.

Install

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

BTCMATIC_AGENT_TOKEN is optional (per-call 402 flow without it). BTCMATIC_API_URL overrides the API base (default https://api.btcmatic.com).

What the numbers are — and are not

• Per-source precision comes from labels BTCMatic sets by hand and publishes on 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 and nothing here is a recommendation to buy or sell.
• Every paid response carries a meta block with the price paid, the remaining balance, a disclaimer and a signup link — the same data is free with a BTCMatic account; this API exists for clients that cannot have one.

Development

pnpm install
pnpm build && pnpm test && pnpm lint
BTCMATIC_API_URL=http://localhost:3000 node dist/cli.js   # stdio transport

Resources

• Agent API docs: https://btcmatic.com/integrations/agents
• OpenAPI (tag agent): https://api.btcmatic.com/docs
• BTCMatic for automations (API keys, n8n): https://btcmatic.com/integrations/n8n

License

MIT