Chit402
Chit402 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 (ES256 issuer signature); SP1 settlement proof is on demand. The issuer signature does not prove USDC moved. 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. Register is fail-closed: a collected HMAC-valid receipt plus a plain EOA (personal_sign), 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://chit402.com
Public API: https://api.chit402.com
Table of Contents
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/chit402.git
cd chit402
npm install
npx hardhat compile
npx hardhat test
Agent gateway
The agent-facing API (settlement, 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 deployment.
Website
cd apps/web
npm install
npm run dev
Try the paid door
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.chit402.com/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. Working copy: docs/CHAT_COMPLETIONS_GATEWAY.md.
npm install chit402-sdk
npx chit402-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.
Dual anchoring
Each UTC day the gateway signs the receipt Merkle root and publishes it in two places. GET /v1/receipts/tree/head returns both under anchors.base and anchors.solana (signature, slot, cluster, memo). A missing key or a failed send leaves that side pending. A day that already has a Solana signature is not posted again. Details: docs/product/receipt-merkle.md.
Keys stay in the host environment. They are not read from a file in this repo.
GET /v1/receipts/:task_id/inclusion proves one leaf against a signed head. When that head is not itself anchored and a later anchored signed head contains the leaf, the JSON adds optional covered_by. It names the smallest such head: epoch, tree_size, root, inclusion_url (/v1/receipts/<task_id>/inclusion?tree_size=<N>), and anchors (anchors.base.tx, and anchors.solana.slot / anchors.solana.signature when Solana is present). The field is omitted when the head is itself anchored. A quarantined head is not served and is not used as covered_by. Existing fields stay as they are. Detail: docs/product/receipt-merkle.md.
npx chit402-verify receipt.json inclusion.json head.json --rpc
That checks the inclusion proof, fetches the Solana transaction and requires the memo to contain the root, and checks the Base calldata the same way. It prints what this proves and what it does not prove.
One memo costs the Solana base fee: 5,000 lamports, 0.000005 SOL. No account is created, so there is no rent, and the sender does not add a priority fee. At about $120 per SOL that is under $0.001.
Devnet smoke (export the variables in the shell; the script does not load an env file):
export SOLANA_ANCHOR_SECRET_KEY # base58 or JSON array, host env only
export SOLANA_ANCHOR_CLUSTER=devnet
export SOLANA_RPC_URL=https://api.devnet.solana.com
node scripts/solana-anchor-smoke
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.