# 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: ``` 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. ```json { "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 HTTP 200 OK Payment-Receipt: Content-Type: application/json ``` *** #### 5. **Record** Finally, the Facilitator posts the receipt to chain for traceability: ```json { "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 ```json { "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 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 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.justbeep.it/product-overview/agent-to-agent-payments-a402/protocol-specs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.