btcmatic-mcp-server

Servidor MCP para la API de agentes de BTCMatic: contexto de Bitcoin de pago por llamada para agentes autónomos — el radar de seguridad de autocustodia, el percentil de tarifas, las ventanas de cambio de precio y la frecuencia de condiciones — pagado en sats a través de Lightning. Sin cuenta, sin clave de API, sin tarjeta de crédito: la API responde 402 con una factura, la billetera del agente paga, la llamada a la herramienta se completa con la preimagen.

BTCMatic es el motor de eventos de Bitcoin; este paquete es la vía de entrada del agente. Todo aquí es contexto de solo lectura — no puede crear reglas, realizar pedidos, notificar a nadie ni tocar fondos.

Herramientas

Una llamada de pago cuesta alrededor de 21 sats (el precio en vivo está en btcmatic_discover).

Related MCP server: x402-api

Cómo funciona el pago

1. Llame a una herramienta de pago sin prueba. El resultado es la oferta 402 como datos, no un error: { kind: "offer", price_sats, bolt11, payment_hash, next_step }.

2. Su billetera paga el bolt11 y muestra la preimagen.

3. Llame a la misma herramienta nuevamente con { payment_hash, preimage }. La prueba es de un solo uso.

Prepago: btcmatic_topup → pagar → btcmatic_topup_claim → token. Inicie el servidor con BTCMATIC_AGENT_TOKEN=agt_… y cada herramienta de pago debita el saldo; en cero las herramientas responden { kind: "topup_needed" }.

Este servidor nunca guarda claves y nunca paga. Mueve pruebas; pagar es siempre la decisión de una billetera que usted controla. El formato de prueba es Authorization: L402 <payment_hash>:<preimage> — el hash de pago nombra una factura que BTCMatic acuñó y sha256(preimage) = payment_hash es la prueba, por lo que no se necesita macarrón.

Instalación

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

BTCMATIC_AGENT_TOKEN es opcional (flujo 402 por llamada sin él). BTCMATIC_API_URL anula la base de la API (por defecto https://api.btcmatic.com).

Qué son los números — y qué no son

• La precisión por fuente proviene de etiquetas que BTCMatic establece manualmente y publica en btcmatic.com/radar; una fuente sin etiqueta no muestra precisión alguna.

• El percentil de tarifas, las ventanas de cambio y la frecuencia son estadísticas descriptivas sobre series públicas. Describen el pasado; no predicen nada y nada aquí es una recomendación de compra o venta.

• Cada respuesta de pago lleva un bloque meta con el precio pagado, el saldo restante, un descargo de responsabilidad y un enlace de registro — los mismos datos son gratuitos con una cuenta de BTCMatic; esta API existe para clientes que no pueden tener una.

Desarrollo

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

Recursos

• Documentación de la API de agentes: https://btcmatic.com/integrations/agents

• OpenAPI (etiqueta agent): https://api.btcmatic.com/docs

• BTCMatic para automatizaciones (claves de API, n8n): https://btcmatic.com/integrations/n8n

Licencia

MIT