Auth and payment

Agents hold no session, OAuth token, or Venice API key. The only checkpoint on paid routes is x402 settlement (USDC on Base).

Prefer stock x402 (@x402/fetch / Quickstart) — unpaid → 402 → PAYMENT-SIGNATURE → PAYMENT-RESPONSE. The CLI is an optional convenience wrapper around the same loop.

Free vs paid

Call	Requirement
Catalog GETs (`/models`, `/characters`, `/image/styles`, `/crypto/rpc/networks`, …)	None
Sync inference POSTs (chat, image, TTS, …)	x402 settlement
Async music/video quote / retrieve / complete	None (free)
Async music/video queue	x402 settlement

The 402 challenge

An unpaid paid route returns 402. Prefer the Payment-Required header (base64 JSON). The body mirrors the challenge for convenience.

Decoded shape (illustrative):

{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://x402.aispace.bot/api/v1/chat/completions",
    "description": "Chat completions (x402)",
    "serviceName": "AiSpace Venice"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "amount": "5000",
      "payTo": "0x…",
      "maxTimeoutSeconds": 300
    }
  ],
  "extensions": {
    "upstreamUsd": 0.01,
    "priceMult": 0.5
  }
}

amount is USDC base units (6 decimals — "5000" = $0.005). Always pay the live challenge amount.

Payment headers

After signing, resend the identical request with one of:

PAYMENT-SIGNATURE: <payload> (x402 v2 standard — what @x402/fetch / @x402/core send)
X-402-Payment: <payload> (accepted alias)
X-Payment: <payload> (legacy / v1 alias)

Build the payment from the latest 402 — never hardcode amount, payTo, or asset.

After payment (fulfillment errors)

Settlement is final. If Venice/proxy fails after capture, the gateway returns a non-2xx (often 502) with:

Header PAYMENT-RESPONSE (x402 v2 settle receipt — what @x402/fetch reads)
Header x-aispace-payment: settled
Header x-aispace-payment-id: <tx>
Body { "settled": true, "paymentId": "…", "error": "…" }

That means USDC already moved. Do not sign a new payment unless you intentionally want to pay again. A charge that settled but never delivered is eligible for a service credit or refund — see Errors → Credit / refund.

Successful paid responses also include PAYMENT-RESPONSE so stock clients report settlement correctly (not payment status none).

How to pay

Use a standard x402 client or AgentCash against a Base USDC wallet. The instrument is typically an EIP-3009 TransferWithAuthorization (payer needs USDC; gasless settle via facilitator).

See OpenAPI info.x-guidance for the full agent playbook.

CLI & MCP Sync routes