Router code tour
Five blocks of modules: the request path, the market, the money, durability, and the guards. What each file does and where to start reading.
Everything lives in one Bun process under router/src. The route table in server.ts is side-effect free on import (tests load the wiring without starting a listener) and the boot block runs only when the file is executed directly. The modules group into five blocks; this page names each block, the files in it, and the one job each file does.
Block 1: the request path
| File | What it does |
|---|---|
server.ts | The Hono route table, readiness (/ready), and the role-gated boot sequence: reconcilers, crons, and the listener. |
completions.ts | The paid turn, start to finish: parse, route, auction, 402 or verify, optimistic dispatch, stream, meter, bill. The pipeline comment at the top is the map. |
proxy.ts | The streaming tap between provider and client. Meters tokens for billing and measures TTFT on the router's own clock for the auction score. |
metering.ts | Token estimates (chars/4) for providers whose usage frames are missing or zero, so no prompt is ever billed as free. |
anthropicMessages.ts, responses.ts, embeddings.ts, images.ts | Surface adapters: each translates its wire format onto the same paid pipeline. |
Block 2: the market
Covered file by file in the auction code tour: the quote book (quotes.ts), class selection (routing.ts), clearing (auction.ts), the session cost view (sessions.ts), and the feedback channel (feedback.ts). probes.ts keeps latency honest for providers that are not winning traffic, and catalog.ts with modelRegistry.ts define the model classes those markets trade in.
Block 3: the money
| File | What it does |
|---|---|
payments.ts | The x402 flow: 402 bodies, verification, the optimistic-start exposure caps, wallet demotion, durable settlement attempts. |
money/settlement/ | The chain boundary. adapter.ts defines the five operations; eip3009.ts and permit2.ts own the exact and upto signing shapes; evm.ts executes on HyperEVM; mock.ts settles instantly for dev and CI. |
credits.ts, sessions.ts | The two amortization paths: prepaid reservations with no x402 round trip, and budget sessions drawing tranches against one signed authorization. |
payouts.ts | Epoch close. Customer money arrives continuously; providers are paid one netted transfer per hourly epoch, refunds go out, and the epoch hash anchors on-chain. |
reconciliationMonitor.ts | Runs the standalone auditors on a schedule; a confirmed failure closes paid admission until a later audit passes. |
Block 4: durability
records.tsis the persistence layer: SQLite through Bun's built-in driver, WAL mode, with usage_records as the atom of settlement that everything money-related derives from.sqliteStartup.ts and sqliteWal.ts keep the connection lock-safe across deploys, idempotency.ts deduplicates client retries, and the Litestream wrapper plus the S3 writer lease (under deploy/ and scripts/) replicate the file continuously and fence a single writer.
Block 5: guards and operations
config.ts refuses to boot misconfigured: chain and treasury validation, mainnet launch gates, exposure caps. In steady state, financialReadiness.ts gates paid admission, rateLimit.ts and clientIp.ts guard the front door, integrity.ts runs model verification, privacy.ts and retainedStorage.ts enforce zero retention by default, and metrics.ts, observability.ts, alerting.ts, and admin.ts are the operator surface.
completions.ts, then read auction.ts (its header explains the economics), then payments.ts. Those three files are the product; most of the rest exists so they can be trusted.- router/src/http/server.ts route table, readiness, and boot
- router/src/api/completions.ts the paid request pipeline
- router/src/money/payments.ts the x402 flow and exposure caps
- router/src/storage/records.ts the SQLite schema