⚡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)

---

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:

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

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:

#!/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:

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

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

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

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

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

• Add treasury management patterns for rebalancing and yield

• Combine with Starknet trading or Flashnet trading for agents that both pay and trade