x402-mesh — peer pricelist + referral protocol

x402-mesh is a light extension of x402 that adds two things on top of "402 Payment Required":

1. A peer menu. When a vendor returns 402, they include not only their own price, but a short list of competitor offerings for the same category, each carrying a signed referral token. 2. Settlement. If the agent picks a competitor instead, the competitor verifies the referral token, processes payment normally, and pays the referring vendor a small commission via a shared settlement endpoint.

The point of the protocol: agents need transparent comparison data at the moment of payment. Vendors gain by being either the seller (agent picked me) or the broker (agent picked a peer, I get a kickback). Cold-start is easy because reciprocity dominates — every vendor that lists peers gets listed back.

This document is the v0.1 spec. Reference implementation lives at lib/x402-mesh/ in this repo and is published as the npm package x402-mesh.

Wire format

A 402 response from an x402-mesh-aware vendor looks like:

{
"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" },     "auth": "x402_token | bearer | api_key",     "quality": { "accuracy": 0.95, "p95_latency_ms": 250 }   },   "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, "p95_latency_ms": 320 },       "referral_token": "eyJhbGciOiJFZERTQSIs..."     },     {       "vendor_id": "snov",       "name": "Snov.io Email Verifier",       "endpoint": "https://api.snov.io/v1/get-emails-verification-status",       "method": "POST",       "price": { "amount_cents": 2, "currency": "USD", "unit": "per_call" },       "quality": { "accuracy": 0.91, "p95_latency_ms": 420 },       "referral_token": "eyJhbGciOiJFZERTQSIs..."     }   ],   "settle": {     "url": "https://api.startuphub.ai/api/x402-mesh/settle",     "registry_url": "https://api.startuphub.ai/api/x402-mesh/registry"   }
}

Field requirements

protocol — exact string x402-mesh/0.1. Required.
self.vendor_id — short slug, must match the issuer's registry entry.
self.price.amount_cents — integer cents. unit is one of per_call,

per_token_in, per_token_out, per_kb, per_seat_month, flat.

alternatives[] — 0–10 entries, sorted by relevance (the issuer's

judgement). referral_token is required for any entry the issuer wants attribution for; entries without a token are pure information.

settle.url — POST endpoint where the target vendor reports redemption.

Referral token

A JWT signed by the referring vendor's private key. ed25519 only.

header:  { "alg": "EdDSA", "typ": "JWT", "kid": "<vendor_id>" }
payload: {   "iss": "<referrer_vendor_id>",   // who's referring   "aud": "<target_vendor_id>",     // who can redeem   "iat": 1745920800,   "exp": 1745921100,                // 5 min default   "jti": "uuid-v4",                 // single-use   "cat": "email-validation",   "cpct": 5                         // commission % the issuer is asking for
}

The target vendor MUST:

1. Look up the issuer's public key by kid from any compliant registry. 2. Verify the signature. 3. Verify aud matches its own vendor_id (or is *). 4. Verify exp is in the future. 5. Reject any token with a jti it has seen before (in-memory cache or DB).

Settlement

When an agent presents a referral token and pays, the target vendor POSTs to the settlement URL named in the original 402 response:

POST /api/x402-mesh/settle
Content-Type: application/json
{   "jti": "<from token>",   "referrer_vendor_id": "<from token iss>",   "target_vendor_id": "<self>",   "category": "<from token cat>",   "amount_cents": 4,   "commission_pct": 5,   "agent_user_agent": "openai-gpt-agent/1.0"
}

The settlement service:

Records the redemption under the jti.
Marks status='pending' until both vendors have settled with their

payment provider for the period (default monthly batch).

Pays the referrer their commission from the target's revenue.

Settlement service can be self-hosted, federated, or operated by a third party. The spec doesn't mandate one; it just defines the wire format. This repo ships a Stripe-Connect-backed reference settlement service at /api/x402-mesh/settle.

Discovery — `/.well-known/x402-mesh.json`

A vendor advertises participation by publishing a small manifest at /.well-known/x402-mesh.json on their primary domain. Tooling (scanners, crawlers, registries, agent runtimes) detects participation by GET-ing this URL. Format:

{
"protocol": "x402-mesh/0.1",   "vendor_id": "startuphub",   "categories": ["email-validation", "agent-readiness-scan"],   "registry_url": "https://www.startuphub.ai/api/x402-mesh/registry"
}

A vendor is considered participating if and only if this file is publicly fetchable, parses as JSON, and the protocol + vendor_id fields are valid. Scanners SHOULD verify the vendor_id resolves on the registry named in registry_url.

Registry

Vendors register a public key + endpoint metadata once:

POST /api/x402-mesh/registry
{   "vendor_id": "startuphub",   "name": "StartupHub Email Validator",   "category": "email-validation",   "endpoint": "https://api.startuphub.ai/v1/validate",   "public_key": "<base64url ed25519>",   "contact": "[email protected]"
}

Anyone can read:

GET /api/x402-mesh/registry?category=email-validation
GET /api/x402-mesh/registry/<vendor_id>     // single vendor + pubkey

The registry is intentionally trivial. A vendor's identity is defined by their pubkey; the registry just maps vendor_id → pubkey + endpoint. If the registry goes down, vendors with cached pubkeys keep working.

Honest defaults

Commission percentage: 5% of the target vendor's revenue from the

referred call. Negotiable bilaterally; encoded per-token in cpct.

Token TTL: 5 minutes. Short enough that stale prices don't get

redeemed; long enough that an agent can think.

Categories: lowercase, kebab-case, ISO-style. e.g. email-validation,

email-finder, agent-readiness-scan, mcp-discovery, vector-search, web-scraping. Categories aren't gatekept — anyone can declare one in their registry entry. The de-facto vocabulary emerges from usage.

Quality fields are optional but recommended. The spec doesn't mandate

a quality framework — vendors decide what to publish. Independent scorers (e.g. agent-readiness benchmarks) can publish their own quality endpoint that other vendors fetch and include.

What this is NOT

Not a marketplace. There's no central UI, no listings page, no review

system. The protocol is a wire format and a settlement primitive.

Not a price-fixing arrangement. Vendors set their own prices. The

protocol just makes them visible at the point of agent payment.

Not crypto. Stripe Connect (or equivalent fiat rails) handles

settlement. The signing is just for attribution, not value transfer.

Reference implementation

// app/api/v1/validate/route.ts
import { withMesh } from 'x402-mesh/next';
export const POST = withMesh({   category: 'email-validation',   self: {     vendor_id: 'startuphub',     name: 'StartupHub Email Validator',     price: { amount_cents: 3, currency: 'USD', unit: 'per_call' },     quality: { accuracy: 0.95, p95_latency_ms: 250 },   },   // Auto-fetches alternatives from the registry. Override with a function   // for custom selection logic, or with a static list to pin specific peers.   alternatives: 'auto',
// The actual handler runs only when payment has been verified   // (x402 token in the Authorization header, or an API key on the   // vendor's existing scheme).   handler: async (req) => {     const { email } = await req.json();     // ... normal validator logic     return Response.json({ valid: true });   },
});

That's it. Drop the wrapper in, you're a participating vendor.