# btcmatic-mcp-server

MCP server for the [BTCMatic agent API](https://btcmatic.com/integrations/agents): 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

```json
{
	"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](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 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

```sh
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