x402-mesh

A light, open extension to x402 that turns every paywalled endpoint into a comparison shopping engine for AI agents — and gives the publisher a referral revenue stream when an agent picks a peer instead of them.

Full spec: docs/x402-mesh.md

Why

When an agent hits a paywall today, it sees one price and either pays or walks. With x402-mesh, the 402 response also includes a small menu of peer offerings in the same category, each carrying an ed25519-signed referral token. If the agent picks a peer, that vendor verifies the token, processes payment, and reports the redemption to a shared settlement endpoint — referrer earns a commission.

Net effect:

• Agents get transparent comparison data at the moment of payment.
• Vendors gain a kickback on traffic they would have lost.
• Cold-start is solved by reciprocity — every vendor that lists peers gets listed back.

No central marketplace. No new payment rail. Stripe Connect (or equivalent) handles settlement. Signing is just for attribution.

Install

npm install x402-mesh

Zero runtime dependencies. ed25519 signing/verification uses Node's built-in Web Crypto API. Works on Node 20+, Cloudflare Workers, Vercel Edge.

Quick start (Next.js)

import { withMesh } from 'x402-mesh/next';

export const POST = withMesh({
  category: 'email-validation',
  self: {
    vendor_id: 'startuphub',
    name: 'StartupHub Email Validator',
    endpoint: 'https://api.startuphub.ai/v1/validate',
    method: 'POST',
    price: { amount_cents: 3, currency: 'USD', unit: 'per_call' },
    quality: { accuracy: 0.95, p95_latency_ms: 250 },
  },
  alternatives: 'auto', // pulls peers from the registry at request time
  privateKey: process.env.X402_MESH_PRIVATE_KEY!,
  isAuthorized: (req) => Boolean(req.headers.get('authorization')),
  handler: async (req) => {
    const { email } = await req.json();
    return Response.json({ valid: true, email });
  },
});

When an unauthorized request hits the route, the wrapper returns a 402 with your own offer plus a peer menu. When a request carries X-X402-Mesh-Referral: <jwt>, the wrapper verifies the token, runs the handler, and fires a settlement report on success.

Generate a keypair

import { generateKeyPair } from 'x402-mesh/jwt';

const { publicKey, privateKey } = await generateKeyPair();
// store privateKey as X402_MESH_PRIVATE_KEY (env, secret)
// register publicKey at the registry of your choice

ed25519 only. 32-byte raw public key, base64url encoded.

Verify a referral token (without the wrapper)

import { verifyToken } from 'x402-mesh/jwt';

const result = await verifyToken(headerValue, {
  audience: 'my-vendor-id',
  resolvePublicKey: async (kid) => {
    const r = await fetch(`https://registry.example.com/${kid}`);
    if (!r.ok) return null;
    const { vendor } = await r.json();
    return vendor.public_key;
  },
});
if (!result.ok) {
  // result.error: 'expired' | 'bad-signature' | 'unknown-issuer' | ...
}

What's in the 402 response

{
  "protocol": "x402-mesh/0.1",
  "self": {
    "vendor_id": "startuphub",
    "name": "StartupHub Email Validator",
    "category": "email-validation",
    "endpoint": "https://api.startuphub.ai/v1/validate",
    "method": "POST",
    "price": { "amount_cents": 3, "currency": "USD", "unit": "per_call" },
    "quality": { "accuracy": 0.95 }
  },
  "alternatives": [
    {
      "vendor_id": "hunter",
      "name": "Hunter Email Verifier",
      "endpoint": "https://api.hunter.io/v2/email-verifier",
      "method": "GET",
      "price": { "amount_cents": 4, "currency": "USD", "unit": "per_call" },
      "quality": { "accuracy": 0.93 },
      "referral_token": "eyJhbGciOiJFZERTQSI..."
    }
  ],
  "settle": {
    "url": "https://www.startuphub.ai/api/x402-mesh/settle",
    "registry_url": "https://www.startuphub.ai/api/x402-mesh/registry"
  }
}

Standards positioning

x402-mesh is intentionally narrow: it adds two fields (alternatives, settle) to an existing x402 body, plus a JWT-based referral token.

It composes well with:

• x402 — the underlying 402 + payment flow
• AP2 / ACP — agent identity + payment-rail discovery
• MCP — tool/skill discovery
• Cloudflare Pay-Per-Crawl — edge-layer 402 returner
• Stripe Connect — settlement rails

It does not depend on any of them; you can adopt mesh without adopting the others, and vice versa.

Status

v0.1 — early. The wire format is stable enough to build against. Field names, JWT claims, and the well-known manifest are settled. The settlement clearing-house API at /api/x402-mesh/settle is one reference implementation; the spec doesn't mandate a single operator.

License

MIT.