⚡ satsrail-mcp

Bitcoin Lightning payments for AI agents via Model Context Protocol

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?

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

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

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

SATSRAIL_API_KEY=sk_test_... npx satsrail-mcp

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

Invoices

Payments

Payment Requests

Checkout Sessions

Products

Product Types

Webhooks

Catalog & Merchant

Compliance & Access

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

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.

The payment rail for the agent economy.
satsrail.com · @satsrail