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 answersplan_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_requiredunless 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_order | With 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_item | Build a draft order from catalog products or freeform items; taxes are worked out per item |
create_order_payment_link | One link for a draft order's total, paid once before it expires |
send_order_payment_email / send_order_reminder | Email the customer the link, or a reminder while it is unpaid |
get_order / list_orders / cancel_order | Read, list and cancel orders |
get_invoice / get_invoice_qr | An invoice's Lightning string (or on-chain address), and its QR code as SVG |
check_invoice_status | Whether 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_invoice | The 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_session | A hosted checkout for an amount or a product, and its checkout_url; read back as completed once paid |
create_payment_link | A reusable payment link (/pay/…) from a name and a price |
list_payments / get_payment | Confirmed payments |
list_sales / get_sale | The sales ledger: every paid order and refund, kept after the order is deleted |
list_unfulfilled_orders / mark_order_fulfilled | Paid orders still to deliver, and marking one shipped or delivered |
create_webhook | A webhook endpoint, for payment.received and the other events |
get_merchant / list_wallets | The merchant's profile and settings, and its wallets |
A payment, step by step
create_orderwithamount_cents, in the merchant's currency:invoice.payment_requestis the Lightning invoice.- Show the person the invoice, or its QR code from
get_invoice_qr; they pay from their own wallet, straight to the merchant's. check_invoice_statusuntilstatusispaid, or wait for thepayment.receivedwebhook.- If it reads
expired,generate_invoicefor 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.
Payment links for agents
A payment link (https://www.satsrail.com/pay/prod_…) opens the hosted checkout for one product at
one price. It never expires and can be paid any number of times. That makes it the thing an agent hands to a person:
-
Selling. The merchant's agent calls
create_payment_linkwith a name and a price and gets backpayment_link_urlto send the customer. Every product the API returns carries itspayment_link_urltoo (null while the product is inactive). - Buying for someone. An agent paying a SatsRail merchant for the person it works for sends that person the merchant's payment link, and they pay the merchant directly from their own wallet.
Before forwarding a link, read it: the same URL with .json (or Accept: application/json)
describes it and opens no checkout. No key is needed.
GET https://www.satsrail.com/pay/prod_4f1c9e2a7b3d8e6f5a1c0b9d.json
{
"object": "payment_link",
"url": "https://www.satsrail.com/pay/prod_4f1c9e2a7b3d8e6f5a1c0b9d",
"name": "Sunset kayak tour",
"amount_cents": 4500,
"currency": "usd",
"formatted_amount": "$45.00",
"merchant": { "name": "Ember Tours" },
"payable": true,
"payment_methods": ["lightning"],
"how_to_pay": "Open the url in a browser and pay from a bitcoin wallet. ..."
}
payable is false while the merchant has no wallet that can take the price; say so rather than send a
link that shows an unavailable page. An inactive or unknown link answers 404.
amount_cents is what the checkout opens at, taxes included. A product sold in more than one option
(sizes, colors) adds options, each with its id, name,
amount_cents, formatted_amount and sold_out: the person chooses one when the
link opens, so tell them the choices and their prices.