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

{% hint style="info" %}
**The Xverse API is fully MPP-enabled.** Every endpoint in the [Xverse API](https://docs.xverse.app/api/) — Bitcoin RPC, Ordinals, Runes, BRC-20, Spark, Swaps, Portfolio — accepts Lightning payment at **1 satoshi per request**, with no API key required. See [MPP Lightning Payments](/api/mpp-lightning-payments.md) in the Xverse API docs for the full spec.&#x20;
{% endhint %}

```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 to see what paid APIs are available
  * Explore the[ **Xverse API**](https://docs.xverse.app/api/) — every endpoint is MPP-enabled and pays via Lightning at 1 sat per request. See [MPP Lightning Payments](/api/mpp-lightning-payments.md) for the full spec, or run `xverse-wallet pay api --json` to discover endpoints from the CLI.
* Add [treasury management](/xverse-agentic-wallet/capabilities/portfolio-and-treasury.md) patterns for rebalancing and yield
* Combine with [Starknet trading](/xverse-agentic-wallet/guides/agentic-starknet-trading.md) or [Flashnet trading](/xverse-agentic-wallet/guides/agentic-flashnet-trading.md) for agents that both pay and trade


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xverse.app/xverse-agentic-wallet/guides/agentic-lightning-commerce.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.