Skip to content

x402 V2 Wire Format

Vauban Pay speaks x402 V2 Linux Foundation on the wire — three HTTP headers, CBOR canonical payloads, TLS mandatory. The internal X-Vauban-Payment header from v0.1/v0.2 is retired.

The three headers

PAYMENT-REQUIRED (merchant → client)

Merchant returns HTTP 402 with payment terms:

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <CBOR-encoded PaymentRequest>
Content-Type: application/x402+cbor

PaymentRequest contains:

  • currency — USDC / STRK / strkBTC (MVP day-1 currencies)
  • amount — integer in smallest unit (no float64 for money)
  • merchant_pseudonym — pseudonymous identifier (NOT raw merchant wallet)
  • service_id — opaque service reference
  • deadline — TemporalFrame expiry
  • revelation_mask_ref — pointer to required RevelationMask
  • accepts_humanity_gate — boolean ; if true, merchant requires PaymentIntent ∧ HumanityClaim
  • claim_schema_ref — CBOR schema reference for the PaymentIntent encoding

PAYMENT-SIGNATURE (client → merchant)

Client returns the signed PaymentIntent + STARK proof:

POST /api/resource HTTP/1.1
PAYMENT-SIGNATURE: <CBOR-encoded PaymentSignature>
Content-Type: application/x402+cbor

PaymentSignature contains:

  • payment_intent — CBOR-encoded VPSF Claim (sextuplet)
  • stark_proof — Stwo Circle STARK proof of intent validity
  • signature — ML-DSA-65 (Phase 2+) or Ed25519 (MVP) over the canonical bytes
  • humanity_claim — optional, if accepts_humanity_gate was set ; composed via ∧ (same-subject)
  • delegation_chain — optional, if agent payment via DelegationGrant → AgentPayment (Phase Agentic)

PAYMENT-RESPONSE (merchant → client)

Merchant returns HTTP 200 with the SettlementReceipt:

HTTP/1.1 200 OK
PAYMENT-RESPONSE: <CBOR-encoded SettlementReceipt>
Content-Type: application/x402+cbor

SettlementReceipt is itself a VPSF Claim — same sextuplet, different predicate ("Was paid X by Y at T"). It can be:

  • Verified offline by the payer
  • Restricted via ▷ for auditors
  • Aggregated with other receipts via ⊕
  • Revoked via ¬ if refunded

CBOR canonical, never JSON

Per risk R2 (metadata / PII leakage via x402 plaintext fields), Vauban Pay enforces:

  • CBOR canonical (RFC 8949) for all payload bodies — NOT JSON plaintext
  • TLS mandatory — non-negotiable, no HTTP fallback
  • RevelationMask discipline — only fields tagged Open appear on the wire ; Commit / ZK / Encrypted fields are mathematically hidden

A network observer looking at PAYMENT-REQUIRED over plain HTTP could infer transactional profile (service, frequency, tariff) without breaking any crypto. CBOR + TLS + RevelationMask close that side channel.

Content-Type

application/x402+cbor

All Vauban Pay headers carry this Content-Type. Implementations rejecting an unknown Content-Type are conformant to x402 V2.

Coinbase Facilitator concentration (risk R1)

Reality check (mai 2026): x402 production traffic is ~93% concentrated through Coinbase Facilitator. A Vauban Facilitator launched as "just another implementer" would face severe adoption friction.

Mitigation:

  • Own-facilitator — Vauban-operated Facilitator running x402 V2 conformant + STARK Receipts Extension
  • LF x402 TSC co-author — Vauban targets co-authorship of a "STARK Receipts Extension" sub-standard (per ADR-ECO-024), NOT simple implementer status
  • Standards-traction gate — if the STARK Receipts Extension sees no sustained progress, Vauban re-evaluates the engagement (including a standalone specification path)

Customizable PaymentSigner adapters

Per the chain-agnostic invariant (ADR-ECO-031), signing crypto is not baked into core. The PaymentSigner trait accepts pluggable backends:

Backend Status Crypto
VaubanAuthSigner MVP default Ed25519 → ML-DSA-65 path Phase 2+ post FIPS 206
StarknetSigner MVP Argent X / Braavos / direct Cairo signer
EvmSigner Phase 4+ secp256k1 ECDSA (legacy compat) ; PQ migration follows EVM ecosystem
SolanaSigner Phase 4+ Ed25519
BitcoinSigner Phase 3+ conditional BitVM-based, conditional on BitVM mainnet maturity

The signer is selected per-PaymentIntent. A single client can pay USDC on Starknet (via StarknetSigner) and USDC on EVM (via EvmSigner) Phase 4+ — using the same VPSF Claim grammar end-to-end.

Concrete request/response (MVP transparent flow)

A merchant API endpoint GET /api/brain.query priced at 0.10 USDC per call:

# Client → Merchant
GET /api/brain.query HTTP/1.1
Host: brain.api.vauban.tech

# Merchant → Client (no payment yet)
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: <CBOR>
  currency: USDC
  amount: 10_000_000_000 (1e10 atoms = 0.10 USDC)
  merchant_pseudonym: 0xdeadbeef...
  service_id: brain.query.v1
  deadline: 2026-12-31T23:59:59Z
  revelation_mask_ref: mask:vauban-pay/v0.3#audit-minimal
  accepts_humanity_gate: false
  claim_schema_ref: schema:vauban-pay/v0.3/PaymentIntent

# Client → Merchant (retry with signed intent)
POST /api/brain.query HTTP/1.1
Host: brain.api.vauban.tech
PAYMENT-SIGNATURE: <CBOR>
  payment_intent: <Claim sextuplet>
  stark_proof: <Stwo proof bytes>
  signature: <Ed25519 over canonical bytes>

# Merchant → Client (settled)
HTTP/1.1 200 OK
PAYMENT-RESPONSE: <CBOR>
  settlement_receipt: <Claim sextuplet>
Content-Type: application/json
{"result": [...]}  # the actual query response

Sprint-664 (planned 2026-08-03) ships full x402 V2 wire format conformance + Brain.api as first paying endpoint live testbed.

Cross-references

  • ADR-ECO-024 — x402 Foundation TSC engagement + STARK Receipts Extension
  • ADR-ECO-011 — Standards engagement immediate
  • R1 / R2 — Risk register entries (facilitator concentration ; metadata leakage)
  • Standards-traction gate — TSC engagement progress