···

Protocol explorer

Take a real 402 apart field by field, then follow the payment through to the receipt the device checks.

no link

Step 1

The device says what it costs

The 402 advertises what is for sale and the price. The nonce is single-use — a fresh one is minted per request and must be spent before expiresAt.

challenge unavailable

Start relay-proxy to fetch a live challenge.

Step 2

The buyer proves it paid

Sent with the replay request as base64url of canonical JSON. The nonce echoes the challenge; the signature is the settled Solana transaction.

X-PAYMENT

{
  "x402Version": 1,
  "scheme":      "exact",
  "network":     "solana-devnet",
  "payload": {
    "signature": "<base58 settled Solana tx>",
    "nonce":     "<hex — echoes the challenge nonce>"
  }
}

Step 3

The relay signs a receipt

The relay settles on-chain and signs a receipt with its Ed25519 key. The device holds one 32-byte public key and verifies offline in about 40ms — no TLS, no RPC, no heap spike. The signature covers the base64url text exactly as transmitted, so the device never has to re-serialise JSON to check it.

Receipt bodybase64url JSON

{
  "v":         1,
  "nonce":     "<hex — the challenge nonce>",
  "payTo":     "<vendor wallet, base58>",
  "amount":    "<micro-USDC, string>",
  "signature": "<base58 Solana tx>",
  "network":   "solana-devnet",
  "issuedAt":  <unix seconds>,
  "expiresAt": <unix seconds>
}

on the wire

X-Payment-Receipt: <body_b64url>.<sig_b64url>

Step 4

What the device checks

In this order. Any failure returns 402 with a specific error. Signature comes first, so nothing about live nonces leaks to anyone without a valid one.

Verification order

1
ed25519_verify(FACILITATOR_PUBKEY, receipt.body)
the relay signed it
2
nonce ∈ issued_nonces
this challenge was ours
3
nonce not already used
replay defence, without a database
4
receipt.expiresAt > now
still inside maxTimeoutSeconds
5
receipt.payTo == VENDOR_WALLET
paid to us, not redirected
6
receipt.amount ≥ price
full price, not discounted
7
receipt.network == expected
the right chain

types.ts

Every way it can fail

Each reason is defined once in packages/vendx-protocol/src/types.ts and mirrored in firmware-vendor/src/verifier.cpp.

missing_headermalformed_headerbad_signaturenonce_unknownnonce_replayednonce_expiredwrong_recipientinsufficient_amountwrong_networkreceipt_expired