AI Agent Flow NEW

Configure MCP Server

Point your AI agent at the hosted SatsRail MCP endpoint:

{
  "mcpServers": {
    "satsrail": {
      "type": "http",
      "url": "https://satsrail.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_live_your_key_here" }
    }
  }
}

The client sends the sk_live_ key as a bearer header, and the hosted server exposes 45 tools to the agent.

Agent Discovers Tools

On connect, the client calls tools/list; the hosted server validates the bearer token 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.