Protocol Specs

🧩 Protocol Specs (a402)

The a402 protocol defines how two autonomous agents perform a verified payment handshake using HTTP 402 and on-chain settlement. It’s built to be machine-readable, non-custodial, and composable — a protocol any agent can speak.

---

🔄 Transaction Lifecycle

Every a402 payment moves through five atomic stages:

1. Request

The client (agent) attempts to access a protected resource or API endpoint. If payment is required, the merchant server responds with:

HTTP 402 Payment Required
Payment-Request: <encoded a402 payload>

The payload includes:

• amount — stablecoin amount (e.g., "0.50 USDC")

• recipient — merchant vault address

• chain — "sui", "base", or "solana"

• nonce — unique identifier for replay protection

• expiry — optional timeout (in seconds)

• callback — optional URL for post-payment confirmation

---

2. Pay

The agent’s wallet or runtime executes a transfer on the specified chain.

{
  "payer": "0xPAYER",
  "recipient": "0xMERCHANT",
  "amount": "0.50",
  "asset": "USDC",
  "chain": "sui",
  "nonce": "0xabc123"
}

This transaction is non-custodial — the agent signs it directly using its session key.

---

3. Verify

The Facilitator verifies the transaction against the payment request:

• Confirms transfer on-chain with exact amount, recipient, chain, and nonce

• Validates digital signature and confirms finality

• Generates a cryptographic receipt

If valid, the Facilitator emits:

x402.receipt(valid=true)

and the merchant unlocks the resource.

---

4. Unlock

Once verified, the merchant server delivers the protected output:

• File, API result, or model inference

• Optional metadata in HTTP 200 response

• a402 receipt hash embedded in response headers

HTTP 200 OK
Payment-Receipt: <hash>
Content-Type: application/json

---

5. Record

Finally, the Facilitator posts the receipt to chain for traceability:

{
  "receipt_id": "rcpt_01HXYF3",
  "payer": "0xPAYER",
  "merchant": "0xMERCHANT",
  "amount": "0.50",
  "chain": "sui",
  "tx_hash": "0x1234abcd...",
  "timestamp": "2025-10-26T00:31:00Z",
  "status": "paid"
}

Receipts are public, auditable, and can be re-verified by any third party or contract.

---

🔐 Cryptographic Receipts & Verification

Each a402 transaction generates a verifiable receipt signed by the Facilitator. It’s the trust anchor for machine-to-machine commerce.

Receipt Format

{
  "id": "rcpt_01HXYF3",
  "request_nonce": "0xabc123",
  "payer": "0xPAYER",
  "merchant": "0xMERCHANT",
  "amount": "0.50",
  "asset": "USDC",
  "chain": "sui",
  "tx_hash": "0x1234abcd...",
  "signature": "0xFACILITATOR_SIG",
  "issued_at": 1735278394
}

Verification Steps

1. Validate facilitator signature using known public key.

2. Confirm tx_hash exists and matches amount, payer, and merchant.

3. Check replay protection (request_nonce not reused).

4. Confirm status = paid and within valid time window.

Receipts are portable — they can be re-verified by any service, L2, or agent framework.

---

🧠 MCP / a402 Facilitator Interface

The Facilitator acts as the protocol’s bridge between web requests and blockchain settlement. It exposes a Machine Communication Protocol (MCP) interface for verifying and recording a402 payments.

Core Endpoints

Method	Endpoint	Description
POST	/a402/verify	Validate an agent’s payment receipt against the chain
POST	/a402/record	Post a verified receipt to on-chain storage
GET	/a402/status/:id	Check payment or receipt status
POST	/a402/sponsor	(Optional) Request gas sponsorship for zero-fee settlement

Facilitator Responsibilities

• Verify amount, recipient, and nonce match the merchant’s 402 payload

• Ensure chain finality before confirming

• Sign and issue receipt (0xFACILITATOR_SIG)

• Maintain receipt registry for external verification

• Optionally cover gas through the sponsorship pool

Facilitators are stateless by design — all trust is derived from on-chain proofs, not backend storage.

---

🧯 Error Codes and Responses

Code	Meaning	Description
402	Payment Required	Payment info missing or unpaid
409	Nonce Collision	Reused or invalid request nonce
410	Expired Payment	Request expired before settlement
422	Invalid Receipt	Receipt verification failed (mismatch or tamper)
424	Chain Finality Error	Transaction not yet confirmed or reverted
429	Rate Limit	Facilitator throttling or abuse detection
500	Internal Error	Unexpected facilitator issue

Example: Invalid Receipt

HTTP 422 Unprocessable Entity
x402-Error: INVALID_RECEIPT
x402-Details: Signature mismatch or tampered data

---

🧾 Summary

• a402 is the transport layer for agentic payments

• HTTP 402 signals payment intent

• Facilitator validates and signs receipts

• Merchants unlock resources on verified proof

• Receipts live on-chain, auditable, and portable

• Transaction Lifecycle

• Cryptographic Receipts & Verification

• MCP / a402 Facilitator Interface

• Error Codes and Responses