API Documentation

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

Base URL https://x402-gateway-production.up.railway.app

Protocol x402 v2

Payment USDC on Base, USDC on Solana, or USDm on MegaETH

Free endpoints /health, /.well-known/x402.json, /api/discover, /api/services

Quick Start

Install the x402 client packages and viem:

bash

npm install @x402/fetch @x402/evm viem

Make your first paid call with TypeScript:

TypeScript

import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

// Create account from private key
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);

// Initialize x402 client and register EVM payment scheme
const client = new x402Client();
registerExactEvmScheme(client, {
  signer: account,
  networks: ["eip155:8453"], // Base mainnet
});

// Wrap native fetch — handles 402 negotiation automatically
const paidFetch = wrapFetchWithPayment(fetch, client, {
  paymentRequirementsSelector: (accepts) => accepts.find(a => a.network === "eip155:8453"),
});

// 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());
// { bitcoin: { usd: 97234, usd_24h_change: 2.31 } }

// 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());

How does payment work?

paidFetch calls the endpoint normally
Engine returns 402 with payment requirements in headers
The wrapper reads the requirements, signs a USDC/USDm permit or transfer
It retries the request with the payment in X-PAYMENT header
Engine verifies the payment, calls the upstream API, and returns data

Important: Use the Exact EVM Scheme for Base

Base payments must use the @x402/evm/exact/client scheme shown above. This produces a Permit2 signature payload that the Coinbase CDP facilitator verifies and settles. Sending a raw ERC-20 transfer tx hash will not work — the facilitator expects the v2 exact scheme payload, not a transaction hash.

The three critical lines: import { registerExactEvmScheme } from "@x402/evm/exact/client" → registerExactEvmScheme(client, { signer, networks: ["eip155:8453"] }) → wrapFetchWithPayment(fetch, client). MegaETH and Solana use different schemes — see Networks below.

💡 Test All Endpoints

Want to test all 61 endpoints at once? Download our comprehensive test suite:

curl -O https://x402-gateway-production.up.railway.app/test-all-endpoints.mjs
TEST_PRIVATE_KEY=0x... node test-all-endpoints.mjs

Includes proper parameters and examples for every endpoint category.

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 engine 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

{ "bitcoin": { "usd": 97234.12, "usd_24h_change": 2.31 } }

Supported Networks

Network	CAIP-2	Token	Decimals	Speed	Verification
Base	eip155:8453	USDC	6	~2s	Coinbase CDP facilitator
MegaETH	eip155:4326	USDm	18	~10ms	Direct on-chain
Solana	solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp	USDC	6	~400ms	Coinbase CDP facilitator

Amount conversion: $0.001 = 1000 USDC (6 decimals) = 1000000000000000 USDm (18 decimals)

Base Payment Notes

Recommended rail. Base uses Permit2 gasless signatures — the @x402/fetch + @x402/evm SDK handles everything automatically. No on-chain transfer needed from the payer, no nonce management, no gas fees.

Concurrency: Safe to send multiple Base payments in parallel — Permit2 signatures are off-chain and don't conflict.

Common errors:

insufficient_funds — wallet doesn't have enough USDC on Base. Each endpoint costs $0.001–$0.10 depending on the API.
Permit2 allowance — if using Permit2 for the first time, the SDK may need a one-time USDC approval to the Permit2 contract.

MegaETH Payment (~10ms confirmations)

MegaETH uses on-chain USDm transfers instead of Permit2 signatures. The official @x402/evm SDK doesn't support MegaETH natively, so you need a small custom scheme class. The complete, copy-pasteable example below plugs into @x402/fetch so paidFetch handles the 402 flow automatically — just like Base and Solana.

Install:

npm install @x402/fetch viem

Complete example:

import { wrapFetchWithPaymentFromConfig } from '@x402/fetch';
import { privateKeyToAccount } from 'viem/accounts';
import { createWalletClient, createPublicClient, http,
         getAddress, parseGwei } from 'viem';

// ── MegaETH chain definition ────────────────────────────
const megaethChain = {
  id: 4326,
  name: 'MegaETH',
  nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
  rpcUrls: { default: { http: ['https://mainnet.megaeth.com/rpc'] } },
};

const erc20TransferAbi = [{
  type: 'function', name: 'transfer',
  stateMutability: 'nonpayable',
  inputs: [
    { name: 'to', type: 'address' },
    { name: 'value', type: 'uint256' },
  ],
  outputs: [{ name: '', type: 'bool' }],
}];

// ── Custom x402 scheme for MegaETH ─────────────────────
// Sends a USDm ERC-20 transfer and returns the txHash.
// Plugs into wrapFetchWithPaymentFromConfig so the 402
// negotiate-pay-retry flow is fully automatic.
class MegaethScheme {
  constructor(walletClient, publicClient) {
    this.scheme = 'exact';
    this.wc = walletClient;
    this.pc = publicClient;
    this.nonce = null;
    this.queue = Promise.resolve();
  }

  createPaymentPayload(x402Version, req) {
    // Serialize calls to avoid nonce races
    const run = async () => {
      const to = getAddress(req.payTo);
      const token = getAddress(req.asset);
      const value = BigInt(req.amount);

      // Fetch nonce once, then track locally
      if (this.nonce === null)
        this.nonce = await this.pc.getTransactionCount({
          address: this.wc.account.address,
        });

      try {
        const txHash = await this.wc.writeContract({
          address: token,
          abi: erc20TransferAbi,
          functionName: 'transfer',
          args: [to, value],
          nonce: this.nonce,
          maxFeePerGas: parseGwei('0.001'),  // stable on MegaETH
          maxPriorityFeePerGas: 0n,
          gas: 200_000n,
          chain: megaethChain,
          account: this.wc.account,
        });

        await this.pc.waitForTransactionReceipt({
          hash: txHash, timeout: 5000,
        });
        this.nonce++;
        return { x402Version, payload: { txHash } };
      } catch (e) {
        this.nonce = null; // re-fetch on next call
        throw e;
      }
    };
    const p = this.queue.then(run);
    this.queue = p.catch(() => {});
    return p;
  }
}

// ── Setup ───────────────────────────────────────────────
const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const transport = http('https://mainnet.megaeth.com/rpc');

const scheme = new MegaethScheme(
  createWalletClient({ account, chain: megaethChain, transport }),
  createPublicClient({ chain: megaethChain, transport }),
);

const paidFetch = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:4326', client: scheme }],
});

// ── Use like normal fetch ────────────────────────────────
const BASE = 'https://x402-gateway-production.up.railway.app';

const res = await paidFetch(
  `${BASE}/api/crypto/price?ids=bitcoin`
);
console.log(await res.json());
// { bitcoin: { usd: 97234.12, ... } }

Key details:

USDm token: 0xFAfDdbb3FC7688494971a79cc65DCa3EF82079E7 (18 decimals, not 6)
Amount math: $0.001 = 1000000000000000 (10^15). The 402 response accepts.amount is already in raw units.
Gas: Base fee is stable at 0.001 gwei. Use maxFeePerGas: parseGwei('0.001') and gas: 200_000n.
Nonce: The scheme tracks nonces locally to avoid stale getTransactionCount from RPC caching. The queue serializes calls to prevent races.
Wallet needs: USDm for payments + a tiny amount of ETH for gas (~0.0001 ETH covers thousands of calls).

Common errors:

Transaction reverted — insufficient USDm balance or wrong token address.
nonce too low — concurrent calls without the queue serialization. Use the scheme class above which handles this.
Transaction already used — replay protection. Each txHash can only be used once.

Solana Payment Notes

Solana payments use the @x402/svm SDK with the Coinbase CDP facilitator. The SDK handles transaction construction automatically, but there are important considerations for reliability:

SDK version: Use @x402/[email protected]. Version 2.3.0 adds a Memo instruction that the CDP facilitator does not yet support, causing all payments to be rejected.

Wallet requirements: Your Solana wallet needs two things: USDC (SPL token) to cover the accepts.amount from the 402 response, and a small amount of SOL for transaction fees (~0.000005 SOL per payment). If either is missing, you'll get confusing "payment required" loops where the code looks correct but the transaction silently fails simulation.

Example (@x402/fetch + @x402/svm):

import { x402Client, wrapFetchWithPayment } from '@x402/fetch';
import { ExactSvmScheme } from '@x402/svm';      // v2.2.0
import { createKeyPairSignerFromBytes } from '@solana/kit';

const signer = await createKeyPairSignerFromBytes(keypairBytes);
const scheme = new ExactSvmScheme(signer);

const client = new x402Client().register('solana:*', scheme);
const paidFetch = wrapFetchWithPayment(fetch, client);

// Use paidFetch like normal fetch — payment is automatic
const res = await paidFetch('https://x402engine.app/api/crypto/price?ids=bitcoin');
console.log(await res.json());

Rate limiting: The Solana public RPC (api.mainnet-beta.solana.com) has a strict rate limit (~10 req/s). If you're making many payments, consider using a dedicated RPC endpoint (Helius, Alchemy, QuickNode) with higher limits.

Common errors:

transaction_simulation_failed: Custom:1 — Insufficient USDC balance. Check wallet balance before creating the payment.
No matching payment requirements — feePayer mismatch between client and server. Use @x402/[email protected] and ensure the feePayer from the 402 response is used.

Discovery

Agents can discover available services and payment options programmatically.

GET /.well-known/x402.json Free

Full discovery document — services, networks, payment routes, categories.

GET /api/services Free

List all services with IDs, descriptions, pricing, and endpoints.

GET /api/services/:id Free

Service details including payment options. Example: /api/services/crypto-price

MCP Server

Model Context Protocol (MCP) gives AI agents a standard way to discover and call tools. For x402engine, MCP matters because agents can plug in once, then browse and use paid x402 services without custom integration code per client.

Install x402 MCP server

Server repo: github.com/agentc22/x402engine-mcp

claude mcp add x402 -- npx -y x402engine-mcp

Use this same command pattern in Claude Code, Claude Desktop, and OpenClaw.

Add x402 to popular MCP clients

Tool	Command / Pattern
Claude Code	`claude mcp add x402 -- npx -y x402engine-mcp`
Claude Desktop	`claude mcp add x402 -- npx -y x402engine-mcp`
OpenClaw	`claude mcp add x402 -- npx -y x402engine-mcp`
OpenAI Codex	`claude mcp add x402 -- npx -y x402engine-mcp`
Cursor	Add an MCP server named `x402` that runs `npx -y x402engine-mcp`.
Cline	Use the same server process pattern: `npx -y x402engine-mcp` under MCP settings.
Continue	Register MCP server `x402` with command `npx -y x402engine-mcp`.
Windsurf	Add MCP server entry using `npx -y x402engine-mcp`.
Goose	Use the same MCP server command pattern with server name `x402`.

Verify connection

claude mcp get x402

If the server is connected, your agent can immediately discover all x402engine services from the discovery endpoint:

https://x402engine.app/.well-known/x402.json

Crypto & Blockchain

GET /api/crypto/price $0.001

Real-time cryptocurrency prices in any fiat currency.

Parameters

Name	Type	Description
ids required	string	Comma-separated CoinGecko IDs, e.g. `bitcoin,ethereum`
currencies optional	string	Comma-separated fiat codes. Default: `usd`
include_24h optional	string	`true` or `false`. Default: `true`
include_mcap optional	string	`true` or `false`. Default: `false`

Example Response

{
  "bitcoin": { "usd": 97234.12, "usd_24h_change": 2.31 },
  "ethereum": { "usd": 3456.78, "usd_24h_change": -0.45 }
}

GET /api/crypto/markets $0.002

Market rankings with price, volume, and market cap.

Parameters

Name	Type	Description
currency optional	string	Fiat currency. Default: `usd`
category optional	string	Filter by CoinGecko category
order optional	string	Sort order. Default: `market_cap_desc`
limit optional	number	Results per page, max 250. Default: `100`
page optional	number	Page number. Default: `1`

Example Response

[
  { "id": "bitcoin", "symbol": "btc", "name": "Bitcoin",
    "current_price": 97234, "market_cap": 1920000000000, ... }
]

GET /api/crypto/history $0.003

Historical price, market cap, and volume data.

Parameters

Name	Type	Description
id required	string	CoinGecko coin ID, e.g. `bitcoin`
currency optional	string	Default: `usd`
days optional	string	Days of history or `"max"`. Default: `30`
interval optional	string	Data interval, e.g. `daily`

Example Response

{
  "prices": [[1706745600000, 43012.5], [1706832000000, 43150.2], ...],
  "market_caps": [...],
  "total_volumes": [...]
}

GET /api/crypto/trending $0.001

Currently trending coins on CoinGecko. No parameters required.

Example Response

{
  "coins": [
    { "item": { "id": "pepe", "name": "Pepe", "symbol": "PEPE", "market_cap_rank": 24, ... } }
  ]
}

GET /api/crypto/search $0.001

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

Parameters

Name	Type	Description
q required	string	Search query, e.g. `btc`

Example Response

{
  "coins": [
    { "id": "bitcoin", "name": "Bitcoin", "symbol": "BTC", "market_cap_rank": 1 }
  ]
}

POST /api/wallet/balances $0.005

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

Request Body

Field	Type	Description
chain required	string	Chain name: `ethereum`, `base`, `solana`, etc.
address required	string	Wallet address

Example

Request

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

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

Response

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

POST /api/wallet/transactions $0.005

Transaction history with asset transfers and labels.

Request Body

Field	Type	Description
chain required	string	Chain name
address required	string	Wallet address

POST /api/wallet/transactions
{ "chain": "base", "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" }

// Response
{
  "transactions": [
    {
      "hash": "0xabc...",
      "block_number": 12345678,
      "timestamp": "2025-01-15T12:00:00Z",
      "from": "0xd8dA...",
      "to": "0x833...",
      "value": "0",
      "asset_transfers": [
        { "token": "USDC", "amount": "100.00", "direction": "out" }
      ]
    }
  ]
}

POST /api/wallet/pnl $0.01

Realized and unrealized profit & loss per token for any wallet. Powered by Allium.

Request Body

Field	Type	Description
chain required	string	Chain name: `ethereum`, `base`, `solana`, etc.
address required	string	Wallet address

Example

Request

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

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

Response

{
  "items": [{
    "chain": "base",
    "address": "0xa9c4...",
    "tokens": [{
      "token_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "average_cost": { "currency": "USD", "amount": "1.0001" },
      "current_price": { "currency": "USD", "amount": "1.0002" },
      "current_balance": { "currency": "USD", "amount": "1.42" },
      "realized_pnl": { "currency": "USD", "amount": "0.05" },
      "unrealized_pnl": { "currency": "USD", "amount": "0.001" }
    }],
    "total_balance": { "currency": "USD", "amount": "1.42" },
    "total_realized_pnl": { "currency": "USD", "amount": "0.05" },
    "total_unrealized_pnl": { "currency": "USD", "amount": "0.001" }
  }]
}

POST /api/token/prices $0.005

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

Request Body

Field	Type	Description
tokens required	array	Array of `{ token_address, chain }` objects. Max 200.

Example

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

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

Response

[
  {
    "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "chain": "base",
    "price_usd": 1.0001,
    "price_change_24h": 0.01,
    "volume_24h": 12345678.90
  }
]

GET /api/token/metadata $0.002

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

Parameters (at least one required)

Name	Type	Description
chain	string	Chain name
address	string	Token contract address
slug	string	Token slug
id	string	Token ID

Example

GET /api/token/metadata?chain=ethereum&address=0xdac17f958d2ee523a2206206994597c13d831ec7

Response

{
  "name": "Tether USD",
  "symbol": "USDT",
  "decimals": 6,
  "chain": "ethereum",
  "token_address": "0xdac17f958d2ee523a2206206994597c13d831ec7"
}

GET

/api/ens/resolve

$0.001

Resolve an ENS name to an Ethereum address. Uses public Ethereum RPCs — no API key needed.

Param	Type	Description
name required	string	ENS name (e.g. "vitalik.eth")

GET /api/ens/resolve?name=vitalik.eth

// Response
{
  "name": "vitalik.eth",
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

GET

/api/ens/reverse

$0.001

Reverse lookup — find the ENS name for an Ethereum address. Returns null if no reverse record is set.

Param	Type	Description
address required	string	Ethereum address (0x...)

GET /api/ens/reverse?address=0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

// Response
{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "name": "vitalik.eth"
}

Compute

POST /api/image/fast $0.015

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

Request Body

Field	Type	Description
prompt required	string	Image description
width optional	number	256–2048 pixels. Default: `1024`
height optional	number	256–2048 pixels. Default: `1024`
seed optional	number	For reproducible results

Example

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

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

Response (200 OK)

{
  "images": [
    {
      "url": "https://v3.fal.media/files/abc123/output.png",  // ← download this URL
      "width": 1024,
      "height": 1024
    }
  ],
  "seed": 42,
  "model": "fal-ai/flux/schnell",
  "inference_time_ms": 1850
}

Image URL is at images[0].url. All 3 image endpoints return the same response shape.

POST /api/image/quality $0.05

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

Same parameters as /api/image/fast.

POST /api/image/text $0.12

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

Same parameters as /api/image/fast.

POST /api/image/face-swap $0.08

Identity-preserving face swap using FLUX PuLID. Best for portraits, stylized edits, and marketing mockups where the reference face needs to stay recognizable.

Request Body

Field	Type	Description
prompt required	string	Describe the final image after the face swap
reference_image_url required	string	Public image URL containing the face to preserve
width optional	number	256–2048 pixels. Default: `1024`
height optional	number	256–2048 pixels. Default: `1024`
negative_prompt optional	string	Artifacts to avoid, such as blur or warped features
id_weight optional	number	How strongly to preserve the reference identity. Example: `1.2`

Example

POST /api/image/face-swap
Content-Type: application/json

{
  "prompt": "a fashion editorial portrait with soft cinematic lighting",
  "reference_image_url": "https://images.unsplash.com/photo-1494790108377-be9c29b29330?w=1024",
  "width": 768,
  "height": 1024,
  "id_weight": 1.2
}

Response (200 OK)

{
  "images": [
    {
      "url": "https://v3.fal.media/files/abc123/faceswap.png",
      "width": 768,
      "height": 1024
    }
  ],
  "seed": 7,
  "model": "fal-ai/flux-pulid",
  "inference_time_ms": 4210
}

Same response shape as the other image endpoints. The generated image is at images[0].url.

POST /api/code/run $0.005

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

Request Body

Field	Type	Description
code required	string	Code to execute (max 100KB)
language optional	string	`python`, `javascript`, `bash`, `r`. Default: `python`
timeout optional	number	1–300 seconds
files optional	object	Additional files for the sandbox, keyed by filename

Example

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

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

Response

{
  "success": true,
  "exit_code": 0,
  "stdout": "Pi to 10 decimals: 3.1415926536\n",
  "stderr": ""
}

POST /api/transcribe $0.10

Audio transcription with speaker identification using Deepgram Nova-3.

Request Body

Field	Type	Description
audio_url required*	string	URL to audio file
audio_base64 required*	string	Base64-encoded audio (max 50MB)
audio_mimetype optional	string	Required with base64, e.g. `audio/mp3`
language optional	string	Language code. Default: `en`
diarize optional	boolean	Speaker identification. Default: `true`
model optional	string	`nova-3` or `whisper-large`

* Provide either audio_url or audio_base64, not both.

Example Response

{
  "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"
}

Storage

POST /api/ipfs/pin $0.01

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

Request Options

Option 1: File upload

Send as multipart/form-data with a file field. Max 100MB.

Option 2: JSON data

Send { "json": { ... }, "name": "optional-name" } as JSON body.

Option 3: Pin from URL

Send { "url": "https://...", "name": "optional-name" } as JSON body.

Example

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

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

Response

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

GET /api/ipfs/get $0.001

Fetch files from IPFS by CID via Pinata gateway.

Parameters

Name	Type	Description
cid required	string	IPFS Content Identifier

Example

GET /api/ipfs/get?cid=bafkreihdwdcefgh4dqkjv67uzcmw7ojee6xedzdetojuzjevtensgqas7y

Response (JSON content)

// Returns the stored JSON object directly
{ "name": "Test", "value": 42 }

For JSON content: returns the stored object as-is. For binary content (images, files): streams the raw bytes with appropriate Content-Type header.

LLM & AI

POST

/api/llm/{model}

Chat completion via 38 models from OpenAI, Anthropic, Google, DeepSeek, Meta, xAI, Qwen, Mistral, Perplexity, Moonshot, MiniMax, Zhipu, and ByteDance. All models use the same request/response format.

Field	Type	Description
messages required	array	Array of {role, content} objects
max_tokens optional	number	Max tokens (1-4096, default 1024)

POST /api/llm/claude-sonnet
{
  "messages": [{"role": "user", "content": "Explain x402 in one sentence"}],
  "max_tokens": 100
}

// Response
{
  "content": "x402 is a protocol that enables...",
  "model": "anthropic/claude-sonnet-4.5",
  "usage": {"prompt_tokens": 12, "completion_tokens": 24, "total_tokens": 36}
}

Available Models

Endpoint	Model	Price
/api/llm/gpt-4o	GPT-4o	$0.04
/api/llm/gpt-4o-mini	GPT-4o Mini	$0.003
/api/llm/gpt-4.1	GPT-4.1	$0.03
/api/llm/gpt-4.1-mini	GPT-4.1 Mini	$0.006
/api/llm/gpt-5	GPT-5	$0.035
/api/llm/gpt-5-mini	GPT-5 Mini	$0.007
/api/llm/o3	o3 (reasoning)	$0.03
/api/llm/o4-mini	o4 Mini (reasoning)	$0.02
/api/llm/claude-opus	Claude Opus 4.6	$0.09
/api/llm/claude-sonnet	Claude Sonnet 4.5	$0.06
/api/llm/claude-haiku	Claude Haiku 4.5	$0.02
/api/llm/gemini-pro	Gemini 2.5 Pro	$0.035
/api/llm/gemini-flash	Gemini 2.5 Flash	$0.009
/api/llm/deepseek	DeepSeek V3	$0.005
/api/llm/deepseek-r1	DeepSeek R1 (reasoning)	$0.01
/api/llm/llama	Llama 3.3 70B	$0.002
/api/llm/grok	Grok 4	$0.06
/api/llm/qwen	Qwen3 235B	$0.004
/api/llm/mistral	Mistral Large 3	$0.006
/api/llm/perplexity	Perplexity Sonar Pro (search)	$0.06
/api/llm/gpt-5.2	GPT-5.2	$0.08
/api/llm/gpt-5.2-codex	GPT-5.2 Codex (reasoning)	$0.06
/api/llm/kimi	Kimi K2.5	$0.03
/api/llm/minimax	MiniMax M2.5	$0.01
/api/llm/glm	GLM-5	$0.03
/api/llm/grok-code	Grok Code Fast	$0.04
/api/llm/seed	Seed 1.6	$0.02
/api/llm/devstral	Devstral 2	$0.02
/api/llm/gpt-5.4	GPT-5.4	$0.10
/api/llm/gpt-5.4-pro	GPT-5.4 Pro (reasoning)	$0.30
/api/llm/gpt-5.3-codex	GPT-5.3 Codex (reasoning)	$0.08
/api/llm/claude-opus-4.5	Claude Opus 4.5	$0.09
/api/llm/gemini-3.1-pro	Gemini 3.1 Pro (reasoning)	$0.05
/api/llm/gemini-3.1-flash-lite	Gemini 3.1 Flash Lite	$0.003
/api/llm/qwen3.5	Qwen 3.5	$0.006
/api/llm/deepseek-v3.2-speciale	DeepSeek V3.2 Speciale (reasoning)	$0.008

POST

/api/embeddings

$0.001

Generate text embeddings using OpenAI text-embedding-3-small (1536 dimensions). Useful for semantic search, clustering, and RAG.

Field	Type	Description
text option 1	string	Single text to embed
texts option 2	string[]	Array of texts (1-100)

POST /api/embeddings
{ "text": "What is x402?" }

// Response (single)
{ "embedding": [0.012, -0.034, ...] }  // 1536 dimensions

POST /api/embeddings
{ "texts": ["What is x402?", "How do payments work?"] }

// Response (batch)
{ "embeddings": [[0.012, ...], [-0.005, ...]] }

Web

GET

/api/web/scrape

$0.005

Scrape any URL and get clean markdown content. Powered by Firecrawl.

Param	Type	Description
url required	string	URL to scrape
formats optional	string	Comma-separated: markdown, html, text (default: markdown)

GET /api/web/scrape?url=https://example.com

// Response
{
  "content": "# Example Domain\n\nThis domain is for use in...",
  "markdown": "# Example Domain\n\nThis domain is for use in...",
  "metadata": { "title": "Example Domain", "statusCode": 200 }
}

GET

/api/web/screenshot

$0.01

Capture a screenshot of any URL. Returns a base64-encoded image.

Param	Type	Description
url required	string	URL to screenshot
full_page optional	boolean	Capture full page (default: false)

GET /api/web/screenshot?url=https://example.com&full_page=true

// Response
{
  "screenshot": "iVBORw0KGgoAAAANSUhEUgAA...",  // base64 PNG
  "metadata": { "title": "Example Domain", "statusCode": 200 }
}

POST

/api/search/web

$0.01

Neural web search powered by Exa. Returns titles, URLs, and highlighted snippets.

Field	Type	Description
query required	string	Search query
numResults optional	number	Number of results, 1-30 (default: 10)
includeDomains optional	string[]	Only include results from these domains
category optional	string	Filter: news, research paper, company, tweet, github, pdf
includeText optional	boolean	Include full page text in results (default: false)

POST /api/search/web
{ "query": "latest ethereum news", "numResults": 5, "category": "news" }

// Response
{
  "results": [
    {
      "title": "Ethereum Hits New All-Time High...",
      "url": "https://example.com/article",
      "publishedDate": "2026-02-20",
      "highlights": ["Ethereum surged past $5,000..."]
    }
  ],
  "autopromptString": "latest ethereum news and updates"
}

POST

/api/search/contents

$0.005

Fetch full text content from up to 10 URLs at once. Powered by Exa.

Field	Type	Description
urls required	string[]	Array of URLs to fetch content from (max 10)

POST /api/search/contents
{ "urls": ["https://example.com/article"] }

// Response
{
  "contents": [
    {
      "title": "Example Article",
      "url": "https://example.com/article",
      "text": "Full article text content..."
    }
  ]
}

Text-to-Speech

POST

/api/tts/openai

$0.01

Convert text to speech using OpenAI TTS. Returns base64-encoded audio.

Field	Type	Description
text required	string	Text to speak (max 4096 chars)
voice optional	string	alloy, echo, fable, onyx, nova, shimmer (default: alloy)
model optional	string	tts-1 or tts-1-hd (default: tts-1)
format optional	string	mp3, opus, aac, flac, wav, pcm (default: mp3)

POST /api/tts/openai
{ "text": "Hello, I am an AI agent.", "voice": "nova", "model": "tts-1-hd" }

// Response
{
  "audio": "//uQxAAAAAANIAAAAAExB...",  // base64 audio
  "format": "mp3",
  "model": "tts-1-hd"
}

POST

/api/tts/elevenlabs

$0.02

Premium text-to-speech with ElevenLabs. Ultra-realistic voices with multilingual support.

Field	Type	Description
text required	string	Text to speak (max 5000 chars)
voice_id optional	string	ElevenLabs voice ID (default: Rachel)
model_id optional	string	Model ID (default: eleven_multilingual_v2)
format optional	string	mp3_44100_128, pcm_16000, etc. (default: mp3_44100_128)

POST /api/tts/elevenlabs
{ "text": "Welcome to x402engine.", "voice_id": "21m00Tcm4TlvDq8ikWAM" }

// Response
{
  "audio": "//uQxAAAAAANIAAAAAExB...",  // base64 audio
  "format": "mp3_44100_128"
}

POST

/api/tx/simulate

$0.01

Simulate EVM transactions before sending. Get gas estimates, execution traces, and revert reasons via Tenderly.

Field	Type	Description
network_id required	string	Chain ID (e.g. "1" for mainnet, "8453" for Base)
from required	string	Sender address (0x...)
to required	string	Recipient/contract address (0x...)
value optional	string	ETH value in wei
data optional	string	Calldata hex (0x...)
gas optional	number	Gas limit override

POST /api/tx/simulate
{
  "network_id": "1",
  "from": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "to": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
  "data": "0xa9059cbb000000000000000000000000..."
}

// Response
{
  "success": true,
  "gasUsed": 51234,
  "logs": [...],
  "trace": { "type": "CALL", "from": "0x...", "to": "0x...", ... }
}

GET

/api/travel/flights

$0.02

Search flights via Google Flights (SerpApi). Returns best flights, alternative options, and price insights.

Param	Type	Description
origin required	string	Departure airport IATA code (e.g. JFK)
destination required	string	Arrival airport IATA code (e.g. LAX)
departureDate required	string	Departure date (YYYY-MM-DD)
returnDate optional	string	Return date for round trips (YYYY-MM-DD)
adults optional	string	Number of adult passengers (default: 1)
travelClass optional	string	1=Economy, 2=Premium, 3=Business, 4=First
stops optional	string	0=Nonstop, 1=Up to 1 stop, 2=Up to 2 stops
maxPrice optional	string	Maximum price filter
currency optional	string	Currency code (default: USD)

GET /api/travel/flights?origin=JFK&destination=LAX&departureDate=2026-04-15

// Response
{
  "best_flights": [
    {
      "flights": [{
        "airline": "JetBlue",
        "flight_number": "B6 223",
        "departure_airport": { "name": "JFK", "time": "2026-04-15 12:29" },
        "arrival_airport": { "name": "LAX", "time": "2026-04-15 15:37" },
        "duration": 368,
        "travel_class": "Economy"
      }],
      "total_duration": 368,
      "price": 124
    }
  ],
  "other_flights": [...],
  "price_insights": {
    "lowest_price": 100,
    "price_level": "low",
    "typical_price_range": [115, 235]
  }
}

GET

/api/travel/hotels

$0.02

Search hotels via Google Hotels (SerpApi). Returns properties with prices, ratings, and amenities.

Param	Type	Description
q required	string	Search query — city or hotel name (e.g. "hotels in Paris")
checkInDate required	string	Check-in date (YYYY-MM-DD)
checkOutDate required	string	Check-out date (YYYY-MM-DD)
adults optional	string	Number of adults (default: 2)
sortBy optional	string	3=Lowest price, 8=Highest rating, 13=Most reviewed
minPrice optional	string	Minimum price per night
maxPrice optional	string	Maximum price per night
hotelClass optional	string	Star rating (2-5)
currency optional	string	Currency code (default: USD)

GET /api/travel/hotels?q=hotels+in+Paris&checkInDate=2026-04-15&checkOutDate=2026-04-18

// Response
{
  "properties": [
    {
      "name": "Villa Panthéon",
      "overall_rating": 4.3,
      "rate_per_night": { "lowest": "$224" },
      "hotel_class": "4-star hotel",
      "amenities": ["Free Wi-Fi", "Restaurant", "Bar"],
      "images": [{ "thumbnail": "https://..." }]
    }
  ],
  "brands": [...]
}

Error Handling

All errors return JSON with an error field.

Status	Meaning
400	Missing or invalid parameters
402	Payment required — check `PAYMENT-REQUIRED` header
404	Resource not found
408	Execution timeout (code execution)
500	Internal server error
503	Upstream temporarily unavailable (retryable)

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