x402-mesh

An open peer-pricelist and referral protocol for safe agentic commerce. Rail-agnostic: born on x402, it rides equally on Stripe MPP, Google AP2, and ACP.

Spec · npm package · Splitter contract · StartupHub.ai

When an AI agent hits a paywall, it sees one price and one vendor. x402-mesh turns that dead end into a market: at the moment of payment the agent is handed a signed menu of competing offers, and if it picks a competitor, that competitor pays the referrer a commission. Every vendor is both a seller and a broker. Reciprocity does the rest.

The menu and the commission are the protocol. The rail that moves the money is an adapter: an HTTP 402 on x402 or L402, a Shared Payment Token on Stripe MPP or ACP, a signed mandate on Google AP2, a card through a network agent program. x402-mesh captures the referral the same way whichever one the agent brought.

The name is historical. The protocol was first specified on x402 and still ships its reference adapter there, but it is not limited to it. See Rail bindings.

• Spec: SPEC.md
• Reference middleware: npm x402-mesh
• License: MIT

🚪 The problem

x402 gave agents a way to pay over HTTP: a server returns 402 Payment Required with payment instructions, the agent signs a USDC transfer, and retries. It works. But it is a closed door. The agent sees the vendor's price and nothing else. It cannot compare, and the vendor has no reason to point it anywhere better.

So agents overpay, vendors compete only on being first, and there is no shared layer where the market is visible at the moment that matters: the moment of payment.

This is not an x402 quirk. Every agent-payment rail that shipped in the last year presents the agent the same single-vendor door: Stripe MPP (per-call API billing), OpenAI and Stripe's ACP (checkout), Google's AP2 (the cross-rail mandate layer). The door is the problem, on every rail.

🧭 What x402-mesh adds

Two things, both backward compatible. A vanilla x402 client ignores them and pays exactly as before.

1. A peer menu. At the moment of payment the agent is handed, alongside the vendor's own price, a short list of competing offers in the same category (carried in the 402 body on x402, in the payment-required response on MPP, in a mandate on AP2). Each peer entry can include a price, quality stats, and a signed referral token.
2. Settlement. If the agent follows a referral and pays the peer, the peer verifies the token and pays the referrer a commission. The split uses whatever the rail already offers: an atomic on-chain transfer on x402, a Stripe Connect application_fee on MPP and ACP, mandate terms on AP2. Default 5%, negotiable per token.

sequenceDiagram
    participant Agent
    participant VendorA as Vendor A (referrer)
    participant VendorB as Vendor B (target)
    participant Settle as Settlement

    Agent->>VendorA: request
    VendorA-->>Agent: 402 + mesh menu<br/>(own price + peers + signed referral token)
    Note over Agent: agent compares, picks Vendor B
    Agent->>VendorB: pay, presenting A's referral token
    VendorB->>VendorB: verify token signature + audience + expiry
    VendorB-->>Agent: service delivered
    VendorB->>Settle: record redemption (jti)
    Settle->>VendorA: commission

The hidden payoff: every redemption is logged across every participating vendor. The mesh accumulates cross-vendor agent behavior that no single closed payment network can see, which is the foundation for an open agent-reputation primitive.

⚡ Quickstart

Drop the middleware into a Next.js route. You become a participating vendor in about twenty minutes.

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

export const POST = withMesh({
  category: 'email-validation',
  self: {
    vendor_id: 'your-slug',
    name: 'Your API',
    price: { amount_cents: 3, currency: 'USD', unit: 'per_call' },
    quality: { accuracy: 0.95, p95_latency_ms: 250 },
  },
  alternatives: 'auto', // fetch peers from the registry, or pin a static list
  handler: async (req) => {
    // runs only after payment is verified
    return Response.json({ ok: true });
  },
});

Then publish a discovery manifest at /.well-known/x402-mesh.json and register your public key once. That is the whole onboarding. See SPEC.md.

⛓️ Atomic settlement on Base (the x402 adapter)

This is the reference adapter. On x402, commissions settle in USDC on Base through a tiny non-custodial splitter contract (contracts/MeshSplitter.sol): the agent pays the contract, and it forwards the vendor share and the referrer commission in a single transaction. No escrow, no platform float, no trust.

flowchart LR
    Agent -- "pay(jti, vendor, referrer, amount, bps)" --> Splitter[MeshSplitter]
    Splitter -- "gross − commission" --> Vendor[Vendor wallet]
    Splitter -- "commission" --> Referrer[Referrer wallet]

A crypto-native vendor onboards with a single field: a Base wallet address. No Stripe account, no KYC. Vendors who settle in fiat skip the contract entirely and take the commission as a Stripe Connect application_fee on the same charge, which is what the MPP and ACP adapters do. The money layer is whichever one the agent brought; see Composes with for the full adapter list.

🪪 Identity: composed, not reinvented

x402-mesh is the commerce layer. It deliberately does not define how an agent proves who it is. That is a separate, fast-moving problem being solved by people with the right mandate, and the protocol is built to compose with whichever standard wins:

• Catena ACK-ID - agent identity via W3C DIDs and Verifiable Credentials.
• IETF WIMSE and OAuth 2.0 Token Exchange (RFC 8693) - the same short-lived, audience-scoped, single-hop token model Uber describes in its agent-identity architecture, including an actor-chain claim that records full delegation lineage.
• A2A - agent-to-agent interop.

The mesh token already uses the same primitives these standards rely on: an ed25519 JWT with issuer, audience, expiry, and a single-use id. A referral can optionally carry an actor-chain claim so a referred payment proves provenance (which agent, acting for whom). Bring your own identity layer; the mesh settles the money.

🧩 Composes with

x402-mesh is a thin layer, not a walled garden. It rides on top of existing rails and identity standards rather than replacing them.

Settlement rails (the menu is presented in each rail's native carrier; the commission splits in that same rail):

• Coinbase x402 - HTTP 402 + USDC, the reference binding. Menu rides the 402 body; split is the atomic on-chain MeshSplitter (see contracts/).
• Stripe MPP (Machine Payments Protocol, Stripe + Tempo, Mar 2026) - the metered per-call rail, stablecoin and fiat (cards, Klarna, Affirm) via Shared Payment Tokens. The best fit for pay-per-result APIs. Menu rides the payment-required / session response; the commission is a native Stripe Connect application_fee, so the split needs no custom escrow.
• ACP (Agentic Commerce Protocol, OpenAI + Stripe) - agent checkout, live in ChatGPT Instant Checkout. Menu rides the product feed; split via Connect application_fee.
• Google AP2 (Agent Payments Protocol, 60+ partners incl. PayPal, Mastercard, Amex, Adyen, Coinbase) - the rail-agnostic authorization layer over cards, bank and stablecoin. Referral terms ride inside the signed Payment Mandate; settlement happens on whatever method the mandate names (its stablecoin leg uses x402).
• L402 (Lightning) - the Bitcoin-native HTTP 402, for vendors settling over Lightning. Same menu-in-402 shape as x402.
• Card-network agent programs - Visa Trusted Agent Protocol, Mastercard Agent Pay: cryptographic agent identity plus tokenized card rails, settled under AP2 or ACP.
• USDC on Base and Cloudflare (x402 facilitation across chains + Web Bot Auth at the edge) - the default on-chain payout and agent verification.

The protocol core (the peer menu, the signed referral token, redemption logging, reputation) is identical across all of these. A rail is just two functions: present the menu at the decision point, and split the commission at settlement. Adding a rail is writing that adapter, not changing the protocol. The per-rail wire details are in SPEC.md §8.

Identity (bring your own; the mesh settles the money):

• Catena ACK-ID - agent identity via W3C DIDs and Verifiable Credentials.
• WorkOS auth.md - agentic registration for human-delegated agents.
• IETF WIMSE / OAuth 2.0 Token Exchange (RFC 8693) - the actor-chain direction.
• Google A2A, Cisco AGNTCY - agent-to-agent interop and identity infrastructure.

A fuller map of the agentic-commerce ecosystem lives at startuphub.ai.

🚫 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 only makes them visible at the moment of agent payment.
• Not a closed network. There is no gatekeeper, no paid certification, no "verified partner" badge. Anyone can run a registry; identity is your public key.

🗂️ Repository layout

README.md              this file
SPEC.md                the v0.1 wire spec + rail bindings (§8)
contracts/             MeshSplitter.sol + deploy notes
  MeshSplitter.sol
reference/             JWT helpers and shared types

The reference middleware, JWT helpers, and payout router are published as the npm package x402-mesh.

📄 License

MIT. Copy it, fork it, run your own registry. The protocol wins when it spreads.