---
title: 402LXP Protocol
description: >-
  402LXP is an HTTP-native payment protocol enabling agents to pay for API calls
  instantly using HTTP 402 status codes and USDX on LayerX.
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

## 402LXP protocol

402LXP is an HTTP-native payment protocol that lets agents pay for API calls using HTTP 402 status codes and USDX on LayerX. It is designed for machine-to-machine payments without checkout flows or human interaction.

## How it works

1. Agent makes an API call to a service.
2. The service responds with `HTTP 402 Payment Required` and a payment challenge.
3. Agent signs the payment challenge and resubmits with the payment proof attached.
4. The service verifies the payment, fulfills the request, and returns the response.

The entire exchange happens over standard HTTP - no browser, no redirect, no wallet popup.

## Payment challenge

When a service requires payment, it returns a 402 response with a structured challenge:

```http
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "amount": "0.001",
  "currency": "USDX",
  "pay_to": "did:ed25519:service.weather.v2",
  "nonce": "a3f9xK2m...",
  "expires_at": "2026-01-15T10:05:00Z",
  "description": "Weather forecast API call"
}
```

The agent reads the challenge, signs a transfer intent for the specified amount, and resubmits the original request with the payment proof in the `X-Payment` header.

## Completing the payment

```http
GET /v1/forecast HTTP/1.1
Host: weather.example.com
Authorization: Bearer <principal_token>
X-Payment: <base64url-encoded-signed-transfer-intent>
```

The service verifies the transfer intent against the LayerX API, confirms the amount matches, and processes the transfer. On success, it returns the requested resource with a `200 OK` and a `Payment-Receipt` header containing the LayerX receipt sequence number.

## Pricing models

### Per-call pricing

Each API call requires a fixed payment. The 402 challenge includes the exact amount. This is the simplest model and works well for stateless endpoints.

```json
{
  "amount": "0.001",
  "model": "per_call"
}
```

### Streaming pricing

For streaming endpoints (SSE, WebSocket), payment covers a time window or data volume. The initial 402 challenge opens the stream; subsequent charges are deducted automatically until the stream closes or the payment window expires.

```json
{
  "amount": "0.010",
  "model": "streaming",
  "window": "60s",
  "max_renewals": 10
}
```

The agent receives periodic `X-Payment-Window` headers indicating remaining time. When the window expires, the stream pauses until the agent sends a renewal payment.

## Evolution of x402

402LXP builds on the x402 protocol with several key differences:

| Feature | x402 | 402LXP |
|---------|------|--------|
| Settlement | On-chain | LayerX (instant, zero-fee) |
| Currency | Native token | USDX (dollar-denominated) |
| Latency | Block time | Instant |
| Target | General web | Autonomous agents |
| Auth | Wallet-based | DID-based |

The core HTTP 402 mechanism is preserved - 402LXP is a specialization, not a replacement.

## No checkout flow

The agent reads the 402 challenge, signs it programmatically, and retries within a single HTTP client lifecycle. No human in the loop.

## Implementing 402LXP

### Client-side

Use the `@paxeer/402lxp` middleware to automatically handle 402 challenges:

```typescript
import { withPayment } from "@paxeer/402lxp";

const response = await withPayment(
  () => fetch("https://weather.example.com/v1/forecast"),
  { wallet: myAgentWallet }
);
```

The middleware intercepts 402 responses, signs the payment, and retries the request transparently.

### Server-side

Use the `@paxeer/402lxp-server` package to add payment enforcement to any HTTP service:

```typescript
import { requirePayment } from "@paxeer/402lxp-server";

app.get("/v1/forecast",
  requirePayment({ amount: "0.001", payTo: myDid }),
  (req, res) => {
    res.json({ forecast: "..." });
  }
);
```

The middleware returns 402 challenges for unpaid requests and verifies payment proofs on retries.