API Reference

Complete documentation for integrating x402-RPC-Aggregator into your applications. This API provides intelligent RPC routing with built-in x402 micropayment support for Solana, Ethereum, and Base chains.

Quick Start

Make your first RPC call in less than 5 minutes.

1. Make an RPC Request

curl -X POST https://x402labs.cloud/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "method": "getSlot",
    "chain": "solana"
  }'

2. Receive 402 Payment Challenge

{
  "invoice": {
    "amount": 0.0001,
    "to": "FacilitatorWalletAddress...",
    "network": "solana-mainnet",
    "provider": "Triton One",
    "nonce": "1730000000000-abc123"
  }
}

3. Pay and Retry (Automatic with SDK)

import { X402Agent } from './x402-client';

const agent = new X402Agent('https://x402labs.cloud/');
const result = await agent.callRPC('getSlot', [], 'solana');

console.log('Slot:', result.result);
console.log('Tx Hash:', result.x402.paymentInfo.txHash);

Authentication LIVE

x402-RPC-Aggregator uses the x402 protocol for authentication. Instead of API keys, you pay per request using USDC micropayments on Solana or Base.

Payment Flow

1. Make request without payment → Receive 402 with invoice
2. Sign payment with wallet (Phantom/MetaMask)
3. Retry request with x402-payment header
4. Facilitator verifies & settles payment
5. Receive RPC response with receipt

RPC Endpoint LIVE

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": 182456789,
  "x402": {
    "provider": "Triton One",
    "paymentInfo": {
      "provider": "solana",
      "chain": "solana",
      "txHash": "5x...",
      "amount": 0.0001,
      "explorer": "https://orb.helius.dev/tx/5x..."
    },
    "cost": 0.0001,
    "status": "settled"
  }
}

{
  "invoice": {
    "amount": 0.0001,
    "to": "FacilitatorWallet...",
    "network": "solana-mainnet",
    "resource": "/rpc",
    "nonce": "unique-nonce",
    "provider": "Triton One",
    "batchOption": {
      "calls": 1000,
      "price": 0.08,
      "savings": "20%"
    }
  }
}

Health Check

curl https://x402labs.cloud//health

{
  "status": "ok",
  "timestamp": "2025-10-27T12:00:00.000Z",
  "version": "1.0.0",
  "chains": ["solana", "ethereum", "base"],
  "stats": {
    "totalProviders": 8,
    "activeProviders": 8,
    "healthyProviders": 7,
    "averageLatency": 312
  }
}

List Providers

curl 'https://x402labs.cloud//providers?chain=solana'

{
  "providers": [
    {
      "id": "triton-solana",
      "name": "Triton One",
      "chains": ["solana"],
      "costPerCall": 0.0001,
      "batchCost": { "calls": 1000, "price": 0.08 },
      "status": "active",
      "priority": 100,
      "averageLatency": 245
    }
  ],
  "total": 1
}

Routing Strategies LIVE

Customize how the aggregator selects RPC providers for your requests.

Available Strategies

{
  "method": "getSlot",
  "chain": "solana",
  "preferences": {
    "strategy": "lowest-cost"
  }
}

{
  "method": "getSlot",
  "chain": "solana",
  "preferences": {
    "strategy": "lowest-latency",
    "maxLatencyMs": 2000
  }
}

{
  "method": "getSlot",
  "chain": "solana",
  "preferences": {
    "strategy": "highest-priority"
  }
}

{
  "method": "getSlot",
  "chain": "solana",
  "preferences": {
    "strategy": "round-robin"
  }
}

Batch Payments LIVE

Purchase multiple calls upfront for discounted pricing (20% savings).

Get Batch Pricing

curl 'https://x402labs.cloud/batch-pricing?chain=solana'

Response

{
  "chain": "solana",
  "batchOptions": [
    {
      "providerId": "triton-solana",
      "providerName": "Triton One",
      "calls": 1000,
      "price": 0.08,
      "pricePerCall": 0.00008,
      "savings": "20.0%"
    }
  ]
}

Purchase Batch

Include batchPurchase: true in payment payload to buy a batch.

Use Batch

Include batch ID in header for subsequent calls:

curl -X POST /rpc \
  -H "x402-batch: {\"batchId\": \"batch_123...\"}" \
  -d '{"method":"getSlot","chain":"solana"}'

Error Handling

HTTP Status Codes

JavaScript/TypeScript SDK

import { X402Agent } from './lib/x402-client';

// Initialize agent
const agent = new X402Agent('https://x402labs.cloud/');

// Make RPC call (handles payment automatically)
const result = await agent.callRPC('getSlot', [], 'solana');

console.log('Current slot:', result.result);
console.log('Payment tx:', result.x402.paymentInfo.txHash);

With Preferences

const result = await agent.callRPC(
  'getBalance',
  ['SomeWalletAddress...'],
  'solana',
  {
    strategy: 'lowest-latency',
    maxLatencyMs: 1500,
    preferredProviders: ['triton-solana']
  }
);

Python (Concept)

from x402_client import X402Agent

# Initialize
agent = X402Agent('https://x402labs.cloud/')

# Make call
result = agent.call_rpc('getSlot', [], chain='solana')
print(f"Slot: {result['result']}")
print(f"Tx: {result['x402']['paymentInfo']['txHash']}")

cURL Examples

Solana - Get Slot

curl -X POST https://x402labs.cloud/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "method": "getSlot",
    "chain": "solana"
  }'

Ethereum - Block Number

curl -X POST https://x402labs.cloud/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "method": "eth_blockNumber",
    "chain": "ethereum"
  }'

With Custom Routing

curl -X POST https://x402labs.cloud/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "method": "getSlot",
    "chain": "solana",
    "preferences": {
      "strategy": "lowest-latency",
      "maxLatencyMs": 2000
    }
  }'