aptos-x402 1.0.0 → 1.0.2

package/README.md

@@ -1,228 +1,261 @@
-# aptos-x402
+# Aptos x402
 
-> x402 Payment Protocol SDK for Aptos blockchain
+<div align="center">
 
-HTTP 402 Payment Required for machine-to-machine micropayments on Aptos.
+**HTTP 402 Payment Protocol SDK for Aptos Blockchain**
 
 [![npm version](https://img.shields.io/npm/v/aptos-x402.svg)](https://www.npmjs.com/package/aptos-x402)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)
+[![Next.js](https://img.shields.io/badge/Next.js-15+-black.svg)](https://nextjs.org/)
 
-## 🎮 Try the Interactive Demo
+[Documentation](https://aptos-x402.vercel.app/docs) • [API Reference](#api-reference) • [Demo](https://aptos-x402.vercel.app)
 
-See x402 in action with our interactive CLI demo:
+</div>
 
-```bash
-# Clone the repo
-git clone https://github.com/adipundir/aptos-x402
-cd aptos-x402
+---
 
-# Install dependencies
-npm install
+## Overview
 
-# Start the server
-npm run dev
+**Aptos x402** is a TypeScript SDK implementing the [x402 payment protocol](https://github.com/coinbase/x402) for the Aptos blockchain. Enable your APIs to require cryptocurrency payments before serving responses using the standardized HTTP 402 status code.
 
-# In another terminal, run the demo
-npx tsx scripts/test-x402-axios.ts
-```
+Built for **machine-to-machine micropayments**, this SDK provides zero-friction payment integration for Next.js applications with automatic payment handling, cryptographic verification, and **sub-second settlement times** (optimized from 2-3s to 200-500ms).
 
-The demo will:
-1. Ask for your Aptos private key (testnet)
-2. Check your balance
-3. Make a request to a protected API endpoint
-4. **Automatically handle the payment** using x402-axios
-5. Show you the response and transaction details
+> ⚡ **Performance:** Latest optimizations deliver **5-10x faster** payments with verification caching, async confirmation, and smart deduplication. See [PERFORMANCE_OPTIMIZATIONS.md](./PERFORMANCE_OPTIMIZATIONS.md) for details.
+
+<!-- ## Key Features
+
+-  **Sub-3s Settlement** - Aptos blockchain finality in 1-3 seconds
+-  **Cryptographically Secure** - Client-side signing, no key exposure
+-  **Axios-Compatible Client** - Drop-in replacement with automatic payment handling
+- 🛡️ **Zero-Config Middleware** - Protect Next.js routes without touching API code
+- 🤖 **AI Agent Ready** - Perfect for autonomous machine-to-machine payments
+- 📦 **TypeScript Native** - Fully typed with comprehensive IntelliSense
+- 🌐 **Production Ready** - Battle-tested with comprehensive error handling
+- 💰 **Free Public Facilitator** - Start building immediately, no infrastructure required -->
+
+## Use Cases
+
+| Use Case | Description |
+|----------|-------------|
+| **Pay-per-API-Call** | Monetize APIs without subscriptions or rate limits |
+| **AI Agent Payments** | Enable autonomous agents to pay for resources |
+| **Metered Services** | Charge exactly for what's consumed in real-time |
+| **Micropayments** | Enable sub-cent transactions economically |
+| **Decentralized Access** | Replace API keys with cryptographic payments |
+
+## Quick Start
+
+### Installation
 
-**Don't have testnet APT?** Generate an account and fund it:
 ```bash
-npx tsx scripts/generate-account.ts
-npx tsx scripts/fund-account.ts <your-address>
+npm install aptos-x402
 ```
 
-## Quick Start (5 Minutes)
+### Requirements
 
-Add cryptocurrency payments to your Next.js API in just 3 steps:
+- **Next.js:** 15.0.0 or higher
+- **Node.js:** 20.0.0 or higher
+- **TypeScript:** 5.x (recommended)
+- **Aptos SDK:** 1.26.0 or higher (included as peer dependency)
 
-### Step 1: Install the Package
+---
+
+## 🤖 AI-Powered Setup (Cursor IDE)
+
+Get started in seconds with AI-assisted integration:
 
 ```bash
-npm install aptos-x402
+mkdir -p .cursor/rules
+curl -o .cursor/rules/aptos-x402.mdc https://raw.githubusercontent.com/adipundir/aptos-x402/main/integration/aptos-x402.mdc
 ```
 
-## 🛒 For Buyers (Consuming Paid APIs)
+**Restart Cursor IDE**, then ask:
+> "Set up Aptos x402 in my Next.js app with payment middleware and a test client component"
+
+The MDC context file provides Cursor with complete API documentation, types, and examples for accurate code generation.
+
+**Learn more:** [Cursor Integration Guide](./docs/guides/cursor-integration.md)
+
+---
+
+## 🛒 Client Integration (Consuming Paid APIs)
 
-Access paid APIs with automatic payment handling using our **axios-compatible** interface:
+Access x402-protected APIs with zero configuration. The `x402axios` client automatically detects payment requirements, builds transactions, and handles the entire payment flow.
+
+### Basic Usage
 
 ```typescript
 import { x402axios } from 'aptos-x402';
 
-// Works exactly like axios - payment handled automatically!
 const response = await x402axios.get('https://api.example.com/premium/data', {
-  privateKey: '0x...'  // Your Aptos private key
+  privateKey: process.env.APTOS_PRIVATE_KEY
 });
 
-console.log(response.data);              // API response data
-console.log(response.paymentInfo);       // { transactionHash, amount, ... }
-```
+// Access response data
+console.log(response.data);
 
-### Full Axios Compatibility
+// Verify payment details
+console.log('Transaction:', response.paymentInfo?.transactionHash);
+console.log('Amount:', response.paymentInfo?.amount);
+```
 
-x402axios supports all standard axios methods and features:
+### Supported HTTP Methods
 
 ```typescript
-// GET request
-const response = await x402axios.get('https://api.example.com/data', {
-  privateKey: '0x...',
-  timeout: 5000,
-  headers: { 'Authorization': 'Bearer token' }
+// GET with parameters
+await x402axios.get('/data', {
+  privateKey: process.env.APTOS_PRIVATE_KEY,
+  params: { filter: 'active' }
 });
 
-// POST request
-const response = await x402axios.post('https://api.example.com/analyze', 
-  { text: 'Hello world' },
-  { 
-    privateKey: '0x...',
-    headers: { 'Content-Type': 'application/json' }
-  }
+// POST with body
+await x402axios.post('/analyze', 
+  { text: 'Content to analyze' },
+  { privateKey: process.env.APTOS_PRIVATE_KEY }
 );
 
-// Create instance with defaults
+// PUT, PATCH, DELETE
+await x402axios.put('/resource/123', data, { privateKey: '0x...' });
+await x402axios.patch('/resource/123', updates, { privateKey: '0x...' });
+await x402axios.delete('/resource/123', { privateKey: '0x...' });
+```
+
+### Instance Configuration
+
+```typescript
+// Create configured instance
 const api = x402axios.create({
   baseURL: 'https://api.example.com',
   timeout: 10000,
-  privateKey: '0x...'  // Default for all requests
+  privateKey: process.env.APTOS_PRIVATE_KEY,
+  headers: { 'X-Client-Version': '1.0.0' }
 });
 
-const response = await api.get('/premium/data');
+// Use instance for all requests
+const weather = await api.get('/premium/weather');
+const stocks = await api.get('/premium/stocks');
 ```
 
-**What happens automatically:**
-1. Makes initial request to the protected API
-2. Detects 402 Payment Required response
-3. Extracts payment requirements (amount, recipient, network)
-4. Builds and signs Aptos transaction
-5. Retries request with payment
-6. Returns data + payment info
+### How It Works
+
+The client automatically handles the complete payment flow:
+
+1. **Initial Request** - Sends HTTP request to protected endpoint
+2. **402 Detection** - Identifies payment requirement from response
+3. **Transaction Building** - Constructs Aptos transfer transaction
+4. **Client Signing** - Signs transaction locally (keys never leave client)
+5. **Payment Retry** - Resubmits request with X-PAYMENT header
+6. **Settlement** - Server verifies and submits to blockchain
+7. **Response** - Receives data after confirmed payment
+
+---
 
-## 🏪 For Sellers (Creating Paid APIs)
+## 🏪 Server Integration (Monetizing Your APIs)
 
-### Step 2: Create `middleware.ts` in Your Project Root
+Protect Next.js API routes with x402 middleware - zero payment code required in your route handlers.
+
+### Step 1: Configure Environment
+
+Create `.env.local` in your project root:
+
+```env
+PAYMENT_RECIPIENT_ADDRESS=0xYOUR_APTOS_WALLET_ADDRESS
+FACILITATOR_URL=https://aptos-x402.vercel.app/api/facilitator
+```
 
-Create a file called `middleware.ts` in the root of your Next.js project (same level as `app/` or `pages/`):
+> **Getting a Wallet Address:**  
+> Install [Petra Wallet](https://petra.app/) or generate programmatically with `@aptos-labs/ts-sdk`
+
+### Step 2: Create Middleware
+
+Create `middleware.ts` in your project root (same level as `app/` directory):
 
 ```typescript
-// middleware.ts
 import { paymentMiddleware } from 'aptos-x402';
 
 export const middleware = paymentMiddleware(
   process.env.PAYMENT_RECIPIENT_ADDRESS!,
   {
-    // Configure which routes require payment
     '/api/premium/weather': {
-      price: '1000000',  // 0.01 APT (in Octas)
+      price: '1000000',  // 0.01 APT (1 APT = 100,000,000 Octas)
       network: 'testnet',
-      config: { description: 'Premium weather data' },
+      config: {
+        description: 'Premium weather data access',
+        mimeType: 'application/json'
+      }
     },
+    '/api/premium/stocks': {
+      price: '5000000',  // 0.05 APT
+      network: 'testnet',
+      config: { description: 'Real-time stock data' }
+    }
   },
   { 
-    // Use public facilitator (perfect for testing)
-    url: 'https://aptos-x402.vercel.app/api/facilitator'
+    url: process.env.FACILITATOR_URL!
   }
 );
 
 export const config = {
-  matcher: ['/api/premium/:path*'],  // Apply to all /api/premium/* routes
+  matcher: ['/api/premium/:path*']
 };
 ```
 
-### Step 3: Set Environment Variable
-
-Create `.env.local` in your project root:
-
-```env
-# Your Aptos wallet address (where payments go)
-PAYMENT_RECIPIENT_ADDRESS=0xYOUR_WALLET_ADDRESS_HERE
-```
-
-**How to get your wallet address:**
-1. Install [Petra Wallet](https://petra.app/) or [Martian Wallet](https://martianwallet.xyz/)
-2. Create a new wallet
-3. Copy your address (starts with `0x`)
-4. Paste it in `.env.local`
-
-**That's it!** Your API routes under `/api/premium/*` now require payment.
+### Step 3: Create Protected Routes
 
-### Your API Routes Stay Clean
-
-**Important:** You don't need to change anything in your API routes! The middleware handles everything.
+Your API routes require **zero payment logic** - the middleware handles everything:
 
 ```typescript
 // app/api/premium/weather/route.ts
 import { NextResponse } from 'next/server';
 
-export async function GET() {
-  // This code only runs AFTER payment is verified and settled!
-  // No payment logic needed here.
+export const dynamic = 'force-dynamic';
+
+export async function GET(request: Request) {
+  // Execution only reaches here AFTER successful payment settlement
   
   return NextResponse.json({
     location: 'San Francisco',
     temperature: 72,
     condition: 'Sunny',
+    forecast: '7-day detailed forecast data...'
   });
 }
 ```
 
-The middleware automatically:
-- Returns 402 for requests without payment
-- Verifies payment signatures
-- Settles payments on Aptos blockchain
-- Only allows API execution after successful payment
-- Adds payment receipt headers to responses
+### Middleware Behavior
 
-### Next.js Requirements
+| Scenario | Response |
+|----------|----------|
+| No payment header | **402 Payment Required** with payment instructions |
+| Invalid payment | **403 Forbidden** with error details |
+| Valid payment | **Verifies → Settles → Executes route → 200 OK** |
 
-- **Next.js 15+** with App Router
-- TypeScript (recommended)
-- Node.js 20+
+### Price Configuration
 
-### Complete Project Structure
+Aptos uses **Octas** as the smallest unit (like satoshis or wei):
 
-After setup, your Next.js project should look like this:
+```typescript
+1 APT = 100,000,000 Octas
 
-```
-my-nextjs-app/
-├── middleware.ts              ← Payment middleware (created in Step 2)
-├── .env.local                 ← Environment variables (created in Step 3)
-├── app/
-│   └── api/
-│       └── premium/           ← Protected routes (payment required)
-│           └── weather/
-│               └── route.ts   ← Your API route (no payment code needed!)
-├── package.json
-└── next.config.js
+Common prices:
+  0.001 APT = 100,000 Octas
+  0.01 APT  = 1,000,000 Octas
+  0.1 APT   = 10,000,000 Octas
+  1 APT     = 100,000,000 Octas
 ```
 
-**Key Points:**
-- `middleware.ts` must be in the project root (not inside `app/`)
-- Applies to all routes matching `/api/premium/*` (configurable)
-- Your API routes need **zero** payment code
-- Works automatically on every request
+### Testing Your Integration
 
-### Testing Your Setup
+Start your development server and verify payment protection:
 
-After setup, test that payment protection is working:
-
-**1. Start your Next.js dev server:**
 ```bash
 npm run dev
-```
 
-**2. Try accessing your protected route without payment:**
-```bash
+# Test without payment (should return 402)
 curl http://localhost:3000/api/premium/weather
 ```
 
-**Expected Response (402 Payment Required):**
+Expected 402 response:
 ```json
 {
   "x402Version": 1,
@@ -231,275 +264,213 @@ curl http://localhost:3000/api/premium/weather
     "network": "aptos-testnet",
     "maxAmountRequired": "1000000",
     "payTo": "0xYOUR_WALLET_ADDRESS",
-    "description": "Premium weather data",
+    "description": "Premium weather data access",
     "resource": "http://localhost:3000/api/premium/weather"
   }]
 }
 ```
 
-If you see this 402 response, your middleware is working perfectly!
-
-**3. For full payment testing:**
-- Use our [live demo](https://aptos-x402.vercel.app) to see the complete flow
-- Or implement client-side payment signing (see [Client Integration](#client-integration) below)
-
-## What is x402?
-
-[x402](https://github.com/coinbase/x402) is an open protocol by Coinbase for machine-to-machine micropayments using HTTP 402 status code. This SDK implements x402 for the Aptos blockchain.
-
-### Use Cases
+Test with payment using the client:
+```typescript
+import { x402axios } from 'aptos-x402';
 
-- **Pay-per-API-call** - Monetize your APIs without subscriptions
-- **AI Agent Payments** - Let AI agents pay for resources automatically
-- **Metered Services** - Charge exactly for what's consumed
-- **Decentralized Access Control** - No API keys, just payments
-- **Micropayments** - Enable sub-cent transactions economically
+const response = await x402axios.get('http://localhost:3000/api/premium/weather', {
+  privateKey: process.env.APTOS_PRIVATE_KEY
+});
+```
 
-## Features
+---
 
- - **Axios-compatible** - Drop-in replacement for axios with x402 payment support
- - **Zero payment logic in your code** - Middleware handles everything
- - **Aptos native** - Built on Aptos's fast finality (~1-3s)
- - **Type-safe** - Full TypeScript support with proper interfaces
- - **x402 compliant** - Follows official Coinbase specification
- - **Next.js optimized** - Designed for Next.js 15+ (more frameworks coming)
- - **Production ready** - Comprehensive error handling and logging
- - **Backward compatible** - Old interface still works alongside new axios interface
+## Architecture
 
-## How It Works
+### Protocol Flow
 
 ```
-┌─────────┐                  ┌─────────┐                  ┌────────────┐
-│ Client  │                  │  Your   │                  │   Aptos    │
-│         │                  │  API    │                  │ Blockchain │
-└────┬────┘                  └────┬────┘                  └─────┬──────┘
-     │                            │                              │
-     │  1. GET /api/premium      │                              │
-     │──────────────────────────>│                              │
-     │                            │                              │
-     │  2. 402 Payment Required  │                              │
-     │<──────────────────────────│                              │
-     │   {accepts: [...]}         │                              │
-     │                            │                              │
-     │  3. Sign Transaction       │                              │
-     │   (client-side)            │                              │
-     │                            │                              │
-     │  4. GET /api/premium      │                              │
-     │     X-PAYMENT: <signed>   │                              │
-     │──────────────────────────>│                              │
-     │                            │  5. Verify (fast)            │
-     │                            │──────────────┐               │
-     │                            │              │               │
-     │                            │<─────────────┘               │
-     │                            │                              │
-     │                            │  6. Settle (submit tx)       │
-     │                            │─────────────────────────────>│
-     │                            │                              │
-     │                            │  7. Confirmed                │
-     │                            │<─────────────────────────────│
-     │                            │                              │
-     │  8. 200 OK + Resource     │                              │
-     │<──────────────────────────│                              │
-     │   X-Payment-Response       │                              │
+┌──────────┐                 ┌──────────┐              ┌────────────┐         ┌───────────┐
+│  Client  │                 │   API    │              │ Facilitator│         │   Aptos   │
+│  (Buyer) │                 │ (Seller) │              │  Service   │         │Blockchain │
+└────┬─────┘                 └────┬─────┘              └─────┬──────┘         └─────┬─────┘
+     │                            │                          │                      │
+     │ GET /api/premium/data      │                          │                      │
+     │───────────────────────────>│                          │                      │
+     │                            │                          │                      │
+     │ 402 Payment Required       │                          │                      │
+     │<───────────────────────────│                          │                      │
+     │ {scheme, amount, payTo}    │                          │                      │
+     │                            │                          │                      │
+     │ [Build & Sign Transaction] │                          │                      │
+     │ (Client-side, offline)     │                          │                      │
+     │                            │                          │                      │
+     │ GET /api/premium/data      │                          │                      │
+     │ X-PAYMENT: <signed_tx>     │                          │                      │
+     │───────────────────────────>│                          │                      │
+     │                            │                          │                      │
+     │                            │ POST /verify             │                      │
+     │                            │─────────────────────────>│                      │
+     │                            │ {isValid: true}          │                      │
+     │                            │<─────────────────────────│                      │
+     │                            │                          │                      │
+     │                            │ POST /settle             │                      │
+     │                            │─────────────────────────>│                      │
+     │                            │                          │ Submit Transaction  │
+     │                            │                          │────────────────────>│
+     │                            │                          │ Confirmed (1-3s)     │
+     │                            │                          │<────────────────────│
+     │                            │ {success, txHash}        │                      │
+     │                            │<─────────────────────────│                      │
+     │                            │                          │                      │
+     │ 200 OK + Data              │                          │                      │
+     │<───────────────────────────│                          │                      │
+     │ X-PAYMENT-RESPONSE: {...}  │                          │                      │
+     │                            │                          │                      │
 ```
 
-## Installation & Setup
+### Components
 
-### 1. Install Dependencies
+| Component | Responsibility | Location |
+|-----------|----------------|----------|
+| **Client** | Request resources, sign transactions | Your application/agent |
+| **Middleware** | Intercept requests, enforce payment | Your Next.js server |
+| **Facilitator** | Verify & settle payments | Shared service or self-hosted |
+| **Aptos Blockchain** | Final settlement & verification | Decentralized network |
 
-```bash
-npm install aptos-x402 @aptos-labs/ts-sdk next
-```
-
-### 2. Environment Variables
+### Key Design Principles
 
-```env
-# Your wallet address (receives payments)
-PAYMENT_RECIPIENT_ADDRESS=0xYOUR_WALLET_ADDRESS_HERE
+- **Client-Side Signing** - Private keys never leave the client
+- **Stateless Protocol** - No sessions, cookies, or stored state
+- **Atomic Operations** - Payment settles or request fails (no partial states)
+- **Transparent** - All transactions verifiable on-chain
+- **HTTP Native** - Uses standard status codes and headers
 
-# Facilitator URL (required)
-# Option 1: Use public demo facilitator (easiest for testing)
-FACILITATOR_URL=https://aptos-x402.vercel.app/api/facilitator
+---
 
-# Option 2: Deploy your own for production
-# FACILITATOR_URL=https://yourdomain.com/api/facilitator
-```
+## API Reference
 
-### 3. Create Middleware
+### Server-Side API
 
-```typescript
-// middleware.ts
-import { paymentMiddleware } from 'aptos-x402';
+#### `paymentMiddleware()`
 
-export const middleware = paymentMiddleware(
-  process.env.PAYMENT_RECIPIENT_ADDRESS!,
-  {
-    // Configure your protected routes
-    '/api/premium/weather': {
-      price: '1000000',  // 0.01 APT
-      network: 'testnet',
-      config: {
-        description: 'Premium weather data',
-        mimeType: 'application/json',
-      },
-    },
-    '/api/premium/stocks': {
-      price: '5000000',  // 0.05 APT
-      network: 'testnet',
-      config: {
-        description: 'Real-time stock data',
-      },
-    },
-  },
-  {
-    // Facilitator handles blockchain interactions
-    url: process.env.FACILITATOR_URL!,
-  }
-);
+Creates Next.js middleware for x402 payment enforcement.
 
-export const config = {
-  matcher: ['/api/premium/:path*'],
-};
+**Signature:**
+```typescript
+function paymentMiddleware(
+  recipientAddress: string,
+  routes: Record<string, RouteConfig>,
+  facilitatorConfig: FacilitatorConfig
+): NextMiddleware
 ```
 
-### 4. Create Your API Route
-
-```typescript
-// app/api/premium/weather/route.ts
-import { NextResponse } from 'next/server';
+**Parameters:**
 
-export const dynamic = 'force-dynamic';
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `recipientAddress` | `string` | Aptos wallet address to receive payments |
+| `routes` | `Record<string, RouteConfig>` | Map of route paths to payment configs |
+| `facilitatorConfig` | `FacilitatorConfig` | Facilitator service configuration |
 
-export async function GET(request: Request) {
-  // Payment already verified & settled by middleware!
-  // Just return your premium data
-  
-  return NextResponse.json({
-    location: 'San Francisco',
-    temperature: 72,
-    forecast: '5-day detailed forecast',
-    premium: true,
-  });
+**RouteConfig:**
+```typescript
+interface RouteConfig {
+  price: string;                    // Amount in Octas
+  network?: 'testnet' | 'mainnet';  // Default: 'testnet'
+  config?: {
+    description?: string;           // Human-readable description
+    mimeType?: string;              // Response content type
+    outputSchema?: object;          // Optional JSON schema
+    maxTimeoutSeconds?: number;     // Request timeout
+  };
 }
 ```
 
-### 5. Set Up Facilitator
-
-The facilitator handles blockchain interactions. You need to deploy facilitator endpoints:
-
+**FacilitatorConfig:**
 ```typescript
-// app/api/facilitator/verify/route.ts
-// app/api/facilitator/settle/route.ts
+interface FacilitatorConfig {
+  url: string;  // Base URL (e.g., 'https://example.com/api/facilitator')
+}
 ```
 
-See the [full facilitator implementation](https://github.com/adipundir/aptos-x402/tree/main/app/api/facilitator) in the repository.
-
-## API Reference
-
-### `paymentMiddleware(recipientAddress, routes, facilitatorConfig)`
-
-Creates x402 payment middleware for Next.js.
-
-#### Parameters
-
-- **`recipientAddress`** (string, required): Your Aptos wallet address
-- **`routes`** (object, required): Route configuration mapping
-  - **`path`** (string): API route path
-  - **`config`** (RouteConfig):
-    - `price` (string): Payment amount in Octas (1 APT = 100,000,000 Octas)
-    - `network` (string): `'testnet'` or `'mainnet'`
-    - `config.description` (string, optional): Resource description
-    - `config.mimeType` (string, optional): Response MIME type
-    - `config.maxTimeoutSeconds` (number, optional): Max timeout
-- **`facilitatorConfig`** (object, required):
-  - `url` (string): Facilitator base URL
-
-#### Returns
+### Client-Side API
 
-Next.js middleware function
+#### `x402axios`
 
-## TypeScript Types
+Axios-compatible HTTP client with automatic x402 payment handling.
 
+**Methods:**
 ```typescript
-import type {
-  PaymentRequiredResponse,
-  PaymentRequirements,
-  PaymentPayload,
-  RouteConfig,
-  FacilitatorConfig,
-} from 'aptos-x402/types';
+x402axios.get(url, config?)
+x402axios.post(url, data?, config?)
+x402axios.put(url, data?, config?)
+x402axios.patch(url, data?, config?)
+x402axios.delete(url, config?)
+x402axios.request(config)
+x402axios.create(defaultConfig)
 ```
 
-### Core Types
-
+**Configuration:**
 ```typescript
-interface RouteConfig {
-  price: string;              // Amount in Octas
-  network?: string;           // 'testnet' | 'mainnet'
-  config?: {
-    description?: string;
-    mimeType?: string;
-    outputSchema?: Record<string, any>;
-    maxTimeoutSeconds?: number;
-  };
-}
-
-interface FacilitatorConfig {
-  url: string;  // Required facilitator URL
+interface X402AxiosConfig extends AxiosRequestConfig {
+  privateKey?: string;    // Aptos private key (hex string)
+  account?: Account;      // Or Aptos Account object
 }
+```
 
-interface PaymentRequiredResponse {
-  x402Version: number;
-  accepts: PaymentRequirements[];
-  error?: string;
+**Response:**
+```typescript
+interface X402Response<T = any> extends AxiosResponse<T> {
+  paymentInfo?: {
+    transactionHash: string;
+    amount: string;
+    recipient: string;
+    network: string;
+    settled: boolean;
+  };
 }
 ```
 
-## Client Integration
-
-### Simple Approach: Use x402axios
+### TypeScript Types
 
-The easiest way to consume protected APIs is with our **axios-compatible** wrapper:
+Import types for full type safety:
 
 ```typescript
-import { x402axios } from 'aptos-x402';
+import type {
+  RouteConfig,
+  FacilitatorConfig,
+  PaymentRequiredResponse,
+  PaymentRequirements,
+  PaymentPayload
+} from 'aptos-x402/types';
+```
 
-// Automatic payment handling - works exactly like axios!
-const response = await x402axios.get('https://api.example.com/premium/data', {
-  privateKey: '0x...'  // Your Aptos private key
-});
+---
 
-console.log(response.data);              // API response data
-console.log(response.paymentInfo);       // Payment details
-```
+## Advanced Usage
 
-### Advanced: Manual Implementation
+### Manual Payment Flow
 
-If you need more control, you can implement the payment flow manually:
+For full control over the payment process:
 
 ```typescript
 import { Aptos, AptosConfig, Network, Account, Ed25519PrivateKey } from '@aptos-labs/ts-sdk';
 
-async function callProtectedAPI(url: string, privateKey: string) {
-  // Step 1: Try without payment
+async function manualPaymentFlow(url: string, privateKey: string) {
+  // 1. Request without payment
   let response = await fetch(url);
   
   if (response.status === 402) {
-    // Step 2: Parse payment requirements
     const paymentReqs = await response.json();
     const requirement = paymentReqs.accepts[0];
     
-    // Step 3: Initialize Aptos client
+    // 2. Initialize Aptos client
     const config = new AptosConfig({ 
       network: requirement.network === 'aptos-testnet' ? Network.TESTNET : Network.MAINNET 
     });
     const aptos = new Aptos(config);
-    
-    // Step 4: Create account and build transaction
     const account = Account.fromPrivateKey({
       privateKey: new Ed25519PrivateKey(privateKey)
     });
     
+    // 3. Build and sign transaction
     const transaction = await aptos.transaction.build.simple({
       sender: account.accountAddress,
       data: {
@@ -508,9 +479,9 @@ async function callProtectedAPI(url: string, privateKey: string) {
       }
     });
     
-    // Step 5: Sign and create payment header
     const authenticator = aptos.transaction.sign({ signer: account, transaction });
     
+    // 4. Create payment payload
     const paymentPayload = {
       x402Version: 1,
       scheme: requirement.scheme,
@@ -521,7 +492,7 @@ async function callProtectedAPI(url: string, privateKey: string) {
       }
     };
     
-    // Step 6: Retry with payment
+    // 5. Retry with payment
     response = await fetch(url, {
       headers: {
         'X-PAYMENT': Buffer.from(JSON.stringify(paymentPayload)).toString('base64')
@@ -529,188 +500,211 @@ async function callProtectedAPI(url: string, privateKey: string) {
     });
   }
   
-  // Step 11: Get the data
-  const data = await response.json();
-  console.log('Success!', data);
-  
-  // Step 12: Check payment receipt (optional)
-  const paymentResponse = response.headers.get('x-payment-response');
-  if (paymentResponse) {
-    const receipt = JSON.parse(Buffer.from(paymentResponse, 'base64').toString());
-    console.log('Payment settled:', receipt.settlement.txHash);
-  }
-  
-  return data;
+  return await response.json();
 }
-
-// Usage
-await callProtectedAPI(
-  'http://localhost:3000/api/premium/weather',
-  '0xYOUR_PRIVATE_KEY_HERE'
-);
 ```
 
-### Quick Test with curl
+### Wallet Integration
 
-**1. Get payment requirements:**
-```bash
-curl http://localhost:3000/api/premium/weather
-```
+For browser applications, integrate with Aptos wallets:
 
-**Response:**
-```json
-{
-  "x402Version": 1,
-  "accepts": [{
-    "scheme": "exact",
-    "network": "aptos-testnet",
-    "maxAmountRequired": "1000000",
-    "payTo": "0xYOUR_WALLET_ADDRESS",
-    "resource": "http://localhost:3000/api/premium/weather"
-  }]
-}
+```typescript
+// Petra Wallet
+import { useWallet } from '@aptos-labs/wallet-adapter-react';
+
+const { signTransaction } = useWallet();
+const signedTx = await signTransaction(transaction);
 ```
 
-**2. Make payment request:**
+---
+
+## Examples & Demo
+
+### Interactive Demo
+
+Try the complete payment flow: **[aptos-x402.vercel.app](https://aptos-x402.vercel.app)**
+
+### Example Code
+
+| Example | Description | Path |
+|---------|-------------|------|
+| **Simple Seller** | Basic middleware setup | [`examples/simple-seller/`](./examples/simple-seller/) |
+| **Facilitator** | Self-hosted facilitator guide | [`examples/facilitator/`](./examples/facilitator/) |
+| **Full Demo** | Complete implementation | [`app/`](./app/) |
+
+### CLI Demo
+
 ```bash
-curl http://localhost:3000/api/premium/weather \
-  -H "X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoi..."
+git clone https://github.com/adipundir/aptos-x402
+cd aptos-x402
+npm install
+npm run dev  # In one terminal
+
+# In another terminal
+npx tsx scripts/test-x402-axios.ts
 ```
 
-### Browser Integration
+## Facilitator
 
-For browser applications, you can use wallet integrations:
+The facilitator handles blockchain operations (verification and settlement) separately from your API server.
 
-```typescript
-// Using Petra Wallet
-const { signTransaction } = usePetraWallet();
-const signedTx = await signTransaction(transaction);
-```
+### Options
 
-### AI Agent Integration
+| Option | Best For | Setup |
+|--------|----------|-------|
+| **Public Facilitator** | Development, testing, POCs | `FACILITATOR_URL=https://aptos-x402.vercel.app/api/facilitator` |
+| **Self-Hosted (Same App)** | Small to medium deployments | Copy facilitator routes to your Next.js app |
+| **Self-Hosted (Separate)** | Production, high scale | Deploy as standalone service |
 
-```typescript
-import { x402axios } from 'aptos-x402';
+### Why Separate?
 
-// Agent automatically handles payments
-const response = await x402axios.get('https://api.example.com/premium/data', {
-  privateKey: process.env.AGENT_KEY!
-});
+- **Security** - Isolate blockchain operations
+- **Scalability** - Share across multiple APIs
+- **Flexibility** - Upgrade independently
 
-const data = response.data;
-```
+See [Facilitator Setup Guide](./docs/guides/facilitator-setup.md) for detailed deployment instructions.
 
-## Examples
+## FAQ
 
-### Example Projects in This Repo
+<details>
+<summary><strong>Why use x402 instead of API keys?</strong></summary>
 
-- **[examples/simple-seller/](./examples/simple-seller/)** - Basic middleware configuration
-- **[examples/facilitator/](./examples/facilitator/)** - Facilitator setup guide  
-- **[app/](./app/)** - Complete working demo with frontend
+- No secrets to manage, rotate, or leak
+- True pay-per-use with no subscriptions
+- Decentralized with no auth server
+- Instant monetization without payment processors
 
-### Live Demo
+</details>
 
-Visit **https://aptos-x402.vercel.app** to see the complete payment flow in action:
-- Try requesting without payment (gets 402)
-- Sign transaction with demo account
-- See payment verification and settlement
-- View transaction on Aptos Explorer
+<details>
+<summary><strong>How fast are payments?</strong></summary>
 
-## Facilitator Setup
+| Operation | Time |
+|-----------|------|
+| Verification | < 50ms |
+| Settlement | 1-3 seconds |
+| **Total** | **~1-3 seconds** |
 
-The facilitator is a critical component that handles blockchain interactions (verify and settle operations).
+</details>
 
-### Why Separate Facilitator?
+<details>
+<summary><strong>What are the costs?</strong></summary>
 
-- **Security**: Keeps blockchain keys separate from app servers
-- **Scalability**: Can be shared across multiple services
-- **x402 Compliance**: Follows the official protocol architecture
+| Party | Cost |
+|-------|------|
+| **Client** | Gas (~$0.0001) + API price |
+| **Server** | Facilitator hosting only |
+| **Protocol** | Free, open source |
 
-### Options
+</details>
 
-#### 1. Use Public Demo Facilitator (Easiest)
+<details>
+<summary><strong>Is this production-ready?</strong></summary>
 
-```env
-FACILITATOR_URL=https://aptos-x402.vercel.app/api/facilitator
-```
+Yes, with proper testing:
+-  Start on testnet for development
+-  Thorough testing before mainnet
+-  Monitor facilitator health
+-  Implement error handling
 
-Perfect for:
-- Development and testing
-- Proof of concepts
-- Learning x402 protocol
+</details>
 
-**Note**: For production, deploy your own for better control and reliability.
+<details>
+<summary><strong>Can I use other blockchains?</strong></summary>
 
-#### 2. Deploy Your Own (Production)
+This SDK is Aptos-specific. x402 protocol supports any blockchain. Other implementations coming soon.
 
-Copy the facilitator implementation from the repository:
-- `app/api/facilitator/verify/route.ts`
-- `app/api/facilitator/settle/route.ts`
+</details>
 
-Deploy to:
-- Same Next.js app (simplest)
-- Separate microservice (recommended for scale)
-- Serverless functions (Vercel, AWS Lambda, etc.)
+<details>
+<summary><strong>Do I need a blockchain wallet?</strong></summary>
 
-See [Facilitator Guide](https://github.com/adipundir/aptos-x402/blob/main/examples/facilitator) for full setup instructions.
+**Sellers:** Need wallet address to receive payments (no private key on server)  
+**Buyers:** Need funded wallet to make payments
 
-## FAQ
+Generate testnet wallets: `npx tsx scripts/generate-account.ts`
+
+</details>
+
+<details>
+<summary><strong>How do AI agents use this?</strong></summary>
+
+Agents can autonomously make payments:
+```typescript
+const agent = createAgent({ privateKey: process.env.AGENT_KEY });
+const data = await x402axios.get(apiUrl, { privateKey: agent.key });
+```
 
-### Why not just use API keys?
+No human intervention required.
 
-- **No key management** - No secrets to rotate or leak
-- **Pay-per-use** - No subscriptions or upfront costs
-- **Decentralized** - No central auth server
-- **Monetization built-in** - Get paid automatically
+</details>
 
-### How fast are payments?
+---
 
-- **Verification**: < 50ms (cryptographic validation only)
-- **Settlement**: 1-3 seconds (Aptos blockchain finality)
-- **Total**: ~1-3 seconds for full payment confirmation
+## Performance Monitoring
 
-### What are the costs?
+Track payment performance with built-in timing headers:
 
-- **Client pays**: Transaction gas (~0.0001 APT) + your API price
-- **Server pays**: Nothing! Just host the facilitator
-- **Protocol fees**: None, x402 is free and open source
+```typescript
+const response = await x402axios.get(url, { privateKey });
 
-### Can I use this with other blockchains?
+// Check performance metrics
+const verifyTime = response.headers['x-verification-time'];
+const settleTime = response.headers['x-settlement-time'];
+const cached = response.headers['x-cached'] === 'true';
 
-This package is Aptos-specific. For other chains:
-- Ethereum: `@x402/ethereum` (coming soon)
-- Solana: `@x402/solana` (coming soon)
-- Sui: `@x402/sui` (coming soon)
+console.log(`Verification: ${verifyTime}ms`);
+console.log(`Settlement: ${settleTime}ms`);
+console.log(`Cached: ${cached}`);
+```
 
-### Is this production-ready?
+### Performance Benchmarks
 
-Yes! The protocol is designed for production use. However:
-- ⚠️ Start with testnet for development
-- ⚠️ Test thoroughly before mainnet deployment
-- ⚠️ Monitor facilitator health and security
+Run the included benchmark to measure your setup:
 
-## Contributing
+```bash
+APTOS_PRIVATE_KEY=0x... npx tsx scripts/benchmark-payment-flow.ts
+```
 
-Contributions welcome! Feel free to open issues or submit pull requests.
+**Expected Performance:**
+- First request (uncached): ~800-1000ms
+- Cached requests: ~650-800ms
+- Settlement alone: ~200-300ms
+- Legacy (pre-optimization): ~2000-3000ms
 
-## License
+**Optimization Details:** See [PERFORMANCE_OPTIMIZATIONS.md](./PERFORMANCE_OPTIMIZATIONS.md) for complete breakdown of the **5-10x performance improvements**.
 
-MIT © Aditya Pundir
+---
+
+## Resources
 
-## Links
+### Documentation
+- [Full Documentation](https://aptos-x402.vercel.app/docs)
+- [API Reference](./docs/api-reference/server-api.md)
+- [Protocol Specification](https://github.com/coinbase/x402)
+- [Performance Guide](./PERFORMANCE_OPTIMIZATIONS.md)
 
+### Links
 - [GitHub Repository](https://github.com/adipundir/aptos-x402)
 - [NPM Package](https://www.npmjs.com/package/aptos-x402)
-- [x402 Protocol Spec](https://github.com/coinbase/x402)
 - [Aptos Developer Docs](https://aptos.dev)
 
-## Support
+### Support
+- [Report Issues](https://github.com/adipundir/aptos-x402/issues)
+- [Discussions](https://github.com/adipundir/aptos-x402/discussions)
+- [Twitter: @aptos-x402](https://x.com/aptosx402)
+
+## Contributing
 
-- 🐛 [Report Issues](https://github.com/adipundir/aptos-x402/issues)
-- 💬 [Discussions](https://github.com/adipundir/aptos-x402/discussions)
-- 🐦 Twitter: [@adipundir](https://x.com/adipundir)
+Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
 
 ---
 
-Built with ❤️ for the Aptos ecosystem
+<div align="center">
+
+**Built for the Aptos Ecosystem**
+
+[Documentation](https://aptos-x402.vercel.app) • [GitHub](https://github.com/adipundir/aptos-x402) • [NPM](https://www.npmjs.com/package/aptos-x402)
+
+</div>