btcmatic-mcp-server

MCP 服务器，用于 BTCMatic agent API：为自主代理提供按次付费的 Bitcoin 上下文——自托管安全雷达、费用百分位、价格变化窗口和条件频率——通过 Lightning 以 sats 支付。无需账户、无需 API 密钥、无需信用卡：API 以 402 响应并附发票，代理的钱包支付，工具调用以 preimage 完成。

BTCMatic 是 Bitcoin 事件引擎；这个包是代理的入口。这里的一切都是只读上下文——它不能创建规则、下单、通知任何人或接触资金。

工具

一次付费调用大约需要 21 sats（实时价格在 btcmatic_discover 中）。

Related MCP server: x402-api

支付方式

1. 调用一个付费工具，不提供证明。结果是以数据形式呈现的 402 报价，而不是错误：{ kind: "offer", price_sats, bolt11, payment_hash, next_step }。

2. 你的钱包支付 bolt11 并显示 preimage。

3. 用 { payment_hash, preimage } 再次调用同一个工具。证明是一次性的。

预付：btcmatic_topup → 支付 → btcmatic_topup_claim → 令牌。用 BTCMATIC_AGENT_TOKEN=agt_… 启动服务器，每个付费工具都会从余额中扣款；余额为零时，工具会返回 { kind: "topup_needed" }。

这个服务器从不持有密钥，也从不支付。它传递证明；支付始终由你控制的钱包决定。证明格式是 Authorization: L402 <payment_hash>:<preimage>——payment hash 指向 BTCMatic 铸造的发票，sha256(preimage) = payment_hash 就是证明，因此不需要 macaroon。

安装

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

BTCMATIC_AGENT_TOKEN 是可选的（没有它时每次调用 402 流程）。BTCMATIC_API_URL 覆盖 API 基础地址（默认 https://api.btcmatic.com）。

这些数字的含义——以及不是什么

• 每个来源的精度来自 BTCMatic 手工设置并在 btcmatic.com/radar 上发布的标签；未标记的来源不会显示任何精度。

• 费用百分位、变化窗口和频率是对公开序列的描述性统计。它们描述过去；它们不预测任何东西，而且这里没有任何内容是购买或出售的建议。

• 每个付费响应都带有一个 meta 块，包含已支付的价格、剩余余额、免责声明和注册链接——同样的数据在 BTCMatic 账户下是免费的；这个 API 是为无法拥有账户的客户端而存在的。

开发

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

资源

• Agent API 文档：https://btcmatic.com/integrations/agents

• OpenAPI（标签 agent）：https://api.btcmatic.com/docs

• BTCMatic 用于自动化（API 密钥、n8n）：https://btcmatic.com/integrations/n8n

许可证

MIT