# 0mod API Gateway — Agent Guide

> Machine-to-machine, payment-gated microservices for autonomous agents.
> Base (`eip155:8453`) · settled in USDC · HTTP 402 via the x402 protocol.
> Service version: `2.0.0`.

Primary listing category **Data** (331 x402 listings), plus **AI**, **Finance**, **Blockchain** and **Trading**. No API key — pay per call in USDC on Base via x402.

This gateway exposes **10 SKUs**: Data/AI utilities (web scraping, PII redaction,
RDAP lookup, DEX pricing, image OCR) and CEX-DEX **market-microstructure
telemetry** (spread candles, dislocations, execution latency, pre-trade impact
simulation). Every surface below is derived from one source of truth so the SKU
list can never drift.

## ⚠️ Prices are authoritative and DYNAMIC — do not hardcode them

Every SKU is priced in USDC and the price is **dynamic**. The single,
authoritative source is:

- **`GET /api/v1/discovery`** → `endpoints[].pricing` (`atomicUnits` + `readableUsdc`)

**Never hardcode a price** copied from documentation, an example, or a previous
run. Always read the current price from `/api/v1/discovery` — or, at
settlement time, directly from the base64 `PAYMENT-REQUIRED` header of the 402
challenge (that header is what you are actually charged).
The endpoint table below intentionally lists **no prices** for this reason.

## Machine-readable discovery

| Surface | URL |
| :--- | :--- |
| Discovery (authoritative prices) | `https://api.0mod.com/api/v1/discovery` |
| Agent manifest (agent-json) | `https://api.0mod.com/.well-known/agent.json` |
| Agents spec (OpenAI-style) | `https://api.0mod.com/agents.json` |
| A2A agent card | `https://api.0mod.com/.well-known/agent-card.json` |
| MCP server card | `https://api.0mod.com/.well-known/mcp.json` |
| Agent skill doc | `https://api.0mod.com/skill.md` |
| OpenAPI 3.1 | `https://api.0mod.com/openapi.json` |
| Payment walkthrough (repo) | `https://github.com/zeromodern/x402-api/blob/main/docs/payments.md` |
| LLM index | `https://api.0mod.com/llms.txt` |

## When to use (decision guide)

- **Web & content ingestion** — Use when you must read a live web page, or shrink a public image into a token-cheap context window before an LLM call.
  SKUs: `/api/v1/stealth-dom`, `/api/v1/image-ocr-shrink`
- **Privacy, lookup & market utilities** — Use when you must redact PII/PCI before sending text to a model, check a domain, or pull real-time DEX pricing.
  SKUs: `/api/v1/airgap-scrub`, `/api/v1/domain-check`, `/api/v1/dex-price-summary`
- **Crypto market-microstructure telemetry** — Use when you need CEX-DEX spread/basis telemetry, arbitrage dislocation events, fill-latency benchmarks, or a pre-trade impact simulation. Query `/api/v1/crypto/coverage` (free) first to confirm the pair/date window.
  SKUs: `/api/v1/crypto/coverage`, `/api/v1/crypto/spread-candles`, `/api/v1/crypto/dislocations`, `/api/v1/crypto/execution-latency`, `/api/v1/crypto/impact-simulation`

## Example outputs & schemas

- Full request/response examples for **every** SKU (the exact 200 body) are in
  `https://api.0mod.com/api/v1/discovery` at `endpoints[].examples`.
- Formal input schemas + per-operation examples live in
  `https://api.0mod.com/openapi.json`.
- The same examples are mirrored on `https://api.0mod.com/.well-known/agent.json`
  and `https://api.0mod.com/.well-known/agent-card.json` (`examples` per tool/skill).

## Endpoints

| Method | Path | Categories | Description |
| :--- | :--- | :--- | :--- |
| `POST` | `/api/v1/stealth-dom` | Data | Stealth DOM — headless edge web scraper for AI agents. Fetches any public URL and returns raw HTML or clean Markdown (up to 10,000 chars); SSRF-validated, runs at the Cloudflare edge in ~70ms, no API key.
| `POST` | `/api/v1/airgap-scrub` | Data, AI | Airgap Scrub — pre-LLM PII/PCI redaction for AI agents. Scrubs SSNs, credit cards, phones, addresses, emails and ZIPs before text reaches an LLM or log sink; stateless with zero data retention, optional Workers AI deep redaction, no API key.
| `POST` | `/api/v1/domain-check` | Data | Domain Check — global RDAP/WHOIS lookup for AI agents. Resolves availability, status, registrar, registration/expiry dates and nameservers for .com, .net, .org and global TLDs from the Cloudflare edge; no API key.
| `POST` | `/api/v1/dex-price-summary` | Data, Finance, Trading | DEX Price Summary — real-time DEX market data for AI agents. Returns token price, 24h volume, liquidity and top pair stats across chains (DexScreener) for trading bots and research agents; no API key.
| `POST` | `/api/v1/image-ocr-shrink` | Data, AI | Image OCR Shrink — vision OCR-to-markdown for AI agents. Extracts clean text and table markdown from public image URLs with Workers AI Vision Llama 3.2, saving ~95% of the tokens a raw image would consume; no API key.
| `GET` | `/api/v1/crypto/coverage` | Data, Finance, Blockchain, Trading | Crypto Coverage — free CEX-DEX telemetry discovery for AI agents. Returns supported pairs, earliest/latest timestamps, slice interval and the full telemetry endpoint map; no API key, no payment — use it to plan your query window.
| `GET` | `/api/v1/crypto/spread-candles` | Data, Finance, Blockchain, Trading | Spread Candles — cross-venue CEX-DEX spread OHLC for AI agents. Returns 15-minute raw/net spread bps candles, average net spread, book depth and dislocation counts for pairs like AERO/USD, ETH/USD and cbBTC/USD on Base; historical R2 slices, no API key.
| `GET` | `/api/v1/crypto/dislocations` | Data, Finance, Blockchain, Trading | Dislocations — CEX-DEX arbitrage events for AI agents. Returns synchronized cross-venue dislocation events (Coinbase vs Aerodrome Base DEX) with buy/sell venue, prices, raw/net bps, estimated profit and liquidity depth; real-time-sliced, no API key.
| `GET` | `/api/v1/crypto/execution-latency` | Data, Finance, Trading | Execution Latency — cross-venue fill-speed benchmarks for AI agents. Returns p50/p90/p99/min/max latencies, fill rate and per-venue broadcast timings for Coinbase REST vs Aerodrome DEX; empirical execution-quality telemetry for routing decisions, no API key.
| `POST` | `/api/v1/crypto/impact-simulation` | Data, Finance, Trading | Impact Simulation — pre-trade slippage simulator for AI agents. Runs a read-only PAPER order against the LIVE L2 book and returns expected VWAP fill price, slippage in bps, fillable size and fill probability; no order is placed, no custody touched, no API key.

Free / ungated routes: `GET /api/v1/discovery`, `GET /health`,
`GET /api/v1/crypto/coverage`, `GET /agents.md`,
`GET /skill.md`, `GET /llms.txt`,
`GET /.well-known/mcp.json`.

## Paying a 402 (x402 flow)

1. **Probe (no payment header).** Send the real request. A paid route answers `402 Payment Required` with a base64 `PAYMENT-REQUIRED` header carrying the exact amount, asset, network and `payTo`.
2. **Read the price from the challenge.** Decode `PAYMENT-REQUIRED` (base64 → JSON) and read `accepts[0].amount` (atomic USDC, 6 decimals). Do NOT hardcode a price — this header is authoritative.
3. **Sign an EIP-3009 `transferWithAuthorization`** for that exact amount with the `EVM_PRIVATE_KEY` wallet, on Base (`eip155:8453`), for the advertised USDC asset.
4. **Retry with the signature** in the `PAYMENT-SIGNATURE` header. The facilitator verifies + settles, and the route returns `200 OK` with the result plus a `PAYMENT-RESPONSE` settlement header.

### Minimal client (`EVM_PRIVATE_KEY` + `@x402/fetch`)

```ts
// npm i @x402/fetch @x402/core @x402/evm viem
import { wrapFetchWithPayment } from '@x402/fetch';
import { x402Client } from '@x402/core/client';
import { registerExactEvmScheme } from '@x402/evm/exact/client';
import { privateKeyToAccount } from 'viem/accounts';

// 1) Load the paying wallet from the environment. NEVER commit this key.
const account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);

// 2) Build an x402 client and register the EVM "exact" scheme with the signer.
const client = new x402Client();
registerExactEvmScheme(client, { signer: account });

// 3) Wrap fetch. It now transparently handles 402 → sign → retry → 200.
const paidFetch = wrapFetchWithPayment(fetch, client);

const res = await paidFetch('https://api.0mod.com/api/v1/stealth-dom', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ url: 'https://example.com', format: 'markdown' }),
});
if (!res.ok) throw new Error(`paid call failed: ${res.status}`);
console.log(await res.json()); // 200 body — the PAID response
```

### The 402 challenge you will receive

Decoded from the base64 `PAYMENT-REQUIRED` response header:

```json
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://api.0mod.com/api/v1/stealth-dom",
    "description": "",
    "mimeType": ""
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "4000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x1AaD39958eCfc74e2C9de70B2d1376AD749A7501",
      "maxTimeoutSeconds": 300,
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }
  ]
}
```

A full worked example (real captured challenge + the retry that returns 200)
lives in the repository at [`docs/payments.md`](https://github.com/zeromodern/x402-api/blob/main/docs/payments.md) and is
mirrored in the repository README.

## Rules for consuming agents

- Read prices from `/api/v1/discovery` (or the 402 header) at call time — never cache them as constants.
- Only `200` responses are billable; `402`/`404`/`400`/`5xx` are not settled.
- A pre-flight guard returns `404` with `charged: "$0.00 USDC"` for out-of-range crypto date windows — you are not charged.
- Send `Content-Type: application/json` and the exact parameters listed in `/openapi.json`.