X402-Mesh – Open peer-pricelist and referral protocol

Notifications You must be signed in to change notification settings

Fork 0

Star 4

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

3 Commits

3 Commits

contracts

contracts

reference

reference

LICENSE

LICENSE

README.md

README.md

SPEC.md

SPEC.md

Repository files navigation

An open peer-pricelist and referral protocol for safe agentic commerce, layered on top of x402.

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

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.

What x402-mesh adds

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

A peer menu. A 402 response carries, alongside the vendor's own price, a short list of competing offers in the same category. Each peer entry can include a price, quality stats, and a signed referral token.

Settlement. If the agent follows a referral and pays the peer, the peer verifies the token and pays the referrer a commission through a shared settlement endpoint. 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 (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

Loading

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

Commissions settle in USDC on Base. The reference path is 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]

Loading

A crypto-native vendor onboards with a single field: a Base wallet address. No Stripe account, no KYC. Fiat rails (Stripe Connect, manual invoice) exist as opt-in fallbacks for vendors who will not take USDC.

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 payout router is rail-agnostic):

Coinbase x402 — the base payment standard this extends.

USDC on Base — the default atomic on-chain split (see contracts/).

Cloudflare — x402 facilitation across multiple chains, plus Web Bot Auth for edge agent verification.

Stripe / ACP, PayPal, Visa — fiat and card rails for vendors who settle off-chain.

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 contracts/ MeshSplitter.sol + deploy notes MeshSplitter.sol

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.

About

Open peer-pricelist + referral protocol for safe agentic commerce, layered on Coinbase x402. Signed referral tokens, atomic USDC commission settlement on Base, composes with ACK-ID / WIMSE for identity.

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Custom properties

Stars

4 stars

Watchers

1 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

TypeScript 71.2%

Solidity 28.8%