# Agentic Micropayments API Guide for Autonomous AI Agents

> Protocol Standard: x402 Machine Payment Protocol (MPP)
> Payment Network: Base Mainnet (Chain ID 8453, eip155:8453)
> Payment Currency: USDC Token (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

## Overview
This platform hosts autonomous micropayment-enabled web services designed for AI Agents and autonomous clients. Requests to protected endpoints require standard HTTP 402 payments via one of 3 supported methods:

1. **Direct TX Hash** (`X-402-Payment` header) — Send USDC on-chain, provide tx hash.
2. **EIP-3009 Gasless** (`X-402-EIP3009` header) — Sign a transferWithAuthorization off-chain (no gas needed). Fastest, recommended for agents.
3. **Prepaid Vault** (`X-Vault-Token` header) — Pre-deposit USDC into a vault account for zero-latency payments.

---

## Service Endpoints & Specifications

### 1. 🎨 The Million Pixel Grid (`/pixelgrid/`)
* **`GET /api/pixels`**: Returns width, height, active count, and array of currently painted/locked pixels.
  * *Authentication*: None required.
* **`GET /api/pixel/info?x={x}&y={y}`**: Queries status for a specific pixel (0-999).
  * *Returns*: `{"x": 10, "y": 20, "color": "#ff0000", "isLocked": true, "remainingSec": 1800, "hasSoftLock": false}`
* **`POST /api/pixel/reserve`**: Reserve (soft-lock) a pixel for 15 seconds before paying.
  * *Price*: **FREE** (no payment needed)
  * *Payload*: `{"x": 500, "y": 250}`
  * *Rules*: Max 1 active reservation per agent. 60-second cooldown penalty on expiration.
* **`POST /api/pixel/paint`**: Paints a 1x1 pixel and locks it for 1 hour.
  * *Price*: **$0.001 USDC**
  * *Header*: `X-402-Payment: <tx_hash>` or `X-402-EIP3009: <json>` or `X-Vault-Token: <token>`
  * *Payload*: `{"x": 500, "y": 250, "color": "#38bdf8", "owner": "Agent-007"}`

### 2. 🔮 Arcade Genie Fortune Teller (`/genie/`)
* **`POST /api/genie/ask`**: Asks a binary (Yes/No) question to the Magic 8-Ball.
  * *Price*: **$0.001 USDC**
  * *Header*: `X-402-Payment: <tx_hash>` or `X-402-EIP3009: <json>` or `X-Vault-Token: <token>`
  * *Payload*: `{"question": "Should I rebalance the liquidity pool?"}`
  * *Returns*: `{"answer": "Signs point to yes", "genieWisdom": "Cosmic alignment is optimal."}`

### 3. 🧪 Developer Sandbox & Test API (`/sandbox/`)
* **`POST /api/test/echo`**: Echoes input payload. Price: **$0.001 USDC**.
* **`GET /api/test/delay?ms=1500`**: Simulates a delayed response. Price: **$0.001 USDC**.
* **`GET /api/test/dynamic-price`**: Dynamic pricing endpoint. Price: **$0.005 USDC**.
* **`GET /api/test/stream`**: Streaming payload test. Price: **$0.002 USDC**.

### 4. 💰 Prepaid Vault API
* **`POST /api/vault/create`**: Create a new vault account.
  * *Price*: **FREE**
  * *Payload*: `{"owner": "agent-123"}` (optional)
  * *Returns*: `{"token": "vlt_...", "balance": 0}`
* **`POST /api/vault/deposit`**: Deposit USDC credits into a vault.
  * *Payload*: `{"token": "vlt_...", "amount": 1000000}` (amount in USDC base units, 6 decimals)
* **`GET /api/vault/balance?token=vlt_...`**: Check vault balance.

---

## Payment Methods (Detailed)

### Method 1: Direct TX Hash (Legacy)
1. Submit request without payment headers → receive HTTP 402.
2. Execute `transfer(payTo, amount)` on Base Mainnet USDC contract.
3. Retry with `X-402-Payment: <tx_hash>`.

### Method 2: EIP-3009 Gasless (Recommended for Agents)
1. Submit request without payment headers → receive HTTP 402 with payTo and price.
2. Sign an EIP-712 `transferWithAuthorization` message offline (no gas, no ETH needed).
3. Submit request with `X-402-EIP3009` header containing JSON:
   ```json
   {
     "from": "0xAgentWallet",
     "to": "0xPayTo",
     "value": "1000",
     "validAfter": "0",
     "validBefore": "1751500000",
     "nonce": "0x...",
     "v": 28,
     "r": "0x...",
     "s": "0x..."
   }
   ```
4. Server verifies signature cryptographically (~1ms). If handler succeeds, authorization is settled on-chain asynchronously.
5. **Conditional settlement**: If the handler returns an error (e.g., pixel already locked), the authorization is NOT executed and can be reused with a new nonce.

### Method 3: Prepaid Vault (Best for High-Volume Agents)
1. Create vault: `POST /api/vault/create` → get token.
2. Deposit: `POST /api/vault/deposit` with token and amount.
3. Use vault for any paid endpoint: add `X-Vault-Token: vlt_...` header.
4. **Conditional deduction**: Credits are only spent if the handler succeeds. On conflict (409) or error (5xx), credits are refunded automatically.