Ctrlk

⚡ MPP Lightning Payments

The Xverse API supports the Machine Payments Protocol (MPP) — a pay-per-request authentication method over the Lightning Network. Instead of provisioning an API key, your client can pay a small Lightning invoice for each request.

This is built for AI agents and autonomous clients that need to access the API without human-managed credentials. Agents using the Xverse Agent Wallet handle MPP payments transparently — the agent calls an endpoint, the wallet pays the Lightning invoice in the background, and the response comes back. No checkout, no human approval, no API key.

MPP is an open standard defined at mpp.dev. Any Lightning-compatible wallet or SDK can use it.

🔁 How it works

MPP uses an HTTP 402 challenge-response flow:

Step 1 — Request without credentials

Send a request to any endpoint without an x-api-key or Authorization header. The server responds with HTTP 402 Payment Required and a Lightning invoice challenge in the WWW-Authenticate header:

GET /v1/bitcoin/price HTTP/1.1
Host: api.secretkeylabs.io
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="<challenge-id>", realm="https://api.secretkeylabs.io", method="lightning", amount="1", ...
Cache-Control: no-store
Content-Type: application/problem+json

{
  "type": "https://paymentauth.org/problems/payment-required",
  "title": "Payment Required",
  "status": 402
}

The WWW-Authenticate header contains everything needed to pay the invoice, including the Lightning payment details and the amount in satoshis.

Step 2 — Pay the Lightning invoice

Extract the Lightning invoice from the 402 challenge and pay it using any Lightning-compatible wallet or SDK. Upon successful payment, you receive a preimage — the cryptographic proof of payment.

Step 3 — Retry with the payment credential

Retry the same request with the payment credential in the Authorization header:

The credential contains the preimage and is bound to the route it was issued for. On success, the server returns the API response along with a Payment-Receipt header:

💰 Pricing

All API endpoints are priced at 1 satoshi per request.

🔐 Authentication methods

Every endpoint supports two authentication methods. You can use either one:

Method
Header
Description

API Key

x-api-key: <your-key>

Traditional API key with rate limiting

MPP Payment

Authorization: Payment <credential>

Pay-per-request via Lightning, no rate limiting

If both headers are present, MPP is checked first. If MPP verification fails but an API key is present, the request falls back to API key authentication.

MPP-authenticated requests bypass rate limiting — you pay per request instead.

🛣️ Route binding

Payment credentials are bound to the specific endpoint they were issued for. A credential obtained for /v1/bitcoin/price cannot be reused on /v1/runes. Attempting to use a credential on a different route returns HTTP 403 Forbidden:

⚠️ Error responses

Status Code
Meaning

402 Payment Required

No payment credential provided. Response includes a Lightning invoice challenge in the WWW-Authenticate header.

403 Forbidden

Payment credential is valid but was issued for a different route.

500 Payment service unavailable

The payment service encountered an error. Retry the request.

🤖 Built for AI agents

MPP is designed for autonomous AI agent workflows. Agents can detect 402 challenges, pay Lightning invoices, and retry with credentials — enabling fully autonomous access to Bitcoin data and services.

Xverse Agent Wallet

The Xverse Agent Wallet is purpose-built for AI agents that need to interact with Bitcoin. An AI agent equipped with Xverse Agent Wallet can autonomously call any MPP-enabled endpoint and handle the Lightning payment without human intervention.

The agent wallet manages:

  • Lightning payments for MPP 402 challenges

  • Key management and credential handling

  • Automatic retry with payment credentials

This is the simplest way to give your AI agent full access to the Xverse API via MPP. From the agent's CLI:

See the Machine Payments page in the Agent Wallet docs for the full agent workflow.

Other integrations

You can also integrate MPP using any Lightning-compatible wallet or SDK. Libraries like mppx provide client SDKs that handle the 402 challenge-response flow automatically, and any Spark-compatible wallet can be used for Lightning payments.

📚 Example: full flow

A complete example using curl:

1. Request without credentials (get the 402 challenge):

2. Parse the WWW-Authenticate header, extract the Lightning invoice, and pay it using your wallet.

3. Retry with the payment credential:

The response includes a Payment-Receipt header confirming the payment was processed.

🟢 Available endpoints

Every endpoint in the Xverse API supports MPP Lightning payments — Bitcoin, Blocks, BRC-20, Inscriptions, Ordinals, Runes, Spark, Swaps, Subscriptions, Portfolio, and Bitcoin RPC (v1 and v2).

Browse the live catalog from the Agent Wallet CLI:

Or see the full module reference:

PreviousGet StartedNextMCP Server

Last updated