satsrail-mcp

<p align="center"> <h1 align="center">⚡ satsrail-mcp</h1> <p align="center"> <strong>Bitcoin Lightning payments for AI agents via Model Context Protocol</strong> </p> <p align="center"> <a href="https://github.com/SatsRail/satsrail-mcp/blob/main/CHANGELOG.md"><img src="https://img.shields.io/github/package-json/v/SatsRail/satsrail-mcp" alt="version"></a> <a href="https://github.com/SatsRail/satsrail-mcp/actions/workflows/test.yml"><img src="https://github.com/SatsRail/satsrail-mcp/actions/workflows/test.yml/badge.svg" alt="tests"></a> <a href="https://github.com/SatsRail/satsrail-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/SatsRail/satsrail-mcp" alt="license"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/protocol-MCP-blue" alt="MCP"></a> <a href="https://www.satsrail.com/"><img src="https://img.shields.io/badge/payments-Lightning-orange" alt="Lightning"></a> </p> </p>

---

Give any MCP-compatible AI agent the ability to accept Bitcoin Lightning payments. Create orders, generate invoices, check payment status — all through natural language. No browser, no forms, no redirects.

Works with: Claude Desktop · Cursor · Windsurf · Cline · any MCP client

Why Lightning for AI Agents?

	Credit Cards	Lightning (SatsRail)
Integration	Browser forms, 3D Secure, redirects	One API call → invoice string
Settlement	2-3 business days	Instant (seconds)
Fees	2.9% + $0.30 per transaction	Fractions of a cent
Microtransactions	Economically irrational under $5	Works at any amount
Agent-friendly	Requires browser rendering	Pure API — no UI needed
Custody	Funds held by processor	Non-custodial — you keep your sats

Quick Start

1. Get your API key

Sign up at satsrail.com and grab your secret key (sk_live_... or sk_test_...) from the dashboard.

2. Configure your AI tool

<details> <summary><strong>Claude Desktop</strong></summary>

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "satsrail": {
      "command": "npx",
      "args": ["-y", "satsrail-mcp"],
      "env": {
        "SATSRAIL_API_KEY": "sk_test_your_key_here"
      }
    }
  }
}

</details>

<details> <summary><strong>Cursor / Windsurf</strong></summary>

Add to .cursor/mcp.json (or .windsurf/mcp.json) in your project:

{
  "mcpServers": {
    "satsrail": {
      "command": "npx",
      "args": ["-y", "satsrail-mcp"],
      "env": {
        "SATSRAIL_API_KEY": "sk_test_your_key_here"
      }
    }
  }
}

</details>

<details> <summary><strong>Any MCP client (npx)</strong></summary>

SATSRAIL_API_KEY=sk_test_... npx satsrail-mcp

</details>

3. Use it

Ask your AI agent:

"Create a $25 order for a monthly subscription and generate a Lightning invoice"

The agent calls create_order, returns the bolt11 Lightning invoice, and the customer pays with any Lightning wallet. Settlement in seconds.

Available Tools

46 tools covering the full SatsRail merchant API.

Orders

Tool	Description
create_order	Create a payment order with optional auto-generated Lightning invoice. Supports idempotency_key.
get_order	Get order details by ID (expandable: invoice, payment, merchant)
list_orders	List and filter orders by status, currency, amount range, date range
update_order	Update a pending order, mark cash orders paid, mark paid orders shipped
cancel_order	Cancel a pending order

Invoices

Tool	Description
get_invoice	Get invoice details including bolt11 Lightning payment string
generate_invoice	Generate a new invoice for an existing order. Supports idempotency_key.
check_invoice_status	Real-time payment verification against the Lightning node
get_invoice_qr	Get a QR code (SVG) for an invoice

Payments

Tool	Description
list_payments	List confirmed payments with optional date and amount filters
get_payment	Get payment details by ID

Payment Requests

Tool	Description
create_payment_request	One-call flow: creates an Order and Invoice together. Supports idempotency_key.
get_payment_request	Get details of a payment request
get_payment_request_status	Real-time payment status

Checkout Sessions

Tool	Description
create_checkout_session	Create a hosted checkout. Supports product_id, customer pre-fill, success/cancel URLs
list_checkout_sessions	List sessions with filters
get_checkout_session	Get session by ID

Products

Tool	Description
list_products	List products with name/status/SKU/external_ref filters
get_product	Get a product (UUID or slug)
create_product / update_product / delete_product	Full CRUD
get_product_key	Read the AES-256-GCM encryption key (sensitive — for re-encryption windows)
rotate_product_key	Rotate the encryption key, retaining old_key for re-encryption
clear_product_old_key	Clear old_key after re-encryption is complete

Product Types

Tool	Description
list_product_types / get_product_type / create_product_type / update_product_type / delete_product_type	Full CRUD for product categories

Webhooks

Tool	Description
list_webhooks / get_webhook / create_webhook / update_webhook / delete_webhook	Full CRUD for webhook endpoints (signing secret returned once on create)

Catalog & Merchant

Tool	Description
get_catalog	Full catalog: product types, products, taxes, discounts
get_catalog_version	Lightweight version timestamp for cache invalidation
get_merchant	Current merchant profile and settings
list_wallets / get_wallet	Connected Lightning / Bitcoin wallets

Compliance & Access

Tool	Description
list_merchant_documents / get_merchant_document	Read KYC and compliance documents (uploads and deletions are admin-only)
verify_access_token	Verify a macaroon access token, returns key + remaining time on success
get_api_token_usage	RPM and monthly request stats for an API token
list_subscription_plans	Public list of subscription plans (no auth required)

All list_* tools accept page and per_page (1–100, default 25). All metadata fields follow the portal's limits: ≤50 keys, ≤40-char keys, ≤500-char string values.

Example: Complete Payment Flow

User: "Charge me $50 for the pro plan"

Agent → create_order(amount_cents: 5000, description: "Pro Plan", generate_invoice: true)
     ← order_id: "ord_abc123", bolt11: "lnbc500u1pj...kqq5yxmetu"

Agent: "Here's your Lightning invoice — scan the QR or copy the payment string."

User: "Paid!"

Agent → check_invoice_status(invoice_id: "inv_xyz789")
     ← { status: "paid", settled_at: "2026-02-19T..." }

Agent: "Payment confirmed! Your Pro plan is active. ⚡"

Use Cases

• SaaS billing — Agents that sell API access, subscriptions, or per-task services and collect payment in the conversation
• Agent-to-agent commerce — Autonomous agents paying each other for services (translation, compute, data) with instant settlement
• Invoice automation — Generate and send Lightning invoices programmatically based on milestones, usage, or schedules
• Multi-merchant platforms — Build agent-powered marketplaces where AI handles checkout across vendors
• Micropayments — Pay-per-query, pay-per-generation, pay-per-anything — amounts too small for credit cards

Environment Variables

Variable	Required	Description
SATSRAIL_API_KEY	Yes	Your SatsRail API key (sk_live_* or sk_test_*)
SATSRAIL_BASE_URL	No	API base URL (default: https://satsrail.com)

Test Mode

Use sk_test_* keys to create test orders and invoices in a fully isolated sandbox. No real payments processed, no test data mixing with production.

Non-Custodial

SatsRail never holds your funds. Connect your own Lightning node — payments settle directly to your wallet. Learn more about our non-custodial architecture →

SDKs

Need direct API access instead of MCP? Use our SDKs:

• Node.js — npm install satsrail
• Python — pip install satsrail
• Ruby — gem install satsrail

Resources

• Developer Docs — Quickstart, testing, webhooks, embed
• AI Agents Guide — Agent payment flows and architecture
• API Reference — Full REST API documentation
• Use Cases — Bitcoin payments across industries
• Pricing — Zero transaction fees
• Blog — Lightning payments, agent economy, Bitcoin adoption

Local development

git clone https://github.com/SatsRail/satsrail-mcp
cd satsrail-mcp
npm install
npm test            # vitest — unit + smoke against a fake server
SATSRAIL_API_KEY=sk_test_xxx npm start

Drive it interactively with the MCP Inspector:

npx @modelcontextprotocol/inspector node src/index.js

Contributing

Issues and PRs welcome. See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.

---

<p align="center"> <strong>The payment rail for the agent economy.</strong><br> <a href="https://www.satsrail.com/">satsrail.com</a> · <a href="https://x.com/satsrail">@satsrail</a> </p>