# ⚡ 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](https://docs.xverse.app/xverse-agentic-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](https://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:

```http
GET /v1/bitcoin/price HTTP/1.1
Host: api.secretkeylabs.io
```

```http
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:

```http
GET /v1/bitcoin/price HTTP/1.1
Host: api.secretkeylabs.io
Authorization: Payment <base64url-encoded-credential>
```

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:

```http
HTTP/1.1 200 OK
Payment-Receipt: <base64url-encoded-receipt>
Content-Type: application/json

{ ... }
```

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

```json
{
  "type": "https://paymentauth.org/problems/invalid-credential",
  "title": "Forbidden",
  "status": 403,
  "detail": "Credential was issued for /v1/bitcoin/price, not /v1/runes"
}
```

### ⚠️ 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**](https://docs.xverse.app/xverse-agentic-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:

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

# Execute the paid request
xverse-wallet pay request https://api.secretkeylabs.io/v1/bitcoin/price --yes --json

# Discover MPP-enabled endpoints
xverse-wallet pay api --json
```

See the [Machine Payments page in the Agent Wallet docs](/xverse-agentic-wallet/guides/agentic-lightning-commerce.md#step-4-call-paid-apis-automatically-mpp) for the full agent workflow.

#### Other integrations

You can also integrate MPP using any Lightning-compatible wallet or SDK. Libraries like [`mppx`](https://www.npmjs.com/package/mppx) provide client SDKs that handle the 402 challenge-response flow automatically, and any [Spark](https://www.spark.money/)-compatible wallet can be used for Lightning payments.

### 📚 Example: full flow

A complete example using `curl`:

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

```bash
curl -i https://api.secretkeylabs.io/v1/bitcoin/price
```

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

**3. Retry with the payment credential:**

```bash
curl -H "Authorization: Payment <base64url-credential>" \
  https://api.secretkeylabs.io/v1/bitcoin/price
```

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:

```bash
xverse-wallet pay api --json
```

Or see the full module reference:

* [Bitcoin API](/api/bitcoin.md)
* [Ordinals API](/api/ordinals.md)
* [Runes API](/api/runes.md)
* [BRC-20 API](/api/brc-20.md)
* [Spark API](/api/spark.md)
* [Portfolio API](/api/portfolio.md)
* [Swap Aggregator](/api/swaps.md)


---

# 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/api/mpp-lightning-payments.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.