# XFuel Protocol

> Swap one baseURL. Every call comes back with a public receipt that names the
> model, the hub, and the cost. Unauthenticated POST /v1/chat/completions is
> $0.01 x402 on Base (CDP) and Solana (PayAI). Bearer xfuel-demo and valid API
> keys skip payment. /task-request is the other paid door. Paying
> api.xfuel.app moves real mainnet USDC. Canonical: api.xfuel.app.

## Start here (OpenAI-compatible)

- POST /v1/chat/completions : OpenAI chat completions. Unauthenticated GET or
  POST {} → 402 x402 ($0.01 USDC on Base or Solana). Returns signed receipt + public verify_url.
- POST /v1/agents/register  : bind agentWallet + collected HMAC-valid receipt → integer agent_id.
- GET|POST /v1/agents/:agent_id/book : possession-gated last-N collected spend for that agent_id. Not a public index.
- GET  /v1/models           : live catalog (Theta + Akash + xfuel/auto). Public, no key.
- POST /v1/images/generations · POST /v1/audio/transcriptions (modality routes).
- Auth: "Authorization: Bearer <key>" or "X-API-Key: <key>".
- Point any OpenAI client's baseURL at this host + /v1. Receipt in x-xfuel-*
  headers and the "xfuel" body field (HMAC-signed; not an on-chain tx).
- proof_outcome may be pending on the chat body — poll GET /task-status.

## Paid door (USDC / x402)

- POST /task-request      : paid M2M task. 402 without X-PAYMENT. Real USDC.
- Networks: Base mainnet (default, CDP facilitator) or Solana mainnet (PayAI).
  The 402 challenge lists both; your wallet picks the network.
- POST /task-quote        : forecast only (not an invoice).
- GET  /task-status       : status + proof outcome (also works for /v1 task ids).
- GET  /prove-result      : SP1 settlement proof when requested / above COGS gate.
- GET  /health            : status, demo limits, floats. Token buckets with null
  addresses are post-TGE, not live.
- GET  /stats             : public-safe usage.

## MCP

- npx xfuel-mcp  (stdio). First tool: chat_completions (= this /v1 path).
- submit_inference = POST /task-request (paid, 402 without a payer).
- register_agent = POST /v1/agents/register (needs a collected receipt + agentWallet).
- get_agent_book = GET|POST /v1/agents/:agent_id/book (possession-gated; not a public scoreboard).

## Discovery (x402scan + Bazaar)

- GET  /openapi.json      : OpenAPI 3.1 with x-payment-info. Public door is POST /v1/chat/completions.
- GET  /.well-known/x402  : x402 Bazaar manifest (same paid routes). x402scan ignores this.
- GET  /.well-known/agent-card.json : A2A v1.0 card (200).
- POST /v1/agents/register : bind agentWallet + collected HMAC-valid receipt → agent_id.
- GET|POST /v1/agents/:agent_id/book : possession-gated last-N collected spend. Not a public index.
- POST /v1/chat/completions : paid ($0.01 USDC on Base or Solana). Unauth GET or POST {} → 402.
- POST /task-request      : lower-level M2M paid route (not the public door).

## SDK

- npm install xfuel-sdk — client.chatCompletions() with x402 for unauthenticated calls.
- createMockPayer() is for a local mock facilitator only. This host rejects it.

## Docs

- Protocol map: AGENTS.md
- Agent Playbook: skills/AGENT_PLAYBOOK.md
- OpenAI gateway: docs/OPENAI_COMPATIBLE_GATEWAY.md
- Full REST API: docs/M2M_API.md
- Payments (x402): docs/payments-x402.md