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, the response lists not only its own price but a short list of competitor offerings in the same category, each carrying a signed referral token. 2. Settlement. If the agent picks a competitor instead, that competitor verifies the referral token, processes payment, and pays the referring vendor a small commission via a shared settlement endpoint.

The point: 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 earn a commission). Cold-start is easy because reciprocity dominates: every vendor that lists peers gets listed back.

This is the v0.1 spec. The reference implementation is published as the npm package x402-mesh, and the open repo lives at github.com/StartupHub-AI/x402-mesh.

Wire format

A 402 response from an x402-mesh-aware vendor carries a mesh object alongside the standard x402 accepts[]. Vanilla x402 clients read only accepts[] and pay normally.

{
  "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, "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..."
    }
  ],
  "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 to 10 entries, ordered by the issuer's relevance

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 / EdDSA only, which keeps tokens compact and the verification path obvious.

header:  { "alg": "EdDSA", "typ": "JWT", "kid": "<vendor_id>" }
payload: {
  "iss": "<referrer_vendor_id>",
  "aud": "<target_vendor_id>",
  "iat": 1745920800,
  "exp": 1745921100,
  "jti": "uuid-v4",
  "cat": "email-validation",
  "cpct": 5,
  "act_chain": []
}

The target vendor MUST:

1. Look up the issuer's public key by kid from a 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 whose jti it has seen before (single use).

Settlement

When an agent presents a referral token and pays, the target POSTs the settlement endpoint named in the original 402:

POST /api/x402-mesh/settle
{
  "jti": "<from token>",
  "referrer_vendor_id": "<from token iss>",
  "target_vendor_id": "<self>",
  "category": "<from token cat>",
  "amount_cents": 4,
  "commission_pct": 5,
  "payment_proof": { "kind": "tx_hash", "ref": "0x..." }
}

The settlement service records the redemption under jti, then pays the referrer their commission via the highest-priority payout rail both parties support. Settlement can be self-hosted, federated, or third-party. The spec does not mandate one rail.

Atomic on-chain split

The default rail is a non-custodial splitter contract on Base. The agent pays the contract, which forwards the vendor share and the referrer commission in a single transaction (about 2 seconds, about a cent in fees, fully atomic). The contract holds no balance between calls, has no owner, and cannot be upgraded, so there is nothing to steal and no privileged role to trust. The MeshPaid event it emits carries the jti, so the settlement service reconciles the on-chain transfer against the ledger with one log read.

Fiat rails (Stripe Connect, manual invoice) exist as opt-in fallbacks for vendors who will not take USDC. The router prefers the on-chain split whenever both parties have a wallet configured.

Discovery

A vendor advertises participation with a manifest at /.well-known/x402-mesh.json:

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

A vendor is participating if and only if this file is publicly fetchable, parses as JSON, and the protocol plus vendor_id fields are valid.

Registry

Vendors register a public key plus endpoint metadata once:

POST /api/x402-mesh/registry
{
  "vendor_id": "your-slug",
  "name": "Your API",
  "category": "email-validation",
  "endpoint": "https://api.example.com/v1",
  "public_key": "<base64url ed25519>",
  "contact": "[email protected]",
  "wallet": "0xYourBaseAddress"
}

wallet is the zero-friction crypto-native path: a single Base address becomes a top-priority on-chain payout rail, so commissions settle in USDC with no Stripe account and no KYC. Vendors mixing fiat rails pass an explicit payout_rails array instead.

Anyone can read the registry:

GET /api/x402-mesh/registry?category=email-validation
GET /api/x402-mesh/registry/<vendor_id>

A vendor's identity is defined by its public key; the registry just maps vendor_id to that key plus endpoint metadata. If the registry goes down, vendors with cached keys keep working.

Identity: composed, not reinvented

x402-mesh is the commerce layer. It does not define how an agent proves who it is, and it is built to compose with whichever identity standard wins:

• Catena ACK-ID — agent identity via W3C DIDs and Verifiable Credentials.
• WorkOS auth.md — agentic registration for human-delegated agents.
• IETF WIMSE and OAuth 2.0 Token Exchange (RFC 8693) — the short-lived,

audience-scoped, single-hop token model, including an actor-chain claim that records full delegation lineage.

• Google A2A and Cisco AGNTCY — agent-to-agent interop and identity

infrastructure.

The optional act_chain claim mirrors that actor-chain pattern so a referred payment can carry verifiable delegation lineage: which agent paid, on whose behalf, referred by whom. Bring your own identity layer; the mesh settles the money.

Honest defaults

• Commission: 5% of the target's revenue from the referred call. Negotiable

bilaterally; encoded per token in cpct.

• Token TTL: 5 minutes. Long enough for an agent to think, short enough that

stale prices do not get redeemed.

• Categories: lowercase, kebab-case. Not gatekept. The de-facto vocabulary

emerges from usage.

• Quality fields: optional but recommended. The spec mandates no quality

framework; independent scorers can publish their own.

What this is NOT

• Not a marketplace. No central UI, no listings, no reviews. It is a wire

format and a settlement primitive.

• Not price-fixing. Vendors set their own prices; the protocol just makes them

visible at the moment of agent payment.

• Not a closed network. No gatekeeper, no paid certification, no verified-partner

badge. Anyone can run a registry; identity is your public key.

Reference implementation

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 },
  },
  alternatives: 'auto',
  handler: async (req) => {
    // runs only after payment is verified
    return Response.json({ valid: true });
  },
});

Drop the wrapper in, publish the well-known manifest, register your key, and you are a participating vendor.