# Project Zero — paid x402 API catalog

> Three USDC-per-call APIs served by an autonomous agent system over the x402 protocol (HTTP 402). No API key, no signup, no KYC: an unauthenticated call receives a standard x402 v2 `exact` Payment-Required challenge; sign it (EIP-3009) and the paid result returns, with on-chain settlement handled by a facilitator. Failed or invalid calls are never charged — settlement happens only after the handler returns success.

## Payment config (mirror of the live 402 challenge)

| Property | Value |
|---|---|
| Protocol | x402 v2, scheme `exact` |
| Network | `eip155:84532` (Base Sepolia (testnet)) |
| Asset | USDC `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
| Recipient (payTo) | `0x40560Fa6E0908932Ab8F7bf8B2AFA18533e044Cc` |
| Facilitator | https://facilitator.payai.network |
| Pricing | wallet-balance $0.001/call · quick-brief $0.01/call · research-brief $0.05/call |

The challenge served on any unpaid request is authoritative — if this table and the challenge ever disagree, trust the challenge.

## Paid endpoints (x402 per-call USDC)

### 1. Research Brief — $0.05/call
- Endpoint: POST https://preview-chat-985505b1-9dc0-470f-9fc3-3704d8b625e3.space-z.ai/api/x402/research-brief
- Input: JSON `{ "topic": "10-200 chars", "focus"?: "angle", "max_sources"?: 3-6 (default 4), "recency_days"?: 0|7|30|90|365 }`
- Does: live web search + reads 3-6 full sources + cited synthesis.
- Example success response:
```json
{ "ok": true, "topic": "...", "summary": "2-4 sentence synthesis",
  "key_findings": [{ "point": "...", "source_url": "https://...", "source_title": "...", "source_date": "2026-09-01" }],
  "sources": [{ "url": "https://...", "title": "...", "date": "2026-09-01", "retrieved_at": "..." }],
  "confidence": "high|medium|low", "caveats": "...", "generated_at": "...", "disclosure": "..." }
```

### 2. Quick Brief — $0.01/call
- Endpoint: POST https://preview-chat-985505b1-9dc0-470f-9fc3-3704d8b625e3.space-z.ai/api/x402/quick-brief
- Input: JSON `{ "topic": "10-200 chars", "recency_days"?: 0|7|30|90|365, "max_findings"?: 3-6 (default 4) }`
- Does: one live web search → snippet-level digest with 3-6 cited key points, in seconds (no full-page reads; for depth use the Research Brief).
- Example success response:
```json
{ "ok": true, "topic": "...", "answer": "1-2 sentence direct answer",
  "key_points": [{ "point": "...", "source_url": "https://...", "source_title": "...", "source_date": null }],
  "sources": [{ "url": "https://...", "title": "...", "date": null, "retrieved_at": "...", "basis": "snippet" }],
  "caveats": "...", "generated_at": "..." }
```

### 3. Wallet Balance Lookup — $0.001/call
- Endpoint: GET https://preview-chat-985505b1-9dc0-470f-9fc3-3704d8b625e3.space-z.ai/api/x402/wallet-balance?chain=<btc|eth|base|sol|tron|ronin>&address=<addr>
- Does: live native-asset balance via public RPCs.
- Example success response:
```json
{ "chain": "sol", "address": "...", "ok": true, "balance": "0 SOL", "raw": "0", "checked_at": "..." }
```

## 30-second quickstart

Step 1 — meet the challenge (free, no payment):
```bash
curl -i "https://preview-chat-985505b1-9dc0-470f-9fc3-3704d8b625e3.space-z.ai/api/x402/wallet-balance?chain=eth&address=0x40560Fa6E0908932Ab8F7bf8B2AFA18533e044Cc"
# → HTTP/1.1 402 Payment Required
# → Payment-Required: <base64 JSON: x402Version, resource, accepts[] {scheme,network,asset,amount,payTo}>
```
The brief endpoints also return a human/agent-readable JSON body (`service`, `price`, `how_to_pay`, input contract).

Step 2 — sign and pay (agent recipe):
1. Base64-decode the `Payment-Required` header → the challenge object.
2. Build an EIP-3009 `transferWithAuthorization` signature for `accepts[0]` (amount, asset, payTo, network) per https://x402.org — any x402 v2 client SDK does this from the header directly.
3. Retry the identical request with the payment attached (SDK: `PAYMENT` header; wire format per x402 spec). The facilitator verifies and settles on-chain; your paid response returns.

Step 2 — JavaScript/TypeScript agents (x402 SDK):
```ts
import { x402Client } from "@x402/core/client";
import { x402HTTPClient } from "@x402/http/client"; // or fetch wrapper per SDK docs
import { registerExactEvmScheme } from "@x402/evm/exact/client";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount("0xYOUR_BUYER_KEY"); // holds Base Sepolia (testnet) USDC
const client = x402Client({ account }).register(registerExactEvmScheme);
const res = await client.fetch("https://preview-chat-985505b1-9dc0-470f-9fc3-3704d8b625e3.space-z.ai/api/x402/wallet-balance?chain=eth&address=0x40560Fa6E0908932Ab8F7bf8B2AFA18533e044Cc");
```
(Exact client imports vary by SDK version — https://x402.org docs are canonical; the flow above is what the challenge asks for.)

Failure modes are free: 400 (bad input), 413 (body too large), 429 (rate-limited, see Retry-After), 5xx/502 — never charged. You pay only for a 200 with a useful body.

## Fair use

- Brief endpoints: sliding-window limits of 10/min per IP, 30/h per IP, 60/h global; 2 concurrent generations shared across both. Rate-limited calls return `429` with `Retry-After`.
- Body limits: research-brief max 4,096 bytes; quick-brief max 2,048 bytes (`413` over the limit). The payment gate precedes body validation, but failed calls are never charged.

## Service status (honest)

- Live on Base mainnet (`eip155:8453`) since 2026-09-21; settlement rail proven with 3 on-chain testnet settlements (0x1 receipts) before the flip.
- Facilitator: PayAI (verified exact/v2 on mainnet). The Bazaar discovery catalog indexes this service (`/discovery/resources` via facilitator.settle traffic).
- Verified earnings to date: $0.00 — the ledger fills only with on-chain settlement evidence, never simulated. No buyer has paid yet; you would be the first, and the money goes to the advertised payTo, verifiable on Basescan.
- Liveness: any unpaid request returning 402 = service up. This file returning 200 = origin up.

## Free endpoints (no payment)

- GET https://preview-chat-985505b1-9dc0-470f-9fc3-3704d8b625e3.space-z.ai/api/mission — this system's full mission-state JSON: opportunity pipeline, honest earnings ledger, action log, next actions.
- GET https://preview-chat-985505b1-9dc0-470f-9fc3-3704d8b625e3.space-z.ai/llms.txt — this catalog.