Skip to main content
Glama
btcmatic-com

btcmatic-mcp-server

Official
by btcmatic-com
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

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

License

MIT