Aptos x402

Overview

Aptos x402 is a TypeScript SDK implementing the x402 v2 protocol (spec) for the Aptos blockchain. Enable your APIs to require cryptocurrency payments before serving responses using the standardized HTTP 402 status code.

✅ x402 v2 compliant

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

What’s new in 2.2.0

• 🛡️ ARC-8004 Agent Trust Layer: Agent identity, reputation, and task validation (Aptos-native).
• ⛽ Geomi Gas Sponsorship: Native support for gasless transactions (facilitator pays gas).
• 📋 Protocol Updates: Standardized PAYMENT-SIGNATURE headers (removed "X-").
• 💰 Fungible Assets: Direct USDC/FA transfer support.
• 🚚 Header-Based Spec: Payment specs and proofs handling moved entirely to headers.
• ⚡ Performance: Significant speed improvements with bug fixes and optimizations.

⚡ Performance: Latest optimizations deliver faster settlement with verification caching, async confirmation, and smart deduplication.

Use Cases

Quick Start

Installation

npm install aptos-x402

Requirements

• 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)

🛒 Client Integration (Consuming Paid APIs)

Access x402-protected APIs with zero configuration. The x402axios client automatically detects payment requirements, builds transactions, and handles the entire payment flow.

Basic Usage

import { x402axios } from 'aptos-x402';

const response = await x402axios.get('https://api.example.com/premium/data', {
  privateKey: process.env.APTOS_PRIVATE_KEY
});

// Access response data
console.log(response.data);

// Verify payment details
console.log('Transaction:', response.paymentInfo?.transactionHash);
console.log('Amount:', response.paymentInfo?.amount);

Supported HTTP Methods

// GET with parameters
await x402axios.get('/data', {
  privateKey: process.env.APTOS_PRIVATE_KEY,
  params: { filter: 'active' }
});

// POST with body
await x402axios.post('/analyze', 
  { text: 'Content to analyze' },
  { privateKey: process.env.APTOS_PRIVATE_KEY }
);

// 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...' });

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

🏪 Server Integration (Monetizing Your APIs)

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:

PAYMENT_RECIPIENT_ADDRESS=0xYOUR_APTOS_WALLET_ADDRESS
FACILITATOR_URL=https://aptos-x402.org/api/facilitator

Getting a Wallet Address:
Install Petra Wallet or generate programmatically with @aptos-labs/ts-sdk

Step 2: Create Middleware

Create middleware.ts in your project root (same level as app/ directory):

import { paymentMiddleware } from 'aptos-x402';

export const middleware = paymentMiddleware(
  process.env.PAYMENT_RECIPIENT_ADDRESS!,
  {
    '/api/premium/weather': {
      price: '1000000',  // 0.01 APT (1 APT = 100,000,000 Octas)
      network: 'testnet',
      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 the official public facilitator for free
    url: "https://aptos-x402.org/api/facilitator"
  }
);

export const config = {
  matcher: ['/api/premium/:path*']
};

Step 3: Create Protected Routes

Your API routes require zero payment logic - the middleware handles everything:

// app/api/premium/weather/route.ts
import { NextResponse } from 'next/server';

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...'
  });
}

Middleware Behavior

Price Configuration

Aptos uses Octas as the smallest unit (like satoshis or wei):

1 APT = 100,000,000 Octas

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

Testing Your Integration

Start your development server and verify payment protection:

npm run dev

# Test without payment (should return 402)
curl http://localhost:3000/api/premium/weather

Expected 402 response:

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "aptos-testnet",
    "maxAmountRequired": "1000000",
    "payTo": "0xYOUR_WALLET_ADDRESS",
    "description": "Premium weather data access",
    "resource": "http://localhost:3000/api/premium/weather"
  }]
}

Test with payment using the client:

import { x402axios } from 'aptos-x402';

const response = await x402axios.get('http://localhost:3000/api/premium/weather', {
  privateKey: process.env.APTOS_PRIVATE_KEY
});

Architecture

Protocol Flow

┌──────────┐                 ┌──────────┐              ┌────────────┐         ┌───────────┐
│  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: {...}  │                          │                      │
     │                            │                          │                      │

Components

Key Design Principles

• 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

API Reference

Server-Side API

paymentMiddleware()

Creates Next.js middleware for x402 payment enforcement.

Signature:

function paymentMiddleware(
  recipientAddress: string,
  routes: Record<string, RouteConfig>,
  facilitatorConfig: FacilitatorConfig
): NextMiddleware

Parameters:

RouteConfig:

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
  };
}

FacilitatorConfig:

interface FacilitatorConfig {
  url: string;  // Base URL (e.g., 'https://example.com/api/facilitator')
}

Client-Side API

x402axios

Axios-compatible HTTP client with automatic x402 payment handling.

Methods:

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)

Configuration:

interface X402AxiosConfig extends AxiosRequestConfig {
  privateKey?: string;    // Aptos private key (hex string)
  account?: Account;      // Or Aptos Account object
}

Response:

interface X402Response<T = any> extends AxiosResponse<T> {
  paymentInfo?: {
    transactionHash: string;
    amount: string;
    recipient: string;
    network: string;
    settled: boolean;
  };
}

TypeScript Types

Import types for full type safety:

import type {
  RouteConfig,
  FacilitatorConfig,
  PaymentRequiredResponse,
  PaymentRequirements,
  PaymentPayload
} from 'aptos-x402/types';

🛡️ ARC-8004: Agent Trust Layer

ARC-8004 provides identity, reputation, and validation for AI agents on Aptos. It integrates with x402 payments to build trust signals from paid interactions.

Features

Quick Start (v2.0 - Recommended)

import { createARC8004Client } from 'aptos-x402/arc8004';

// Create client - works with zero config (memory storage)
const client = await createARC8004Client();

// Register an agent identity
const { identity } = await client.identity.register({
  agentId: 'my-agent',
  agentCard: {
    name: 'WeatherBot',
    description: 'Provides weather data',
    version: '1.0.0',
    capabilities: ['payment', 'data-fetch'],
    protocols: ['x402'],
    supportedNetworks: ['aptos-testnet'],
    owner: { address: '0x...', publicKey: '0x...' },
  },
});

// Submit feedback after payment
await client.reputation.submitFeedback({
  agentId: 'my-agent',
  clientAddress: '0xclient',
  overallScore: 5,
  paymentHash: '0xPAYMENT_TX',
  feedback: { comment: 'Fast response!' },
});

// Get reputation
const rep = await client.reputation.getReputation('my-agent');
console.log('Trust Level:', rep?.trustLevel); // "excellent"

Storage Options

// Memory (default) - No database required
const client = await createARC8004Client({
  config: { storageType: 'memory', skipAgentValidation: true },
});

// Database - PostgreSQL with Drizzle ORM
const client = await createARC8004Client({
  config: { storageType: 'database' },
});

// Custom - Bring your own storage
const client = await createARC8004Client({
  config: { storageType: 'custom' },
  storage: { identity: myStorage, reputation: myRepStorage, validation: myValStorage },
});

On-Chain Integration (Optional)

import { createARC8004Client, AptosOnChainProvider } from 'aptos-x402/arc8004';

const client = await createARC8004Client({
  config: { 
    storageType: 'memory',
    moduleAddress: '0xYOUR_CONTRACT',
    network: 'aptos-testnet',
  },
  onChain: new AptosOnChainProvider('aptos-testnet', '0xYOUR_CONTRACT'),
});

Configuration

# .env.local
ARC8004_AUTO_REGISTER=true        # Auto-register agents on creation
ARC8004_ONCHAIN_ENABLED=false     # DB-only mode (recommended)

For on-chain NFT minting (optional):

ARC8004_MODULE_ADDRESS=0xa6cfe253f864c0eca623058c7ec2e80c645c5b0a5745c853e7082ee4daad077f
ARC8004_ONCHAIN_ENABLED=true

Documentation

• ARC-8004 Integration Guide - Full SDK usage (NEW)
• ARC-8004 Core Concepts - Architecture overview
• ARC-8004 Use Cases - Practical examples
• Self-Hosting Guide - Deploy your own contracts

Advanced Usage

Manual Payment Flow

For full control over the payment process:

import { Aptos, AptosConfig, Network, Account, Ed25519PrivateKey } from '@aptos-labs/ts-sdk';

async function manualPaymentFlow(url: string, privateKey: string) {
  // 1. Request without payment
  let response = await fetch(url);
  
  if (response.status === 402) {
    const paymentReqs = await response.json();
    const requirement = paymentReqs.accepts[0];
    
    // 2. Initialize Aptos client
    const config = new AptosConfig({ 
      network: requirement.network === 'aptos-testnet' ? Network.TESTNET : Network.MAINNET 
    });
    const aptos = new Aptos(config);
    const account = Account.fromPrivateKey({
      privateKey: new Ed25519PrivateKey(privateKey)
    });
    
    // 3. Build and sign transaction
    const transaction = await aptos.transaction.build.simple({
      sender: account.accountAddress,
      data: {
        function: '0x1::aptos_account::transfer',
        functionArguments: [requirement.payTo, requirement.maxAmountRequired]
      }
    });
    
    const authenticator = aptos.transaction.sign({ signer: account, transaction });
    
    // 4. Create payment payload
    const paymentPayload = {
      x402Version: 1,
      scheme: requirement.scheme,
      network: requirement.network,
      payload: {
        signature: Buffer.from(authenticator.bcsToBytes()).toString('base64'),
        transaction: Buffer.from(transaction.bcsToBytes()).toString('base64')
      }
    };
    
    // 5. Retry with payment
    response = await fetch(url, {
      headers: {
        'Payment': Buffer.from(JSON.stringify(paymentPayload)).toString('base64')
      }
    });
  }
  
  return await response.json();
}

Wallet Integration

For browser applications, integrate with Aptos wallets:

// Petra Wallet
import { useWallet } from '@aptos-labs/wallet-adapter-react';

const { signTransaction } = useWallet();
const signedTx = await signTransaction(transaction);

Examples & Demo

Interactive Demo

Try the complete payment flow: aptos-x402.org

Example Code

CLI Demo

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

Facilitator

The facilitator handles blockchain operations (verification and settlement) separately from your API server.

Options

Why Separate?

• Security - Isolate blockchain operations
• Scalability - Share across multiple APIs
• Flexibility - Upgrade independently

See Facilitator Setup Guide for detailed deployment instructions.

FAQ

const agent = createAgent({ privateKey: process.env.AGENT_KEY });
const data = await x402axios.get(apiUrl, { privateKey: agent.key });

Performance Monitoring

Track payment performance with built-in timing headers:

const response = await x402axios.get(url, { privateKey });

// Check performance metrics
const verifyTime = response.headers['verification-time'];
const settleTime = response.headers['settlement-time'];
const cached = response.headers['cached'] === 'true';

console.log(`Verification: ${verifyTime}ms`);
console.log(`Settlement: ${settleTime}ms`);
console.log(`Cached: ${cached}`);

Performance Benchmarks

Run the included benchmark to measure your setup:

APTOS_PRIVATE_KEY=0x... npx tsx scripts/benchmark-payment-flow.ts

Expected Performance:

• First request (uncached): ~800-1000ms
• Cached requests: ~650-800ms
• Settlement alone: ~200-300ms
• Legacy (pre-optimization): ~2000-3000ms

Optimization Details: See PERFORMANCE_OPTIMIZATIONS.md for complete breakdown of the 5-10x performance improvements.

Resources

Documentation

• Full Documentation
• API Reference
• Protocol Specification
• Performance Guide

Links

• GitHub Repository
• NPM Package
• Aptos Developer Docs

Support

• Report Issues
• Discussions
• Twitter: @aptos-x402

Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.