# AiSpace x402 Marketplace

> Pay-per-request Venice inference via x402. Chat, image, video, audio, search, and RPC — USDC on Base, no API key. OpenAI-compatible /api/v1 at x402.aispace.bot.

Origin: https://x402.aispace.bot
Product (humans): https://aispace.bot
Docs: https://docs.aispace.bot/agent-api
OpenAPI: https://x402.aispace.bot/openapi.json
Well-known: https://x402.aispace.bot/.well-known/x402.json

## Path of least resistance

Stock x402 (default) — unpaid → HTTP 402 → `PAYMENT-SIGNATURE` retry:

1. Discover: GET /openapi.json, /llms.txt, /.well-known/x402.json
2. Free catalogs: GET /api/v1/models (defaults to ?type=all — every family) or /api/v1/models?type=… to filter one
3. Unpaid paid-route call → **402** + `Payment-Required` (base64 challenge)
4. Sign exact USDC on Base (or Solana when listed in accepts[]); retry identical request with `PAYMENT-SIGNATURE`
5. On success read `PAYMENT-RESPONSE` (settle receipt)

Use `@x402/fetch` + `@x402/evm` for Base, or `@x402/svm` for Solana (see https://docs.x402.org/getting-started/quickstart-for-buyers). Gateway works without any AiSpace package.

## Complementary options

- CLI convenience: `npx @aispace.bot/x402` (env `AISPACE_X402_KEY`)
- MCP: `npx -y @aispace.bot/x402 mcp` (Cursor / Claude Desktop)
- Header aliases also accepted: `X-402-Payment`, `X-Payment`

## Machine discovery

- GET /openapi.json — routes, x-guidance, info.x-pricing (Venice rates × priceMult), responses.200 from live probes
- GET /api/v1/models — free catalog, defaults to ?type=all; filter with ?type=text|image|video|music|tts|asr|embedding|upscale|inpaint. Music defaults to short-clip ids; pass ?floor=all for 60s-floor models (ACE-Step).
- POST /api/v1/video/quote | /api/v1/audio/quote — free accurate job quotes (`quote` is already the agent charge). Queue body is a different contract: include `prompt` (and I2V `image_url`). A quote 200 is not proof the job will run.
- Live settlement price: HTTP 402 `accepts[].amount` (always authoritative)

## Response shapes

Trust OpenAPI `responses.200` / Bazaar output. Do not invent keys (`voice_id`, `job_id`, `pages`). Image generate/generations → JSON. Edit/upscale/bg-remove default → binary file (`return_binary: false` → JSON like generate). Speech/retrieve → binary. Video `duration` must match `model_spec.constraints`; a bad quote is HTTP 400, not 503.

## Pricing rule

Agent charge = Venice-equivalent upstream USD × priceMult (env). No fake category floors. Unknown price → error, not a cheap 402.

## Chat / thinking models

Do not treat empty `choices[0].message.content` alone as failure. Reasoning models may fill `reasoning_content` / `reasoning_details` instead (especially with a small max_tokens). Use `venice_parameters.disable_thinking: true` for a normal text reply. Docs: https://docs.aispace.bot/agent-api/sync-routes#reasoning--thinking-models

## Optional

- x402scan directory listing for this origin
- Stats (aggregate): GET /api/x402/stats — today plus a rolling 30-day window (`rolling30d`)
- Health: GET /api/x402/health — liveness/readiness for the payment rail (200 ok / 503 degraded)