# Agentic Lightning Commerce

Build AI agents that **pay and get paid on Lightning rails** — sub-cent fees, sub-second settlement, fully programmatic. This is the core payment primitive for machine-to-machine commerce on Bitcoin.

### What you'll build

An agent that can:

1. **Accept payments** by creating Lightning invoices via Spark
2. **Make payments** by paying Lightning invoices programmatically
3. **Call paid APIs** that settle over Lightning automatically (MPP)
4. **Manage a continuous commerce loop** — receive payments, process orders, sweep profits to cold BTC storage

### Prerequisites

* Xverse Agentic Wallet CLI installed (`npm i -g @secretkeylabs/xverse-wallet-cli`)
* A funded wallet with BTC on Spark (see [Getting Started](https://claude.ai/chat/getting-started.md))

***

### Step 1: Fund your Spark balance

Lightning payments require BTC on Spark. If your agent's Spark balance is empty, fund it from Bitcoin L1:

```bash
# Check current Spark balance
xverse-wallet spark balance --json

# If empty, deposit from L1 (requires ~30 min for 3 confirmations)
xverse-wallet bitcoin balance --json          # confirm you have native BTC
xverse-wallet spark deposit --amount 0.001 --yes --json

# Wait for confirmations, then claim
xverse-wallet spark claim --json
```

> **Tip:** If you have BTC on another account, check all accounts first: `xverse-wallet portfolio --accounts 0-4 --json`. You can pay from a specific account using `-a <index>`.

### Step 2: Accept payments — create Lightning invoices

Your agent acts as a merchant and generates invoices for incoming payments:

```bash
xverse-wallet spark lightning invoice --amount 50000 --memo "Order #1234" --json
```

This returns a BOLT11 invoice string that any Lightning-enabled wallet or agent can pay. The amount is in satoshis.

**Example agent loop — accept and process orders:**

```bash
#!/bin/bash
# 1. Create an invoice for the order
INVOICE=$(xverse-wallet spark lightning invoice --amount 50000 --memo "Order #1234" --quiet)
echo "Invoice: $INVOICE"

# 2. Poll for payment (check balance / history)
while true; do
  BALANCE=$(xverse-wallet spark balance --json)
  LATEST=$(xverse-wallet spark history --token BTC --limit 1 --json)
  # Parse and check if payment received...
  sleep 5
done

# 3. Process the order
# 4. Optionally sweep to cold storage
```

### Step 3: Make payments — pay Lightning invoices

Your agent pays another service or merchant:

```bash
# Estimate the fee first
xverse-wallet spark lightning estimate --invoice <bolt11> --json

# Pay the invoice
xverse-wallet spark lightning pay --invoice <bolt11> --yes --json
```

The agent can pay any valid BOLT11 invoice — from another Xverse wallet, a BTCPay Server merchant, a Lightning-enabled API, or any node on the Lightning Network.

### Step 4: Call paid APIs automatically (MPP)

The Machine Payments Protocol (MPP) lets your agent call HTTP APIs that require Lightning payment — without any manual payment flow. The CLI handles the full cycle: request → 402 challenge → Lightning payment → credential → response.

```bash
# Preview cost (no payment)
xverse-wallet pay request https://api.secretkeylabs.io/v1/bitcoin/price --json

# Pay and get the response
xverse-wallet pay request https://api.secretkeylabs.io/v1/bitcoin/price --yes --json
```

Your agent can call any MPP-enabled endpoint the same way — data APIs, RPC calls, indexer queries:

```bash
# Get rune info (paid)
xverse-wallet pay request https://api.secretkeylabs.io/v1/runes/DOG%E2%80%A2GO%E2%80%A2TO%E2%80%A2THE%E2%80%A2MOON --yes --json

# Broadcast a transaction (paid POST)
xverse-wallet pay request https://api.secretkeylabs.io/v1/rpc/bitcoin/tx \
  --method POST --body '{"tx":"0200..."}' --yes --json

# Discover all available endpoints
xverse-wallet pay api --json
```

### Step 5: Treasury management — sweep profits

Periodically move accumulated BTC from Spark to cold Bitcoin L1 storage:

```bash
# Check accumulated balance
xverse-wallet spark balance --json

# Sweep to cold BTC vault
xverse-wallet spark withdraw --amount 0.005 --speed fast --yes --json
```

Or rebalance into stablecoins:

```bash
xverse-wallet swap execute --from spark:BTC --to spark:USDB --amount 0.001 --yes --json
```

***

### Putting it all together: continuous commerce loop

Here's the full agent pattern for a Lightning-powered service:

```
┌─────────────────────────────────────────────────┐
│                  Agent Loop                      │
│                                                  │
│  1. Create invoice for customer order            │
│     spark lightning invoice --amount <sats>       │
│                                                  │
│  2. Wait for payment                             │
│     Poll spark history / spark balance            │
│                                                  │
│  3. Process the order                            │
│     (your business logic)                        │
│                                                  │
│  4. Call paid APIs if needed                     │
│     pay request <url> --yes                       │
│                                                  │
│  5. Periodically sweep profits to cold storage   │
│     spark withdraw --amount <btc> --speed fast   │
│                                                  │
│  Loop back to 1.                                 │
└─────────────────────────────────────────────────┘
```

### Key numbers

| Metric             | Value                      |
| ------------------ | -------------------------- |
| Settlement time    | < 1 second                 |
| Transaction fees   | Sub-cent (< $0.001)        |
| Invoice creation   | Instant                    |
| L1 deposit time    | \~30 min (3 confirmations) |
| L1 withdrawal time | Depends on speed setting   |

### What's next

* Explore the [full MPP API catalog](https://claude.ai/chat/machine-payments-mpp.md) to see what paid APIs are available
* Add [treasury management](https://claude.ai/chat/portfolio-and-treasury.md) patterns for rebalancing and yield
* Combine with [Starknet trading](https://claude.ai/chat/guide-starknet-trading.md) or [Flashnet trading](https://claude.ai/chat/guide-flashnet-trading.md) for agents that both pay and trade