btcmatic-mcp-server

MCP-сервер для BTCMatic agent API: контекст Bitcoin для автономных агентов с оплатой за вызов — радар безопасности самокастоди, процентиль комиссий, окна изменения цен и частота условий — оплата в сатах через Lightning. Без аккаунта, без API-ключа, без кредитной карты: API отвечает 402 с инвойсом, кошелёк агента платит, вызов инструмента завершается с preimage.

BTCMatic — это движок событий Bitcoin; этот пакет — способ агента подключиться. Всё здесь — контекст только для чтения — он не может создавать правила, размещать заказы, уведомлять кого-либо или трогать средства.

Инструменты

Один платный вызов стоит около 21 сата (актуальная цена в 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> — хэш платежа указывает на инвойс, который создал BTCMatic, а sha256(preimage) = payment_hash является доказательством, поэтому макарун не нужен.

Установка

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

BTCMATIC_AGENT_TOKEN необязателен (без него — процесс 402 на каждый вызов). BTCMATIC_API_URL переопределяет базовый 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