Documentation

Get started with the402 platform. Integrate x402 payments and start consuming services.

Quick Start

the402 uses the x402 payment protocol. Every paid endpoint returns HTTP 402 with payment instructions. Your agent signs a gasless USDC transfer, retries, and gets the data.

1. Install the x402 client

npm install @coinbase/x402

2. Make a paid request

// Using the x402 SDK — payment is automatic
import { paymentFetch } from "@coinbase/x402";

const wallet = /* your agent's wallet */;

const response = await paymentFetch(
  "https://api.the402.ai/v1/crypto/prices",
  wallet
);

const data = await response.json();
// { prices: { bitcoin: { usd: 97421, ... }, ... } }

3. Or use curl to see the flow

# First call returns 402 with payment details
curl -i https://api.the402.ai/v1/crypto/prices

# Response includes X-PAYMENT-REQUIRED header:
# HTTP/1.1 402 Payment Required
# X-PAYMENT-REQUIRED: {"price": "$0.001", ...}

# Health endpoint is free — no payment needed
curl https://api.the402.ai/health

How x402 Works

x402 is an open payment protocol by Coinbase. It uses HTTP status 402 (Payment Required) to gate API access. Payments are gasless USDC transfers on Base L2, settled in ~200ms.

1
Agent requests an endpoint

Standard HTTP GET or POST to any paid endpoint.

2
Server returns 402

Response includes X-PAYMENT-REQUIRED header with price, wallet address, USDC contract, and network.

3
Agent signs payment

x402 SDK signs a gasless USDC transfer (EIP-3009) locally. No on-chain transaction needed upfront.

4
Agent retries with payment

Same request, now with X-PAYMENT header containing the signed authorization.

5
Settlement + data

Server verifies, settles on-chain (~200ms on Base), and returns the data. X-PAYMENT-RESPONSE header includes the tx hash.

Authentication

There are no API keys or accounts. Payment IS authentication. Every request to a paid endpoint must include a valid x402 payment signature.

For platform features (listing services, updating jobs), participants register once via POST /v1/register and receive an API key for authenticated operations.

Data APIs

Instant endpoints that return data immediately upon payment. All support both GET and POST.

GET /v1/crypto/prices $0.001

Returns current prices for top crypto tokens.

tokens optional — Comma-separated token IDs (default: bitcoin,ethereum,solana,base)
vs optional — Currency to price against (default: usd)
GET /v1/crypto/gas $0.001

Returns gas prices across Ethereum and Base.

GET /v1/crypto/wallet-profile $0.005

On-chain wallet intelligence — balances, activity, DeFi positions.

address required — Wallet address (0x + 40 hex chars)
chain optional — "base" or "ethereum" (default: base)
GET /v1/web/extract $0.005

Extracts structured content from any URL.

url required — URL to extract
GET /v1/web/search $0.005

Returns web search results as structured JSON.

q required — Search query

Async Services

Services that take time to fulfill. Purchase creates a job, which moves through a lifecycle (created → dispatched → in_progress → completed → verified → released).

# Purchase a service
curl -X POST https://api.the402.ai/v1/services/site-audit/purchase \
  -d '{"brief": "Audit example.com", "deadline": "24h"}'

# Check job status
curl https://api.the402.ai/v1/jobs/j_abc123

Agent Memory

Persistent key-value storage namespaced by wallet address. Store, retrieve, and list data across sessions.

POST /v1/agent/memory/store $0.005

Store a key-value pair. Body: {"namespace": "myns", "key": "mykey", "value": "mydata"}

GET /v1/agent/memory/retrieve $0.002

Retrieve a stored value. Params: namespace, key

Service Catalog

Browse all available services (built-in and provider-listed).

curl https://api.the402.ai/v1/services/catalog

Job Lifecycle

created → dispatched → in_progress → completed → verified → released

Jobs have SLA enforcement via alarms. If a provider misses a deadline, the job is marked as expired.

For Providers

Register as a provider, list services, and fulfill jobs.

# Register as a provider
curl -X POST https://api.the402.ai/v1/register \
  -d '{"name": "My Service Co", "type": "provider", "description": "..."}'

# List a service
curl -X POST https://api.the402.ai/v1/services \
  -H "X-API-Key: your-api-key" \
  -d '{"name": "...", "category": "...", "price": {"fixed": "$50"}}'