x402v2 compliant Payment Protocol SDK for Aptos - Axios-compatible payment wrapper with automatic network detection
npm install aptos-x402HTTP 402 Payment Protocol SDK for Aptos Blockchain



Documentation β’ API Reference β’ Demo
---
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).
PAYMENT-SIGNATURE headers (removed "X-").> Performance: Latest optimizations deliver faster settlement with verification caching, async confirmation, and smart deduplication.
| 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 |
``bash`
npm install aptos-x402
- 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)
Access x402-protected APIs with zero configuration. The x402axios client automatically detects payment requirements, builds transactions, and handles the entire payment flow.
`typescript
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);
`
`typescript
// 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...' });
`
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
---
Protect Next.js API routes with x402 middleware - zero payment code required in your route handlers.
Create .env.local in your project root:
`env`
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
Create middleware.ts in your project root (same level as app/ directory):
`typescript
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*']
};
`
Your API routes require zero payment logic - the middleware handles everything:
`typescript
// 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...'
});
}
`
| 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 |
Aptos uses Octas as the smallest unit (like satoshis or wei):
`typescript
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
`
Start your development server and verify payment protection:
`bash
npm run dev
Expected 402 response:
`json
{
"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:
`typescript
import { x402axios } from 'aptos-x402';const response = await x402axios.get('http://localhost:3000/api/premium/weather', {
privateKey: process.env.APTOS_PRIVATE_KEY
});
`---
Architecture
$3
`
ββββββββββββ ββββββββββββ ββββββββββββββ βββββββββββββ
β 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: β β β
ββββββββββββββββββββββββββββ>β β β
β β β β
β β POST /verify β β
β ββββββββββββββββββββββββββ>β β
β β {isValid: true} β β
β β<ββββββββββββββββββββββββββ β
β β β β
β β POST /settle β β
β ββββββββββββββββββββββββββ>β β
β β β Submit Transaction β
β β βββββββββββββββββββββ>β
β β β Confirmed (1-3s) β
β β β<βββββββββββββββββββββ
β β {success, txHash} β β
β β<ββββββββββββββββββββββββββ β
β β β β
β 200 OK + Data β β β
β<ββββββββββββββββββββββββββββ β β
β X-PAYMENT-RESPONSE: {...} β β β
β β β β
`$3
| 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 |
$3
- 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
$3
####
paymentMiddleware()Creates Next.js middleware for x402 payment enforcement.
Signature:
`typescript
function paymentMiddleware(
recipientAddress: string,
routes: Record,
facilitatorConfig: FacilitatorConfig
): NextMiddleware
`Parameters:
| Parameter | Type | Description |
|-----------|------|-------------|
|
recipientAddress | string | Aptos wallet address to receive payments |
| routes | Record | Map of route paths to payment configs |
| facilitatorConfig | FacilitatorConfig | Facilitator service configuration |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
};
}
`FacilitatorConfig:
`typescript
interface FacilitatorConfig {
url: string; // Base URL (e.g., 'https://example.com/api/facilitator')
}
`$3
####
x402axiosAxios-compatible HTTP client with automatic x402 payment handling.
Methods:
`typescript
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:
`typescript
interface X402AxiosConfig extends AxiosRequestConfig {
privateKey?: string; // Aptos private key (hex string)
account?: Account; // Or Aptos Account object
}
`Response:
`typescript
interface X402Response extends AxiosResponse {
paymentInfo?: {
transactionHash: string;
amount: string;
recipient: string;
network: string;
settled: boolean;
};
}
`$3
Import types for full type safety:
`typescript
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.
$3
| Feature | Description |
|---------|-------------|
| Identity Registry | Agent Cards with metadata, capabilities, and verification status |
| Reputation Registry | Trust scores based on feedback from interactions |
| Validation Registry | Task completion verification before payments |
| Flexible Storage | Memory (default), PostgreSQL, or custom backends |
| Optional On-Chain | Enable NFT minting and attestations when needed |
$3
`typescript
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"
`$3
`typescript
// 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 },
});
`$3
`typescript
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'),
});
`$3
`bash
.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):
`bash
ARC8004_MODULE_ADDRESS=0xa6cfe253f864c0eca623058c7ec2e80c645c5b0a5745c853e7082ee4daad077f
ARC8004_ONCHAIN_ENABLED=true
`$3
- 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
$3
For full control over the payment process:
`typescript
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();
}
`$3
For browser applications, integrate with Aptos wallets:
`typescript
// Petra Wallet
import { useWallet } from '@aptos-labs/wallet-adapter-react';const { signTransaction } = useWallet();
const signedTx = await signTransaction(transaction);
`---
Examples & Demo
$3
Try the complete payment flow: aptos-x402.org
$3
| Example | Description | Path |
|---------|-------------|------|
| Simple Seller | Basic middleware setup |
examples/simple-seller/ |
| Facilitator | Self-hosted facilitator guide | examples/facilitator/ |
| Full Demo | Complete implementation | app/ |$3
`bash
git clone https://github.com/adipundir/Aptos-x402
cd Aptos-x402
npm install
npm run dev # In one terminalIn another terminal
npx tsx scripts/test-x402-axios.ts
`Facilitator
The facilitator handles blockchain operations (verification and settlement) separately from your API server.
$3
| Option | Best For | Setup |
|--------|----------|-------|
| Public Facilitator | Development, testing, POCs |
url: "https://aptos-x402.org/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 |$3
- Security - Isolate blockchain operations
- Scalability - Share across multiple APIs
- Flexibility - Upgrade independently
See Facilitator Setup Guide for detailed deployment instructions.
FAQ
Why use x402 instead of API keys?
- No secrets to manage, rotate, or leak
- True pay-per-use with no subscriptions
- Decentralized with no auth server
- Instant monetization without payment processors
How fast are payments?
| Operation | Time |
|-----------|------|
| Verification | < 50ms |
| Settlement | 1-3 seconds |
| Total | ~1-3 seconds |
What are the costs?
| Party | Cost |
|-------|------|
| Client | Gas (~$0.0001) + API price |
| Server | Facilitator hosting only |
| Protocol | Free, open source |
Is this production-ready?
Yes, with proper testing:
- Start on testnet for development
- Thorough testing before mainnet
- Monitor facilitator health
- Implement error handling
Can I use other blockchains?
This SDK is Aptos-specific. x402 protocol supports any blockchain. Other implementations coming soon.
Do I need a blockchain wallet?
Sellers: Need wallet address to receive payments (no private key on server)
Buyers: Need funded wallet to make payments
Generate testnet wallets:
npx tsx scripts/generate-account.ts
How do AI agents use this?
Agents can autonomously make payments:
`typescript
const agent = createAgent({ privateKey: process.env.AGENT_KEY });
const data = await x402axios.get(apiUrl, { privateKey: agent.key });
`No human intervention required.
---
Performance Monitoring
Track payment performance with built-in timing headers:
`typescript
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});
`$3
Run the included benchmark to measure your setup:
`bash
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.
---
Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.
---
Built for the Aptos Ecosystem
Documentation β’ GitHub β’ NPM