x402-payments

x402 Payments

XActions supports the x402 payment protocol — an HTTP-native micropayment standard for pay-per-use API access with cryptocurrency.

Entry Points

Goal	Route	Method
Discover payment capabilities	GET /.well-known/x402	Public
Get OpenAPI spec with payment info	GET /api/x402/openapi	Public
Make a paid API call	Any protected route	REST API (with x402 headers)

Configuration

Config lives in api/config/x402-config.js. Key settings:

{
  networks: ['base', 'ethereum', 'polygon', 'arbitrum'],  // Supported chains
  tokens: {
    base: ['USDC', 'ETH'],
    ethereum: ['USDC', 'USDT', 'ETH'],
    polygon: ['USDC', 'MATIC'],
    arbitrum: ['USDC', 'ETH'],
  },
  pricing: {
    'POST /api/operations/unfollow': { amount: '0.01', token: 'USDC' },
    'POST /api/operations/follow':   { amount: '0.005', token: 'USDC' },
    // ... per-route pricing
  }
}

Discovery (/.well-known/x402)

Returns a JSON manifest describing all payable routes, supported networks, and token addresses:

GET https://api.xactions.io/.well-known/x402

Response includes:

• List of payable API endpoints with prices
• Supported blockchain networks
• Token contract addresses per network
• Payment verification endpoint

Making a Paid Request

x402-compatible clients handle payment automatically. For manual integration:

# 1. Get payment requirements (HTTP 402 response)
POST /api/operations/unfollow → 402 Payment Required
  X-Payment-Required: { amount, token, network, recipient }

# 2. Submit on-chain payment + proof
POST /api/operations/unfollow
  X-Payment: <signed-payment-proof>

Middleware

api/middleware/x402.js handles:

• Detecting x402-protected routes
• Returning 402 Payment Required with payment details
• Verifying payment proofs before processing requests
• Multi-chain verification across Base, Ethereum, Polygon, Arbitrum

Supported Clients

Any x402-compatible client works automatically:

• x402-axios — Axios adapter with auto-payment
• x402-fetch — Fetch adapter with auto-payment
• Claude agents with x402 MCP tools
• Custom implementations following the x402 spec

Notes

• x402 payments are per-request — no subscription needed
• Payment proofs are cryptographically verified on-chain before operations run
• Use /.well-known/x402 for discovery in agent applications
• Stripe billing (billing-management skill) remains an alternative for subscription access

Related Skills

• billing-management — Stripe subscription-based payment alternative
• xactions-mcp-server — MCP server that uses x402 for AI agent access
• a2a-multi-agent — Agent-to-agent workflows that use x402 for payment