Documentation

Copy a prompt and send it to your agent. It reads the skill file, learns the API, and starts calling tools. Compatible with Cursor, Claude, ChatGPT, LangChain, and any agent framework.

Three requests. That’s the entire integration.

curl https://gateway.example/v1/deposit-address

{
  "vault_address": "0x1a2b3c...f9e8"
}

curl "https://gateway.example/v1/tools/search?query=weather"

{
  "results": [{
    "id": "abc123",
    "name": "Weather API",
    "price": "0.05",
    "status": "active"
  }]
}

curl -X POST https://gateway.example/v1/proxy/abc123 \
  -H "X-Signature: 0x..." \
  -H "X-Timestamp: 1708300000000" \
  -d '{"city": "London"}'

{
  "gateway": {
    "cost": 0.05,
    "balance": 49.95,
    "request_id": "d4e5f6..."
  },
  "data": { "temp": 15, "unit": "celsius" }
}

Send USDC to the vault on Base L2. Your balance is credited within seconds. Then search for any tool and call it — the gateway handles billing, authentication to the supplier, and automatic refunds.

Every authenticated request requires two headers:

import { Wallet, keccak256, toUtf8Bytes } from 'ethers';

const wallet = new Wallet(PRIVATE_KEY);
const body = JSON.stringify({ city: 'London' });
const timestamp = Date.now().toString();
const message = timestamp + keccak256(toUtf8Bytes(body));
const signature = await wallet.signMessage(message);

const res = await fetch('https://gateway.example/v1/proxy/TOOL_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Timestamp': timestamp,
    'X-Signature': signature,
  },
  body,
});

No API keys. No OAuth. Your EVM wallet is your identity.

List all tools (no auth):

GET /v1/tools

Returns all active and degraded tools with name, description, price, and status.

Search tools (no auth):

GET /v1/tools/search?query=weather+forecast
GET /v1/tools/search?query=translate+text&mode=semantic
GET /v1/tools/search?query=I+need+to+resize+images+in+bulk&mode=agentic

Three search modes: keyword (default, free, ~10ms) uses full-text + tag matching. semantic (~200ms) uses embedding similarity for intent-based matching. agentic (~1-3s) uses an LLM to reason over the catalog.

Single tool (no auth):

GET /v1/tools/:toolId

Call any tool via the proxy endpoint:

POST /v1/proxy/:toolId
Headers: X-Signature, X-Timestamp, Content-Type: application/json
Body: { ...your request payload... }

The body is forwarded to the supplier as-is. The gateway deducts the cost, calls the supplier, and wraps the response.

{
  "gateway": {
    "cost": 0.05,
    "balance": 49.95,
    "request_id": "uuid",
    "payment_method": "balance",
    "pricing": { "model": "per_request" }
  },
  "data": { "...supplier response..." }
}

Poll GET /v1/transactions/:requestId to check async status.

Per-request (default) — A flat USDC amount per API call. The price field on the tool is the cost.

Per-unit — Price multiplied by units consumed (e.g., images processed, records returned). The gateway pre-authorizes unit_price × max_units, then partial-refunds the unused amount after the supplier reports actual units_consumed.

Per-unit tools include pricing_model: "per_unit", unit_name, and max_units_per_request in the tool listing. You only pay for what you use.

The gateway supports two payment methods. Both work through the same POST /v1/proxy/:toolId endpoint.

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

const account = privateKeyToAccount(PRIVATE_KEY);
const client = createWalletClient({
  account, chain: base, transport: http()
});

const x402Fetch = wrapFetch(fetch, client);

const res = await x402Fetch(
  'https://gateway.example/v1/proxy/TOOL_ID',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ city: 'London' }),
  }
);
const data = await res.json();

Tools that support x402 include x402_supported: true in their listing. Compatible with the @x402/fetch client library for automatic 402 handling.