Skip to main content

​
What is x402?

The x402 protocol enables pay-per-call HTTP APIs using blockchain micropayments. It’s based on the HTTP 402 “Payment Required” status code, which was originally reserved but never standardized.
Key Concept: Instead of subscriptions or API keys, services charge per-request. Users pay only for what they use.
In Arcana, every agent endpoint uses x402 to charge for its services. The backend orchestrator automatically handles payments when calling agents.

​
How x402 Works

​
Standard HTTP 402 Flow

1

Initial Request

Client makes a regular HTTP request to the protected endpoint:
GET /api/x402/oracle/price?symbol=BTC
2

402 Payment Required

Server responds with HTTP 402 and payment details:
{
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:84532",
    "payTo": "0xbaFF2E0939f89b53d4caE023078746C2eeA6E2F7",
    "amount": "10000000000000000",
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
  }]
}
3

Payment Submission

Client submits on-chain payment to the specified address:
await usdcContract.transfer(
  payTo,
  amount
);
4

Retry with Proof

Client retries the request with payment proof in headers:
GET /api/x402/oracle/price?symbol=BTC
X-Payment: {base64-encoded-payment-proof}
5

200 Success

Server verifies payment and returns the requested data:
{
  "success": true,
  "data": { "symbol": "BTC", "price": 97234.50 }
}

​
x402 in Arcana

​
Two Payment Layers

Arcana implements a two-tier payment system:

User → Backend

Upfront Query PaymentUsers pay $0.03 USDC to the backend orchestrator before asking questions.This covers:
  • AI orchestration (Gemini API)
  • Multiple agent calls
  • Response synthesis
  • Infrastructure costs

Backend → Agents

Per-Call Agent PaymentsBackend pays each agent per-call using x402:
  • Oracle: $0.01 per price lookup
  • Scout: $0.01 per on-chain query
  • News: $0.01 per news search
  • Yield: $0.01 per yield search
  • Tokenomics: $0.02 per analysis
  • NFT: $0.02 per collection lookup
  • Perp: $0.02 per market data

​
Protocol Versions

x402 supports two protocol versions:
Payment requirement in response body
HTTP/1.1 402 Payment Required

{
  "accepts": [{
    "network": "eip155:84532",
    "payTo": "0x...",
    "maxAmountRequired": "10000000000000000",
    "asset": "0x036CbD..."
  }]
}
Used by older agent implementations. Still supported for backward compatibility.

​
Payment Schemes

​
Exact Scheme

The exact scheme requires precise payment amounts: 
{
  "scheme": "exact",
  "price": "$0.01",           // Human-readable
  "network": "eip155:84532",  // Base Sepolia
  "payTo": "0x...",           // Seller wallet
}
  • Payment must match the exact amount specified
  • No overpayment or underpayment accepted
  • Simplest and most predictable scheme
All Arcana agents currently use the exact scheme for predictable pricing.

​
Future Schemes

The x402 protocol supports extensible schemes:
  • Range: Accept payments within a range (min/max)
  • Auction: Dynamic pricing based on demand
  • Subscription: Time-based access passes
  • Bundle: Bulk purchase discounts

​
Facilitator Service

The x402 Facilitator is a third-party service that simplifies payment verification:

Facilitator URL

https://www.x402.org/facilitator
Provides:
  • Payment verification services
  • Transaction settlement tracking
  • Receipt generation
  • Dispute resolution

​
How the Facilitator Works

  • Checks transaction status on-chain
  • Validates payment amount and recipient
  • Generates cryptographic proof
  • Returns settlement ID
  • Tracks payment lifecycle
  • Stores settlement metadata
  • Enables refund/dispute resolution
  • Provides audit trail
  • Issues tamper-proof receipts
  • Includes payment proof
  • Links to on-chain transaction
  • Supports accounting/tax reporting

​
Pinion Runtime Integration

Arcana uses Pinion (a Coinbase x402 runtime) to manage agent payments: 
import { payX402ThroughPinion } from './pinion-runtime';

const result = await payX402ThroughPinion(url, {
  method: 'GET',
  maxAmountAtomic: '10000000000000000',
  headers: { 'Accept': 'application/json' }
});

​
Pinion Features

Automatic Wallets

Provisions CDP wallets for each agent automatically

Payment Flow

Handles preflight, payment, and retry logic

Spend Limits

Enforces session and daily spending caps

Receipt Logging

Persists all payment receipts to Supabase

​
Session Spend Limits

Pinion tracks spending per-session: 
// Set runtime spend limit
POST /x402/runtime-spend-limit
{
  "action": "set",
  "maxUsdc": "1.00"
}

// Get current limit and usage
GET /x402/runtime-spend-limit
{
  "maxUsdc": "1.00",
  "spentUsdc": "0.15",
  "remainingUsdc": "0.85"
}

​
Procurement & Provider Scoring

Arcana implements a procurement layer that ranks and selects the best agent provider:

​
Provider Scoring Algorithm

score = (
  0.35 * successRate +
  0.15 * schemaRate +
  0.20 * qualityScore +
  0.15 * latencyScore +
  0.15 * priceScore
)
Percentage of successful calls (status 200-299)Higher success rate = higher score
Percentage of responses that match expected schemaValidates that agents return well-formed data
Composite score based on:
  • Data completeness
  • Response structure
  • Error rate
Response time normalized to 0-1 scaleFaster responses = higher score
Payment amount normalized to 0-1 scaleLower prices = higher score

​
Circuit Breaker

The procurement system includes a circuit breaker to prevent cascading failures: 
if (consecutiveFailures >= 3) {
  circuitOpenUntil = Date.now() + 180_000; // 3 minutes
  // Agent will be skipped until circuit closes
}
When an agent’s circuit is open, it will not be selected for new calls until the timeout expires.

​
x402 vs Traditional APIs

Traditional API

Pros:
  • Simple authentication
  • No blockchain required
  • Instant access
Cons:
  • Requires API key management
  • Monthly subscriptions
  • Vendor lock-in
  • No micropayments

x402 Protocol

Pros:
  • Pay per use
  • No subscriptions
  • Blockchain-verified payments
  • Trustless verification
Cons:
  • Requires crypto wallet
  • On-chain transaction fees
  • More complex integration

​
Example: Oracle Agent Call

Here’s a complete x402 flow for calling the Oracle agent: 
import { payX402ThroughPinion } from './pinion-runtime';

// 1. Call agent endpoint (preflight)
const url = 'http://localhost:3001/api/x402/oracle/price?symbol=BTC';

// 2. Pinion handles payment automatically
const result = await payX402ThroughPinion(url, {
  method: 'GET',
  maxAmountAtomic: '10000000000000000', // 0.01 USDC
});

// 3. Get the price data
console.log(result.data);
// {
//   "success": true,
//   "data": {
//     "symbol": "BTC",
//     "name": "Bitcoin",
//     "price": 97234.50,
//     "change24h": 2.34,
//     "marketCap": 1920000000000,
//     "volume24h": 45000000000
//   },
//   "payment": {
//     "amount": "$0.01",
//     "network": "eip155:84532",
//     "payTo": "0xbaFF2E0939f89b53d4caE023078746C2eeA6E2F7"
//   }
// }

​
Resources

x402 Specification

Official protocol specification and standards

Coinbase x402 Docs

Coinbase Developer Platform x402 documentation

Pinion Runtime

Pinion runtime library for x402 payments

Payment Flow

See the complete payment flow in Arcana

Build docs developers (and LLMs) love

Get started for freeTalk to us