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

2. Configure your AI tool

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"
      }
    }
  }
}

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"
      }
    }
  }
}

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

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.

satsrail-mcp