AI Agent Flow NEW

Configure MCP Server

Add the SatsRail MCP server to your AI agent's configuration:

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

The MCP server authenticates with the SatsRail API using the sk_live_ key and exposes 12 tools to the agent.

Agent Discovers Tools

When the MCP server starts, it connects to the SatsRail API, validates the key, and advertises all available tools (create_order, check_invoice_status, etc.) to the agent. The agent can now invoke any tool as part of a conversation.

Create Order + Invoice

The agent determines a payment is needed (based on conversation context or autonomous task) and calls:

create_order({
  amount_cents: 2500,
  currency: "usd",
  description: "Monthly subscription",
  generate_invoice: true,
  payment_method: "lightning"
})

SatsRail creates an Order, converts USD → sats, generates a BOLT-11 Lightning invoice from the merchant's node (non-custodial), and returns the order with the bolt11 string.

Present Invoice to Payer

The agent now has a BOLT-11 invoice string. Three paths:

• Path A — Human user: Agent presents the bolt11 string (and optionally a QR code) in the conversation. User scans with their Lightning wallet.
• Path B — Another agent: Agent passes the bolt11 string to another AI agent that has Lightning wallet access. The second agent pays programmatically.
• Path C — Auto-pay: If the agent itself has wallet access (via another MCP server or API), it pays the invoice automatically.

Verify Payment

After payment, the agent calls check_invoice_status to verify:

• completed: Agent proceeds — confirms to user, activates service, delivers product
• pending: Agent waits and re-polls (e.g., every 5 seconds)
• expired: Agent calls generate_invoice to create a new invoice for the same order at the current BTC rate

Checkout Session for Products

For more complex sales, the agent calls create_checkout_session to generate a hosted checkout URL. The agent shares this link with the customer (in chat, email, Slack, etc.). The customer completes the payment through the standard SatsRail checkout flow. The agent polls for completion using check_invoice_status and confirms when paid.

Transaction Reconciliation

The agent can query transaction history for reporting:

• list_payments — retrieve all payments with date range filters
• list_orders — check order statuses
• get_merchant — get merchant profile and settings

All MCP-initiated transactions are also visible in the SatsRail Dashboard, where the merchant can see agent-initiated vs manual transactions side by side.