AI agents

An AI assistant that takes payments for a merchant over MCP, or sends a person a link to pay.

Connect to the hosted server

SatsRail hosts the MCP server at https://app.satsrail.com/api/v1/mcp. It speaks Streamable HTTP (one JSON-RPC message per POST), so there is nothing to install: point your client at the URL with a secret key.

{
  "mcpServers": {
    "satsrail": {
      "type": "http",
      "url": "https://app.satsrail.com/api/v1/mcp",
      "headers": { "Authorization": "Bearer sk_test_your_key_here" }
    }
  }
}
  • Keys. A test key (sk_test_...) works on every plan. A live key (sk_live_...) or an OAuth connection needs the merchant on the Pro plan: on Free or Starter every tool call answers plan_feature_unavailable.
  • OAuth. A client that supports OAuth connects with the URL alone: you sign in, pick the business and approve. The connection can do what you can do at that business, and you can revoke it under Settings → AI Assistants. Discovery starts at https://app.satsrail.com/.well-known/oauth-protected-resource/api/v1/mcp.
  • Two-factor authentication. A tool that creates, changes or deletes anything answers two_factor_required unless the SatsRail account behind the key (whoever made it, or connected the assistant) has two-factor authentication on, under Account settings. Read-only tools work either way.
  • Clients. Any MCP client that speaks Streamable HTTP; a stdio-only client through mcp-remote.

Tools

tools/list returns the tools your key may call: what its security groups allow, among the features the business has on. These are the ones a payment uses.

Tool What it does
create_orderWith amount_cents: an order and its invoice (Lightning, or on-chain if asked for). Without: an empty draft to fill item by item
add_order_item / update_order_item / remove_order_itemBuild a draft order from catalog products or freeform items; taxes are worked out per item
create_order_payment_linkOne link for a draft order's total, paid once before it expires
send_order_payment_email / send_order_reminderEmail the customer the link, or a reminder while it is unpaid
get_order / list_orders / cancel_orderRead, list and cancel orders
get_invoice / get_invoice_qrAn invoice's Lightning string (or on-chain address), and its QR code as SVG
check_invoice_statusWhether an invoice is paid. For Lightning it asks the merchant's wallet provider (its LUD-21 verify URL); for on-chain it reports what SatsRail last saw on the chain
generate_invoiceThe invoice for an order still waiting for a bitcoin payment: the one it has if still good, or a new one once it ran out
create_checkout_session / get_checkout_sessionA hosted checkout for an amount or a product, and its checkout_url; read back as completed once paid
create_payment_linkA reusable payment link (/pay/…) from a name and a price
list_payments / get_paymentConfirmed payments
list_sales / get_saleThe sales ledger: every paid order and refund, kept after the order is deleted
list_unfulfilled_orders / mark_order_fulfilledPaid orders still to deliver, and marking one shipped or delivered
create_webhookA webhook endpoint, for payment.received and the other events
get_merchant / list_walletsThe merchant's profile and settings, and its wallets

A payment, step by step

  1. create_order with amount_cents, in the merchant's currency: invoice.payment_request is the Lightning invoice.
  2. Show the person the invoice, or its QR code from get_invoice_qr; they pay from their own wallet, straight to the merchant's.
  3. check_invoice_status until status is paid, or wait for the payment.received webhook.
  4. If it reads expired, generate_invoice for the same order, and back to step 2.

Other ways to get paid: create_checkout_session gives a checkout_url for the hosted checkout, where the person can also choose on-chain or a card when the merchant takes them. An order built item by item goes out as one link (create_order_payment_link) or an email (send_order_payment_email). Without MCP, the same order and invoice are REST calls: see the Quickstart.