# AI Agents

> Let AI agents accept Bitcoin payments programmatically. MCP server, zero-browser payment flow, and agent-friendly API for Claude, Cursor, and any LLM tool.

Source: https://www.satsrail.com/developers/guides/ai-agents/

The only payment processor AI agents can use natively.
No browser. No forms. Just an API call and a Lightning invoice string.

## Why Lightning Is Perfect for AI Agents

##### Credit Cards

- Require browser forms & 3D Secure
- PCI compliance burden
- Card numbers agents can't handle safely
- Chargebacks and fraud checks
- Banks can freeze accounts anytime

##### Lightning (SatsRail)

- One API call → invoice string
- No browser, no forms, no redirects
- Instant settlement
- No chargebacks — payment is final
- Non-custodial — no account freezes

## MCP Server

The SatsRail MCP server gives any AI agent with [Model Context Protocol](https://modelcontextprotocol.io/) support the ability to create orders, generate invoices, and check payment status.

##### Connect to the hosted server

SatsRail hosts the 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 and authenticate with a secret key.

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

Works in Claude Code, Claude Desktop, Cursor, Windsurf and any Streamable-HTTP MCP client. Stdio-only clients can bridge to the URL with `mcp-remote`.

No key to paste? A client that supports OAuth connects with the URL alone: you sign in, pick the business and approve. Those connections manage your catalog and payment links only, and you can revoke them any time under Settings → AI Assistants.

## Available Tools

The hosted server exposes 53 tools: orders (built item by item, sent as one payment link, delivered), invoices, payments, the sales ledger, checkout, payment links, products and the catalog, webhooks, wallets and account data. These are the core payment tools; `tools/list` returns them all:

| Tool | Description |
| --- | --- |
| `create_order` | Create a payment order with optional auto-generated Lightning invoice, or, without an amount, an empty draft to build item by item |
| `add_order_item` | Add a catalog product or a freeform item to a draft order; taxes are worked out per item and the order's totals come back |
| `update_order_item` / `remove_order_item` | Change an item's quantity, price or tax rate, or remove it, while the order is a draft |
| `create_order_payment_link` | One payment link for the whole order, taxes included, paid once before it expires |
| `send_order_payment_email` / `send_order_reminder` | Email the customer the link on the merchant's behalf, with the merchant's logo and the order summary, or remind them while it is unpaid |
| `list_unfulfilled_orders` / `mark_order_fulfilled` | The paid orders still to deliver, oldest first, and marking one shipped (with a tracking note) or delivered |
| `get_order` | Get order details by ID: items with their taxes, totals, payment link, expiry and delivery (expandable: invoice, payment, merchant) |
| `list_orders` | List orders with optional status filter |
| `cancel_order` | Cancel a pending order |
| `get_invoice` | Get invoice details including bolt11 Lightning string |
| `check_invoice_status` | Real-time payment status check against the Lightning node |
| `generate_invoice` | Generate a new invoice for an existing order |
| `list_payments` | List confirmed payments with optional date range filter |
| `get_payment` | Get payment details |
| `list_sales` / `get_sale` | The sales ledger: every paid order with its amounts, bitcoin price, proof of payment and items, kept after the order itself is deleted; filter by status, payment method or date sold. A sale's id is its order's |
| `create_checkout_session` | Create a hosted checkout session with redirect URL |
| `create_payment_link` | Create a reusable payment link (`/pay/…`) from a name and a price, to send a customer by chat, email or text |
| `get_merchant` | Get the current merchant's profile and settings |
| `list_wallets` | List connected wallets |

## Agent Payment Flow

A complete payment takes 3 steps — no browser involved at any point.

##### 1. Create Order

Agent calls `create_order` with amount and description. SatsRail returns an order with a bolt11 Lightning invoice string.

##### 2. Customer Pays

Agent presents the bolt11 string or a QR code to the customer. Customer pays with any Lightning wallet.

##### 3. Confirm

Agent calls `check_invoice_status` to verify payment, or listens for a webhook. Done.

##### Example Conversation

User "Charge me $25 for the monthly subscription"

Agent *→ calls create_order(amount_cents: 2500, generate_invoice: true)*

Agent "Here's your Lightning invoice. Scan this QR code or copy the payment string:"

lnbc250u1pj...kqq5yxmetu

User "Paid!"

Agent *→ calls check_invoice_status(invoice_id: "...")*

Agent "Payment confirmed! Your subscription is active. ⚡"

## 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_link` with a name and a price and gets back `payment_link_url` to send the customer. Every product the API returns carries its `payment_link_url` too (null while the product is inactive).
- **Buying for someone.** An agent that needs to pay a SatsRail merchant for the person it works for doesn't need a wallet, a key or a card: it sends that person the merchant's payment link, and they pay from their own wallet. The money goes straight to the merchant; the agent never holds funds.

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`.

##### Example Conversation

User "Book me the sunset kayak tour on Saturday."

Agent *→ finds the tour's payment link on the operator's site, reads it with .json*

Agent "Ember Tours charges $45.00 for the Sunset kayak tour. Pay here and they'll confirm your spot: https://www.satsrail.com/pay/prod_4f1c…"

## Direct REST API

Don't need MCP? Any agent that can make HTTP requests can use SatsRail directly. The entire flow is JSON in, JSON out — no redirects, no HTML.

##### Create order + invoice in one call

```
curl -X POST https://app.satsrail.com/api/v1/m/orders \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order": {
      "total_amount_cents": 2500,
      "currency": "usd"
    },
    "generate_invoice": true,
    "payment_method": "lightning"
  }'
```

##### Check payment status

```
curl https://app.satsrail.com/api/v1/m/invoices/{invoice_id}/status \
  -H "Authorization: Bearer sk_test_..."
```

[Full API Reference →](https://www.satsrail.com/developers/)

## Use Cases

##### SaaS & API Billing

Agents that sell access to services and collect payment in the conversation. Per-call, per-session, or per-task billing with no checkout page.

##### Agent-Generated Invoicing

Agents that create fresh invoices when payment is due — milestone billing, on-demand charges, or periodic collections.

##### Multi-Merchant Platforms

Build agent-powered marketplaces where AI handles the checkout flow across multiple merchants.

##### Invoicing Bots

Agents that send invoices, track payments, and follow up — from Slack, Discord, Telegram, or any chat platform.

## Configuration

| Setting | Required | Description |
| --- | --- | --- |
| URL | Yes | `https://app.satsrail.com/api/v1/mcp`, over Streamable HTTP. |
| `Authorization` header | Yes, unless you use OAuth | `Bearer sk_test_*` for testing, `Bearer sk_live_*` for production. |
| OAuth | No | Discovery starts at `https://app.satsrail.com/.well-known/oauth-protected-resource/api/v1/mcp`. An OAuth connection gets the catalog tools only. |

## Build the future of AI payments

Get your API key and let your agents start accepting Bitcoin in minutes.

[Get Your API Key →](https://satsrail.com/users/sign_up) [MCP Server](https://www.satsrail.com/mcp/)