x402 Primitives Catalog

The full-stack pay-per-call API for crypto infrastructure. Every endpoint is x402-native — agents and developers pay USDC per request on Base. No API keys, no accounts, no subscriptions.

20 Primitives

6 Categories

USDC on Base

gateway.spraay.app

Quick Start — Make your first x402 call

// Install the x402 client
npm install x402-client

// Make a paid API call — payment is automatic
import { createClient } from "x402-client";

const client = createClient({
  baseUrl: "https://gateway.spraay.app",
  privateKey: process.env.EVM_PRIVATE_KEY,  // Wallet with USDC on Base
});

// Fetch live ETH price — pays $0.002 USDC automatically
const prices = await client.get("/api/v1/prices");
console.log(prices);  // { ETH: 2847.50, ... }

// Batch send USDC to 50 wallets — pays $0.01 USDC
const tx = await client.post("/api/v1/batch", {
  token: "USDC",
  recipients: [{ address: "0x...", amount: "10.00" }, /* ... */]
});

🪪

Identity & Access

2 endpoints

POST x402 KYC/KYB

On-demand identity verification — compliance-gated batch payments

/api/v1/kyc/verify

$0.25 USDC

▼

Parameters

wallet_address string — Address to verify
level string — "basic" | "enhanced" | "kyb"
chain string — Target chain (default: "base")

Status: Coming SoonLatency: ~2s

Example

const result = await client.post(
  "/api/v1/kyc/verify", {
    wallet_address: "0xAb5...",
    level: "basic"
  }
);
// { verified: true, score: 92,
//   flags: [], expires: "2025-..." }

POST x402 Auth/SSO

Pay-per-session authentication proxy for third-party services

/api/v1/auth/session

$0.01 USDC

▼

Parameters

provider string — Service to authenticate with
wallet_address string — Wallet for session binding
ttl number — Session duration in seconds

Status: Coming SoonLatency: ~500ms

Example

const session = await client.post(
  "/api/v1/auth/session", {
    provider: "github",
    wallet_address: "0xAb5...",
    ttl: 3600
  }
);
// { token: "ey...", expires_at: "..." }

📡

Data & Intelligence

4 endpoints

GET x402 Oracle

Real-time price feeds, gas estimates, FX rates — live off-chain data

/api/v1/prices

$0.002 USDC

▼

Parameters

tokens string[] — Token symbols (e.g. ["ETH","USDC"])
vs_currency string — Quote currency (default: "usd")
include_gas boolean — Include gas price estimates

Status: LiveLatency: ~120msCache: 10s

Example

const data = await client.get(
  "/api/v1/prices?tokens=ETH,USDC"
);
// { ETH: { usd: 2847.50, change_24h: 1.2 },
//   USDC: { usd: 1.00 },
//   gas: { base: "0.004 gwei" } }

▶ Try it live

GET x402 Analytics

Wallet analytics, portfolio scoring, transaction risk profiling

/api/v1/analytics

$0.005 USDC

▼

Parameters

address string — Wallet or ENS to analyze
chain string — Chain to query (default: "base")
depth string — "summary" | "full"

Status: LiveLatency: ~800ms

Example

const report = await client.get(
  "/api/v1/analytics?address=vitalik.eth"
);
// { portfolio_value: "$1.2M",
//   risk_score: 12, tx_count: 4821 }

GET x402 Indexer

Pay-per-query blockchain indexing — tx history, balances across chains

/api/v1/index/query

$0.003 USDC

▼

Parameters

address string — Wallet address to index
chains string[] — Chains to query
type string — "balances" | "history" | "nfts"

Status: Coming SoonLatency: ~1.5s

Example

const history = await client.get(
  "/api/v1/index/query", {
    address: "0xAb5...",
    chains: ["base", "ethereum"],
    type: "history"
  }
);
// { transactions: [...], total: 142 }

POST x402 AI Inference

Pay-per-call ML models — fraud detection, tx classification, clustering

/api/v1/ai/chat

$0.01 USDC

▼

Parameters

model string — Model ID (OpenAI-compatible)
messages array — Chat messages array
max_tokens number — Max response tokens

Status: Live200+ models via OpenRouter

Example

const resp = await client.post(
  "/api/v1/ai/chat", {
    model: "anthropic/claude-sonnet",
    messages: [{
      role: "user",
      content: "Classify this tx..."
    }]
  }
);
// { response: "This appears to be..." }

▶ Try it live

📧

Communication & Notification

3 endpoints

POST x402 Email/SMS

Payment confirmations, alerts, receipts via AgentMail & Twilio

/api/v1/notify/send

$0.005 USDC

▼

Parameters

channel string — "email" | "sms"
to string — Recipient address or phone
subject string — Email subject line
body string — Message body (text or HTML)

Email: Live (AgentMail)SMS: Pending (Twilio)

Example

await client.post("/api/v1/notify/send", {
  channel: "email",
  to: "team@company.com",
  subject: "Payroll Complete",
  body: "50 recipients paid via Spraay"
});
// { sent: true, id: "msg_a1b2c3" }

POST x402 Webhook

Pay-per-delivery event forwarding — tx confirmations, status callbacks

/api/v1/webhook/register

$0.002 USDC

▼

Parameters

url string — Your webhook endpoint URL
events string[] — Events to subscribe to
secret string — Signing secret for verification

Status: Coming SoonEvents: tx.confirmed, batch.complete, payment.received

Example

await client.post("/api/v1/webhook/register", {
  url: "https://myapp.com/hooks",
  events: ["batch.complete"],
  secret: "whsec_..."
});
// { id: "wh_x9y8", active: true }

POST x402 XMTP Relay

Agent-to-agent & agent-to-user encrypted messaging via XMTP

/api/v1/xmtp/send

$0.003 USDC

▼

Parameters

to string — Recipient wallet or ENS
message string — Message content
content_type string — "text" | "attachment"

Provider: XMTP (Fly.io)Status: Coming Soon

Example

await client.post("/api/v1/xmtp/send", {
  to: "0xRecipient...",
  message: "Payment of 50 USDC sent",
  content_type: "text"
});
// { sent: true, conversation_id: "..." }

💰

Financial Primitives

5 endpoints

POST x402 Escrow

Conditional batch payments — milestone-based, time-locked escrow contracts

/api/v1/escrow/create

$0.02 USDC

▼

Parameters

token string — Token symbol or address
amount string — Amount to escrow
recipient string — Recipient address
conditions object — Release conditions (milestone, time-lock)

Status: Live

Example

const escrow = await client.post(
  "/api/v1/escrow/create", {
    token: "USDC",
    amount: "5000",
    recipient: "0xFreelancer...",
    conditions: {
      type: "milestone",
      deadline: "2025-04-01"
    }
  }
);
// { escrow_id: "esc_...", tx: "0x..." }

GET x402 Swap

Atomic swap quotes & execution via Uniswap V3 / Aerodrome

/api/v1/swap/quote

$0.005 USDC

▼

Parameters

from string — Input token symbol
to string — Output token
amount string — Input amount
slippage number — Max slippage % (default: 0.5)

Status: LiveDEXs: Uniswap V3, Aerodrome

Example

const quote = await client.get(
  "/api/v1/swap/quote?from=USDC&to=WETH&amount=100"
);
// { amountOut: "0.0351",
//   route: "USDC→WETH",
//   priceImpact: "0.02%" }

▶ Try it live

POST x402 Bridge

Cross-chain token transfers across Spraay's 11-chain footprint

/api/v1/bridge/transfer

$0.02 USDC

▼

Parameters

from_chain string — Source chain
to_chain string — Destination chain
token string — Token to bridge
amount string — Amount

Status: LiveChains: 11 supported

Example

const bridge = await client.post(
  "/api/v1/bridge/transfer", {
    from_chain: "base",
    to_chain: "arbitrum",
    token: "USDC",
    amount: "1000"
  }
);
// { bridge_id: "br_...", eta: "~2 min" }

POST x402 Payroll

Agent-driven payroll via StablePay — recurring batch payments

/api/v1/payroll/run

$0.01 USDC

▼

Parameters

name string — Payroll run name
token string — Payment token
employees array — [{address, amount, memo}]
schedule string — "once" | "weekly" | "monthly"

Status: LivePowered by: StablePay

Example

const run = await client.post(
  "/api/v1/payroll/run", {
    name: "March 2025",
    token: "USDC",
    employees: [
      { address: "0x...", amount: "3500" },
      { address: "0x...", amount: "4200" }
    ]
  }
);
// { payroll_id: "pr_...", tx: "0x..." }

POST x402 Invoice

On-demand invoice generation with payment tracking & receipts

/api/v1/invoice/create

$0.005 USDC

▼

Parameters

to string — Client wallet or email
items array — Line items [{desc, amount}]
token string — Accepted payment token
due_date string — Payment deadline

Status: Live

Example

const inv = await client.post(
  "/api/v1/invoice/create", {
    to: "client@co.com",
    items: [{ desc: "Dev work",
              amount: "2500" }],
    token: "USDC",
    due_date: "2025-04-15"
  }
);
// { invoice_id: "inv_...",
//   pay_link: "https://..." }

🖧

Infrastructure & DevOps

4 endpoints

POST x402 RPC

Premium multi-chain RPC via Alchemy — 7 chains behind one paywall

/api/v1/rpc

$0.001 USDC

▼

Parameters

chain string — Target chain
method string — JSON-RPC method
params array — Method parameters

Provider: AlchemyChains: 7

Example

const block = await client.post(
  "/api/v1/rpc", {
    chain: "base",
    method: "eth_blockNumber",
    params: []
  }
);
// { result: "0x1a2b3c" }

POST x402 IPFS/Arweave

Permanent storage pinning for receipts, proofs, metadata via Pinata

/api/v1/storage/pin

$0.01 USDC

▼

Parameters

content string|object — Content to pin
name string — Pin name/label
backend string — "ipfs" | "arweave"

Provider: PinataStatus: Coming Soon

Example

const pin = await client.post(
  "/api/v1/storage/pin", {
    content: { receipt: "...", tx: "0x..." },
    name: "payroll-receipt-march",
    backend: "ipfs"
  }
);
// { cid: "Qm...", url: "https://..." }

POST x402 Cron/Scheduler

Scheduled tasks — recurring payments, DCA triggers, automated sprays

/api/v1/cron/schedule

$0.005 USDC

▼

Parameters

cron string — Cron expression
action object — API call to execute
max_runs number — Max executions (0 = unlimited)

Status: Coming Soon

Example

await client.post("/api/v1/cron/schedule", {
  cron: "0 9 1 * *",  // 1st of month
  action: {
    endpoint: "/api/v1/payroll/run",
    body: { name: "Monthly" }
  },
  max_runs: 12
});
// { job_id: "cron_...", next: "..." }

POST x402 Logging

Structured log ingestion & querying for debugging agent workflows

/api/v1/logs

$0.001 USDC

▼

Parameters

action string — "ingest" | "query"
entries array — Log entries to store
filter object — Query filters

Status: Coming Soon

Example

await client.post("/api/v1/logs", {
  action: "ingest",
  entries: [{
    level: "info",
    msg: "Batch sent to 50 recipients",
    tx: "0x..."
  }]
});
// { stored: 1, id: "log_..." }

🛡️

Compliance & Audit

2 endpoints

GET x402 Audit Trail

Immutable, queryable payment audit logs for enterprise & grant reporting

/api/v1/audit/query

$0.005 USDC

▼

Parameters

wallet string — Wallet to audit
from string — Start date (ISO 8601)
to string — End date
format string — "json" | "csv" | "pdf"

Status: Coming Soon

Example

const report = await client.get(
  "/api/v1/audit/query", {
    wallet: "0xTreasury...",
    from: "2025-01-01",
    to: "2025-03-31",
    format: "csv"
  }
);
// Returns CSV of all batch payments
// with tx hashes, timestamps, amounts

POST x402 Tax

Per-request crypto tax calculation and reporting

/api/v1/tax/calculate

$0.01 USDC

▼

Parameters

wallet string — Wallet address
tax_year number — Tax year
jurisdiction string — "US" | "UK" | "EU"
method string — "fifo" | "lifo" | "hifo"

Status: Coming Soon

Example

const taxes = await client.post(
  "/api/v1/tax/calculate", {
    wallet: "0x...",
    tax_year: 2025,
    jurisdiction: "US",
    method: "fifo"
  }
);
// { gains: { short: "$420",
//   long: "$1200" }, events: 84 }

Connect via

🔧

MCP Server

57 tools for Claude Desktop, Cursor, Cline. Install from Smithery.

🤖

Coinbase AgentKit

Batch send action for any AgentKit-powered AI agent. PR #944.

⚡

Direct x402 Gateway

Hit endpoints directly with any x402 client. USDC on Base.

💻

SDKs & Libraries

TypeScript SDK, Solana SDK, Python CLI. Open source on GitHub.