API Documentation

The x402 Gateway exposes 17 production APIs behind x402 micropayments. Every endpoint returns 402 Payment Required until a valid stablecoin payment is attached to the request.

Quick Start

Install the x402 client packages and viem:

npm install @x402/fetch viem

Make your first paid call with TypeScript:

import { wrapFetchWithPayment } from "@x402/fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

// Create a wallet with USDC on Base
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const wallet = createWalletClient({
  account,
  chain: base,
  transport: http(),
});

// Wrap native fetch — handles 402 negotiation automatically
const paidFetch = wrapFetchWithPayment(fetch, wallet);

// Call any endpoint — payment is transparent
const BASE = "https://x402-gateway-production.up.railway.app";

// GET endpoint
const price = await paidFetch(`${BASE}/api/crypto/price?ids=bitcoin`);
console.log(await price.json());
// { service: "crypto-price", data: { bitcoin: { usd: 97234 } } }

// POST endpoint
const balances = await paidFetch(`${BASE}/api/wallet/balances`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ chain: "base", address: "0x..." }),
});
console.log(await balances.json());

Payment Flow

If you're building a custom client (not using @x402/fetch), here's the raw HTTP flow:

Step 1: Initial request

GET /api/crypto/price?ids=bitcoin HTTP/1.1
Host: x402-gateway-production.up.railway.app

Step 2: 402 response

The gateway returns payment requirements as base64 JSON in the PAYMENT-REQUIRED header:

HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0cyI6Wy4uLl19
Content-Type: application/json

{
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "1000",
      "resource": "https://x402-gateway-.../api/crypto/price?ids=bitcoin",
      "payTo": "0x7dd5Be069f2d2eAd75eC7C3423B116fF043c2629",
      "extra": { ... }
    }
  ],
  "x402Version": 2
}

Step 3: Retry with payment

Sign a payment using the details from accepts and send it in the X-PAYMENT header:

GET /api/crypto/price?ids=bitcoin HTTP/1.1
Host: x402-gateway-production.up.railway.app
X-PAYMENT: <base64-encoded signed payment payload>

Step 4: Response with settlement

HTTP/1.1 200 OK
PAYMENT-RESPONSE: <base64 settlement receipt>
Content-Type: application/json

{
  "service": "crypto-price",
  "data": { "bitcoin": { "usd": 97234.12, "usd_24h_change": 2.31 } }
}

Supported Networks

Discovery

Agents can discover available services and payment options programmatically.

Real-time cryptocurrency prices in any fiat currency.

Parameters

Example Response

{
  "service": "crypto-price",
  "data": {
    "bitcoin": { "usd": 97234.12, "usd_24h_change": 2.31 },
    "ethereum": { "usd": 3456.78, "usd_24h_change": -0.45 }
  }
}

Market rankings with price, volume, and market cap.

Parameters

Example Response

{
  "service": "crypto-markets",
  "count": 100,
  "data": [
    { "id": "bitcoin", "symbol": "btc", "name": "Bitcoin",
      "current_price": 97234, "market_cap": 1920000000000, ... }
  ]
}

Historical price, market cap, and volume data.

Parameters

Example Response

{
  "service": "crypto-history",
  "data": {
    "prices": [[1706745600000, 43012.5], [1706832000000, 43150.2], ...],
    "market_caps": [...],
    "total_volumes": [...]
  }
}

Currently trending coins on CoinGecko. No parameters required.

Example Response

{
  "service": "crypto-trending",
  "data": {
    "coins": [
      { "item": { "id": "pepe", "name": "Pepe", "symbol": "PEPE", "market_cap_rank": 24, ... } }
    ]
  }
}

Search for coins by name or symbol to get CoinGecko IDs.

Parameters

Example Response

{
  "service": "crypto-search",
  "data": {
    "coins": [
      { "id": "bitcoin", "name": "Bitcoin", "symbol": "BTC", "market_cap_rank": 1 }
    ]
  }
}

Token balances for any wallet across 20+ chains. Powered by Allium.

Request Body

Example

POST /api/wallet/balances
Content-Type: application/json

{ "chain": "base", "address": "0x7dd5Be069f2d2eAd75eC7C3423B116fF043c2629" }

{
  "service": "wallet-balances",
  "data": {
    "balances": [
      { "token_symbol": "USDC", "balance": "164.23", "usd_value": 164.23, ... },
      { "token_symbol": "ETH", "balance": "0.05", "usd_value": 162.50, ... }
    ]
  }
}

Transaction history with asset transfers and labels.

Request Body

Portfolio profit/loss with realized and unrealized P&L per token.

Request Body

Real-time DEX-derived token prices with OHLC data. Up to 200 tokens per request.

Request Body

Example

POST /api/token/prices
Content-Type: application/json

{
  "tokens": [
    { "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chain": "base" }
  ]
}

Token/asset metadata — name, symbol, decimals, chain info.

Parameters (at least one required)

Quick image generation using FLUX Schnell (~2s). Good for drafts and iteration.

Request Body

Example

POST /api/image/fast
Content-Type: application/json

{ "prompt": "A cyberpunk cityscape at sunset, neon lights reflecting off rain-slicked streets" }

High-quality image generation using FLUX.2 Pro (~5s). Production-ready output.

Same parameters as /api/image/fast.

Image generation with accurate text rendering using Ideogram v3. Best for logos, signs, and typography.

Same parameters as /api/image/fast.

Run code in an isolated sandbox. Supports Python, JavaScript, Bash, and R.

Request Body

Example

POST /api/code/run
Content-Type: application/json

{
  "code": "import math\nprint(f'Pi to 10 decimals: {math.pi:.10f}')",
  "language": "python"
}

{
  "service": "code-run",
  "success": true,
  "data": {
    "exit_code": 0,
    "stdout": "Pi to 10 decimals: 3.1415926536\n",
    "stderr": ""
  }
}

Audio transcription with speaker identification using Deepgram Nova-3.

Request Body

* Provide either audio_url or audio_base64, not both.

Example Response

{
  "service": "transcribe",
  "data": {
    "text": "Hello, welcome to the meeting. Today we'll discuss...",
    "segments": [
      { "text": "Hello", "start": 0.0, "end": 0.5, "speaker": 0, "confidence": 0.98 }
    ],
    "speakers": [{ "id": 0, "segments_count": 12 }, { "id": 1, "segments_count": 8 }],
    "duration_seconds": 145.2,
    "language": "en",
    "model": "nova-3"
  }
}

Pin JSON, files, or URLs to IPFS for decentralized storage. Powered by Pinata.

Request Options

Example

POST /api/ipfs/pin
Content-Type: application/json

{ "json": { "name": "Test", "value": 42 }, "name": "my-data" }

{
  "service": "ipfs-pin",
  "data": {
    "cid": "bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtensgqas7y",
    "name": "my-data",
    "size": 28,
    "gateway_url": "https://gateway.pinata.cloud/ipfs/bafkrei..."
  }
}

Fetch files from IPFS by CID via Pinata gateway.

Parameters

Response

For JSON content: returns { service, cid, data }. For binary content: streams the raw file with appropriate Content-Type.

Error Handling

All errors return JSON with an error field.

{
  "error": "Missing required parameter: ids",
  "details": "Provide comma-separated CoinGecko coin IDs"
}