Agent Calls Protected API
`GET /v1/intelligence` arrives without an `Authorization: Bearer` ES256 license token or paid session receipt.
Turn any REST API or MCP endpoint into a self-monetizing paywall.
Credit cards fail below $1.00 and block autonomous AI agents that lack corporate cards. XPayr brings HTTP `402 Payment Required` to production: challenge unauthenticated callers with a non-custodial stablecoin session, settle 99.5% on Base, Solana, Arbitrum, TRON, or Circle Arc, and verify stateless ES256 JWT access tokens in sub-millisecond edge middleware.
Server Emits HTTP 402
Middleware creates or references an XPayr checkout/license SKU and returns `402 Payment Required` + `X-Payment-Required` metadata.
Agent Settles Stablecoin
Agent validates guardrails via `@xpayr/mcp-server` (`POST /api/mcp`), pays USDC/USDT (99.5% direct to merchant wallet), and receives an ES256 JWT.
Sub-ms JWKS Verification
Agent retries with `Authorization: Bearer <jwt>`. Edge middleware verifies ES256 against `/.well-known/jwks.json` offline and serves `200 OK`.
1. Standard HTTP `402 Payment Required` Challenge Payload
HTTP/1.1 402 Payment Required
Content-Type: application/json
WWW-Authenticate: XPayr402 realm="api.merchant.example", jwks="https://xpayr.com/.well-known/jwks.json"
X-Payment-Required: protocol="xpayr-x402-v1", amount="5.00", currency="USD", fee_bps="50"
{
"error": "payment_required",
"protocol": "xpayr-x402-v1",
"amount": "5.00",
"currency": "USD",
"accepted_rails": ["base:USDC", "solana:USDC", "arbitrum:USDT", "tron:USDT", "arc-testnet:USDC"],
"checkout_url": "https://xpayr.com/buy/pro-api-pass",
"mcp_endpoint": "https://xpayr.com/api/mcp",
"mcp_tool": "xpayr_create_payment_session",
"jwks_uri": "https://xpayr.com/.well-known/jwks.json"
}
2. Node.js / Edge Middleware (`@xpayr/extension-kit` v0.2.0)
import { createRemoteJWKSet, jwtVerify } from 'jose';
const XPAYR_JWKS = createRemoteJWKSet(
new URL('https://xpayr.com/.well-known/jwks.json')
);
export async function requireXpayr402(req, res, next) {
const token = (req.headers.authorization || '').replace(/^Bearer\s+/i, '');
if (token) {
try {
const { payload } = await jwtVerify(token, XPAYR_JWKS, { algorithms: ['ES256'] });
req.xpayrEntitlement = payload;
return next();
} catch (_) { /* expired or invalid token -> emit 402 below */ }
}
return res.status(402)
.set('WWW-Authenticate', 'XPayr402 jwks="https://xpayr.com/.well-known/jwks.json"')
.json({
error: 'payment_required',
protocol: 'xpayr-x402-v1',
checkout_url: 'https://xpayr.com/buy/api-credits-10k',
mcp_endpoint: 'https://xpayr.com/api/mcp'
});
}
Frequently Asked Questions — HTTP 402 & Agentic Paywalls
How does XPayr implement HTTP 402 Payment Required for APIs and AI agents?
When an unauthenticated client or AI agent calls your protected endpoint without a valid XPayr ES256 license token or paid session proof, your middleware returns HTTP 402 with an XPayr payment challenge JSON (and WWW-Authenticate / X-Payment-Required headers). Once paid on Base, Solana, Arbitrum, TRON, or Circle Arc, the client receives a cryptographically signed ES256 JWT verifiable offline via https://xpayr.com/.well-known/jwks.json.
Does verifying an HTTP 402 bearer token add latency to every API call?
Zero network round-trips are required per request. Your edge worker or backend caches XPayr's public P-256 key from /.well-known/jwks.json and verifies the ES256 JWT signature locally in under 0.2 milliseconds.
How can autonomous AI agents pay an HTTP 402 challenge automatically?
Agents connected to @xpayr/mcp-server (or POST https://xpayr.com/api/mcp) inspect the 402 challenge, check their Merchant Agent Guardrail policy (/tools/ai-agent-policy-simulator), execute or request approval for the stablecoin payment intent, and retry the request with the resulting Authorization: Bearer <es256_license_jwt> header.
Where is XPayr's machine-readable x402 discovery manifest hosted?
Inspect https://xpayr.com/.well-known/x402.json alongside https://xpayr.com/.well-known/agents.json and https://xpayr.com/.well-known/mcp.json.