# x402 Image API — llms.txt

> Paid image generation for AI agents via the x402 protocol (HTTP 402 + USDC on Base). Prompt in → PNG out. Live at https://x402.chaly.org

## What this is

- **Endpoint:** `POST https://x402.chaly.org/generate` (x402 paid)
- **Protocol:** x402 v2, `exact` scheme, Base mainnet `eip155:8453`, asset `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (USDC), `payTo 0x53406C32dF6e494aFB078279EA3AD752542E5F0f`, `maxTimeoutSeconds 900`, facilitator `https://facilitator.payai.network`
- **Price:** `low:1K $0.005` per image. `total = $0.005 × count` (aspect free). `count 1..8` or batch `items:[[prompt,count]]` total ≤8. Other tiers 400 (not offered).
- **Flow:** `402 PAYMENT-REQUIRED` (base64 offer) → sign EIP-3009 → retry with `PAYMENT-SIGNATURE` → `202 {jobId, pollUrl, estimatedSeconds:85, charged}` → poll `GET /result/:id` every 5s until `done {urls, items, images}`. Images are white-label `https://x402.chaly.org/images/<hash>.png` (7d retention, no provider leak).
- **Capacity:** self-hosted, ~435 claim-eligible at boot (`last_used ≥24h`, skips `bad_accounts.json 144 + 02jxy`), concurrency 3 browsers, 503 if none eligible. Health at `GET /health` shows `pool_size/eligible/pricing/jobs`.
- **Stack:** self-hosted diffusion, jobs persisted to `jobs.json` (24h TTL), idempotent `id`.

## Endpoints

- `POST /generate` — paid. Body `{prompt, count}` or `{items:[[prompt,count]]}` + `quality:low, megapixels:1K, aspect:1:1|9:16|...|21:9|Auto, id}`. Returns `402 | 202 | 400 | 429 | 503`.
- `GET /result/:id` and `GET /jobs/:id` — poll job. Returns `{status:processing|done|failed, result|error, pollUrl}`.
- `GET /images/:file` — PNG (`[A-Za-z0-9._-]+\.png`).
- `GET /health` — `{ok, status, version, network, facilitator, payTo, capacity{pool_size,eligible,servable_tiers}, pricing{table,defaults}, jobs{active,total}}`.
- `GET /readyz` — 503 if no eligible; `GET /livez` — 200 if alive; `GET /metrics` — Prometheus; `GET /.well-known/x402` — x402 discovery (Bazaar).
- `GET /openapi.json` — OpenAPI 3.1.0 spec; `GET /llms.txt` — this file.

## Buyer examples

### JS (@x402/fetch + viem, polling)

```js
import { wrapFetchWithPaymentFromConfig, decodePaymentResponseHeader } from '@x402/fetch'
import { ExactEvmScheme } from '@x402/evm/exact/client'
import { privateKeyToAccount } from 'viem/accounts'

const signer = privateKeyToAccount(process.env.BUYER_PRIVATE_KEY) // Base USDC holder
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: 'eip155:8453', client: new ExactEvmScheme(signer) }],
})

const res = await fetchWithPayment('https://x402.chaly.org/generate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ prompt: 'a red cube on a blue table', count: 1, aspect: '1:1', id: 'my-key-1' }),
})
console.log(decodePaymentResponseHeader(res.headers.get('PAYMENT-RESPONSE'))) // {success, payer, transaction, network}
const { jobId, pollUrl } = await res.json() // 202
let data
while (true) {
  await new Promise(r => setTimeout(r, 5000))
  const pr = await fetch(pollUrl); const pj = await pr.json()
  if (pj.status === 'done') { data = pj.result; break }
  if (pj.status === 'failed') throw new Error(pj.error)
}
console.log(data.urls) // ['https://x402.chaly.org/images/abc_1.png']
```

### curl (discover pricing + 402)

```bash
curl -s https://x402.chaly.org/health | jq .pricing
curl -i -X POST https://x402.chaly.org/generate -H "Content-Type: application/json" -d '{"prompt":"a red cube","count":1}' # → 402 + PAYMENT-REQUIRED
```

### MCP (once published)

Tool `image_generate` with args `{prompt, count, aspect, id}` — wraps the paid POST + polling above. Use via Smithery / mcp.so / Claude.

## Fees and limits

- Rate limit: 30/min on `/generate` (429), 120/min on `/health`/`/images`.
- Concurrency: 3 browsers total; batch fan-out in chunks of 3. Worker timeout 600s.
- Pricing is dynamic per request (PAYMENT-REQUIRED `amount` = `5000` atomic per image = `$0.005`).
- Capacity gate 503 before 402 — no signature wasted if we can't serve.
- Errors are JSON only; every response has `X-Request-Id`.

## Discovery for agents

- OpenAPI: https://x402.chaly.org/openapi.json
- x402 manifest: https://x402.chaly.org/.well-known/x402
- Health: https://x402.chaly.org/health
- Bazaar: `declareDiscoveryExtension {bazaar:true, bodyType:json}` — auto-indexed via PayAI facilitator.
- Directories: x402-list.com, x402scan.com, agent402.tools, gatex402.dev — search `x402-image-api` or `payTo 0x53406C...`.

## Notes

- Seller holds no private keys; facilitator settles gasless EIP-3009. No accounts/API keys — payment is auth.
- Images are GPT Image 2 via media.io; prompts 3–2000 chars, aspect free, quality/megapixels locked to low/1K today.
- Maintain daily claim loop `media_io_persistent.py login --older-than 3 --workers 3` (sessions TTL ~7d).

## Links

- Live: https://x402.chaly.org
- OpenAPI: https://x402.chaly.org/openapi.json
- Well-known: https://x402.chaly.org/.well-known/x402
- Health: https://x402.chaly.org/health
- Client ref: `client.mjs` in repo
- Protocol: https://x402.org + https://docs.cdp.coinbase.com/x402 + https://x402bazaar.org/docs