# 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 43 tools: orders, invoices, payments, 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 |
| `get_order` | Get order details by ID (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 |
| `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/)