402LXP Protocol

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/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

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.

{
  "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.

{
  "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:

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:

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:

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.