Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@btcmatic-mcp-server check the self-custody radar for any open incidents"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Tool | Paid | What it does |
| no | Prices, prepaid bounds and the payment flow — call first |
| yes | Open/corroborated self-custody incidents, per-product chatter counts with distinct-source counts, per-source precision ledger |
| yes | Latest price with 1h/24h/7d change, next-block fee + its 90-day percentile, mempool size; stale values withheld, gaps reported |
| yes | How often |
| no | Mint a prepaid top-up invoice |
| no | Prove the top-up with its preimage → bearer token (shown once) |
| no | Prepaid balance and calls remaining |
One paid call costs about 21 sats (the live price is in btcmatic_discover).
Related MCP server: x402-api
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 }.
Your wallet pays the bolt11 and shows the preimage.
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.
{
"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).
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.
pnpm install
pnpm build && pnpm test && pnpm lint
BTCMATIC_API_URL=http://localhost:3000 node dist/cli.js # stdio transportAgent 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
MIT
Counts, at hourly resolution, how often a single condition became true in the trailing 90 days (rising edges — what a throttled rule would have fired) and how many hours it held. Metrics: price_change_pct (needs window 1h|24h|7d), fee_next_block (sat/vB), mempool_vsize (vbytes). Operators: <, <=, >, >=. Past frequency, not a forecast.
Inputs: op (required), value (required), metric (required), window, +2 more.
Latest BTC price with 1h/24h/7d change, next-block fee (sat/vB) with its percentile over the trailing 90 days of hourly averages, and mempool size. Values older than 5 minutes come back null; missing history is reported in data_quality, never interpolated. Descriptive only.
Inputs: preimage, payment_hash.
Free. The balance behind the configured prepaid token (BTCMATIC_AGENT_TOKEN) and how many calls it still covers.
Inputs: token.
Free. What the BTCMatic agent API offers, what one call costs in sats, the prepaid bounds and the payment flow. Call this first.
Inputs: no named parameters.
Open and corroborated self-custody security incidents (hardware/software wallets, nodes, payment stacks), per-product feed chatter counts with the number of distinct sources behind them, and the per-source precision ledger from manually labeled items. Counts and labels only — no verdicts. Costs one call; without payment the 402 offer is returned as data.
Inputs: product, preimage, payment_hash.
Free. Mints a Lightning invoice for a prepaid balance (see btcmatic_discover for the min/max). Pay it with a wallet you control, then call btcmatic_topup_claim with the preimage. The payment hash alone never yields a token.
Inputs: amount_sats (required).
Proves the top-up payment with its preimage and receives the prepaid token EXACTLY ONCE. Store it and restart this server with BTCMATIC_AGENT_TOKEN= so every paid tool debits the balance automatically.
Inputs: preimage (required), payment_hash (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 7 tools
Each tool addresses a distinct concern: discovery, security radar, market context, historical condition frequency, pre-payment minting, token claiming, and balance checks. There is no overlap or ambiguity between them; even the related topup and topup_claim are clearly stage-separated.
All tools share the 'btcmatic_' prefix, but the second part mixes nouns (radar, context, credits) and verbs (discover, topup_claim). The pattern is predictable and readable, but not a strict verb_noun convention, so it loses a point for minor stylistic inconsistency.
Seven tools is well within the ideal range for a focused MCP server. Each tool earns its place covering the API's core functions (information, data, condition analysis, payment lifecycle, and account status) without redundancy or bloat.
The tool surface covers the full lifecycle: discovery, market data, historical condition analysis, the prepaid payment flow (mint, claim, balance), and security radar. There are no obvious missing operations that would hinder an agent's ability to accomplish the server's intended tasks.
Pay-per-action access to APIs and MCP tools over Lightning L402 and Base USDC x402.
Bitcoin MCP: fees, tx proofs, address checks. Pay per call by x402, Lightning or a prepaid pass.
Pay-per-call DeFi and macro intel for AI agents. x402 USDC tools via streamable HTTP /api/mcp.
Bitcoin intelligence API. Pay per call via L402 Lightning (10-200 sats). No accounts needed.
