XFuel Protocol

XFuel is the book. This agent spent Y on this job. You hold hub, model, and amount.

POST /v1/chat/completions returns a signed receipt: hub, model, amount, verify_url. Cost-plus, quoted, receipted — pay USDC on Base or Solana. GET|POST /v1/agents/:agent_id/book is possession-gated last-N collected spend. Signed receipt is table stakes (HMAC); SP1 settlement proof is on demand. The product is the collected row — sidecar + ingest if you already pay a provider; without a collected USDC payment.ref the receipt is client-attested only. Demo key xfuel-demo skips payment (rate-limited). Register is fail-closed: a collected HMAC-valid receipt plus an AAWP official or smart-account agentWallet.

To learn more about the protocol design, read the whitepaper. For live endpoints and what is real vs mock today, see runtime state. Full documentation hub: docs/.

Live app: https://xfuel.app
Public API: https://api.xfuel.app

Table of Contents

• Setup
• Using the API
• Agent toolkit
• Documentation
• Security

Setup

Prerequisites

Install Node.js 20+ and npm 10+. A Rust toolchain is required if you build CosmWasm, SP1, or zkLLM crates.

Build and test

Clone the repository, install dependencies, compile contracts, and run the test suite:

git clone https://github.com/XFuel-Lab/xfuel-protocol.git
cd xfuel-protocol
npm install
npx hardhat compile
npx hardhat test

Agent gateway

The agent-facing API (routing, payments, proving, receipts) runs from services/gateway:

cd services/gateway
npm install
npm run m2m-server

The gateway listens on http://localhost:3002 by default. Env examples live under services/gateway/. Production layout is documented in runtime state.

Website

cd apps/web
npm install
npm run dev

Try the demo

No account. No API key. A wallet that can pay the 402 is enough. Register is only to hold the book after a collected receipt.

curl.exe -sS -D - -X POST https://api.xfuel.app/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{}'

Unauthenticated /v1 returns HTTP 402 with payment requirements (USDC on Base or Solana). The receipt prices the next call. Demo key xfuel-demo skips payment (rate-limited). Working copy: docs/DESIGN_PARTNER_ONBOARDING.md.

npm install xfuel-sdk
npx xfuel-mcp

flagship-demo.ts is the paid /task-request path (402 without a payer). Do not start there.

• TypeScript SDK — packages/sdk
• MCP server — packages/mcp
• Agent playbook — packages/agent-skills

Windows note: if you use raw HTTP, call curl.exe — PowerShell’s curl is not real curl.

API reference: M2M API · Chat completions: docs here · Payments: x402 adapter.

Documentation

Security

Responsible disclosure (safe harbour; no cash bounty until the first audit): docs/bug-bounty.md.
Reporting policy: SECURITY.md.

---

Apache-2.0 — see LICENSE.