# 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.

```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: <hash>
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