Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
feat(inference): let a wallet pay per request for the OpenAI-compatible endpoint over x402 upto, settled on measured tokens
nirholasfbb235df5a57
diff --git a/STRUCTURE.md b/STRUCTURE.mdindex 4a9e8aedf..81fd8efef 100644--- a/STRUCTURE.md+++ b/STRUCTURE.md@@ -125,6 +125,7 @@ packages, a generated standalone GitHub mirror). See| MCP credit plans (`/mcp-plans`) | [pages/mcp-plans.html](pages/mcp-plans.html) `→ /mcp-plans` + [src/mcp-plans.js](src/mcp-plans.js), API [api/mcp-plans.js](api/mcp-plans.js) `→ GET/POST /api/mcp-plans`, meter [api/_lib/mcp-credits.js](api/_lib/mcp-credits.js) wired into [api/_mcp/dispatch.js](api/_mcp/dispatch.js), catalog and purchase [api/_lib/mcp-plans.js](api/_lib/mcp-plans.js), schema [api/_lib/migrations/20261023160000_mcp_plans.sql](api/_lib/migrations/20261023160000_mcp_plans.sql) | Built, unapplied | Credit bundles and time passes for paid MCP tools, bought from the prepaid balance. The dispatcher debits before a call, refunds on error, spends a metered free trial last, returns `creditsUsed` and `creditsRemaining` in `_meta`, and falls back to the per-call `-32402` when a plan holder runs dry. Docs: the pricing section of [docs/mcp.md](docs/mcp.md). Tests: [tests/mcp-credit-plans.test.js](tests/mcp-credit-plans.test.js) || Developer plans and quotas (`/developers`) | Config [api/_lib/dev-plans/config.js](api/_lib/dev-plans/config.js) (the only place plan numbers live), gate [api/_lib/dev-plans/quota.js](api/_lib/dev-plans/quota.js) wired into [api/_lib/gateway.js](api/_lib/gateway.js) for every `/api/v1` route, subscriptions [api/_lib/dev-plans/subscription.js](api/_lib/dev-plans/subscription.js), checkout + receipts [api/_lib/dev-plans/billing.js](api/_lib/dev-plans/billing.js), per-key analytics [api/_lib/dev-plans/analytics.js](api/_lib/dev-plans/analytics.js), key cache + immediate invalidation [api/_lib/api-key-cache.js](api/_lib/api-key-cache.js), allowlists [api/_lib/ip-allowlist.js](api/_lib/ip-allowlist.js); REST [api/v1/dev-plans.js](api/v1/dev-plans.js) `→ GET /api/v1/dev-plans`, [api/v1/me/dev-plan/](api/v1/me/dev-plan) `→ /api/v1/me/dev-plan{,/checkout,/confirm,/schedule,/receipts}`, key tools [api/keys/[id]/rotate.js](api/keys/%5Bid%5D/rotate.js), [allowlist.js](api/keys/%5Bid%5D/allowlist.js), [analytics.js](api/keys/%5Bid%5D/analytics.js); page [pages/developers.html](pages/developers.html) `→ /developers` + [public/developers.css](public/developers.css); dashboard Plan tab [src/dashboard-next/pages/developers-plan.js](src/dashboard-next/pages/developers-plan.js) `→ /dashboard/developers#plan`, key tools [src/dashboard-next/pages/api-key-tools.js](src/dashboard-next/pages/api-key-tools.js) | Live | Free, Builder, Scale, Enterprise. Monthly quota, burst and concurrency enforced at the gateway (429 + Retry-After, 402 `quota_exceeded` with the next plan). Upgrades in credits, USDC or $THREE on Solana, user wallet signs, proration, downgrade at period end, receipts. Migration `20261010230000_dev_plans.sql`. Doc [docs/developer-plans.md](docs/developer-plans.md) || Spend and token ceilings (`/spend`) | [pages/spend.html](pages/spend.html) `→ /spend` + [src/spend-page.js](src/spend-page.js), read model [api/spend/me.js](api/spend/me.js) `→ GET /api/me/spend`, ceilings [api/agents/_id/token-budget.js](api/agents/_id/token-budget.js) `→ /api/agents/:id/token-budget(/resume|/extend)` over [api/_lib/token-budgets.js](api/_lib/token-budgets.js), gate wired into `assertAgentBudget` in [api/_lib/inference-billing.js](api/_lib/inference-billing.js), counters [api/_lib/migrations/20261010173000_agent_token_budgets.sql](api/_lib/migrations/20261010173000_agent_token_budgets.sql), free-tier choices [api/_lib/free-tier.js](api/_lib/free-tier.js) | Live | Per-agent hourly, daily and per-run token ceilings enforced before the model call with one conditional upsert per window (two calls racing for the last token admit exactly one), next to the dollar budget. Hitting a ceiling pauses the agent, notifies the owner (`token_budget_paused`) and opens one extend-once approval (venue `token_budget`); resume refuses while the window is still full (`409 still_capped`). The spend page shows balance, month-to-date and projected month end, per-agent usage by day, model and tool, and every 50/80/100 percent alert (`spend_cap_alert`) from the same latches the bell uses. The free-tier `429 free_tier_exhausted` body carries `choices` (wait, top up, bring your own key, and a one-step `paid_fallback` on brain chat, copilot and v1 messages). Docs: [docs/inference-billing.md](docs/inference-billing.md). Tests: [tests/token-budgets.test.js](tests/token-budgets.test.js). |+| Pay-per-request model access (`POST /api/v1/chat/completions` with no key) | price table [api/_lib/pricing/inference-models.js](api/_lib/pricing/inference-models.js), cap sizing, escrow and claim [api/_lib/metered-router.js](api/_lib/metered-router.js), endpoint [api/v1/chat/completions.js](api/v1/chat/completions.js), price sheet [api/v1/models.js](api/v1/models.js) `→ GET /api/v1/models` | Live (needs `X402_UPTO_ENABLED`) | An unauthenticated request answers 402 with an x402 `upto` Solana offer whose cap is the model's worst case for that request; the retry escrows the cap, the completion runs, and the claim settles measured tokens times the published price while the rest is refunded. A request that produces nothing cancels the channel; a dropped stream settles the tokens already sent. Docs: [docs/metered-router.md](docs/metered-router.md). Tests: [tests/metered-router.test.js](tests/metered-router.test.js). || Agent lifecycle, runs and automations over MCP (Runs tab) | MCP tools [api/_mcp/tools/agent-lifecycle.js](api/_mcp/tools/agent-lifecycle.js) (`get_agent`, `update_agent`, `delete_agent`, `start_agent`, `stop_agent`, `upload_agent_avatar`, `create_agent_run`, `update_agent_run`, `cancel_agent_run`, `get_agent_run_steps`, `automation_list`, `automation_get`, `automation_create`, `automation_update`, `automation_delete`, `automation_trigger`) over the REST validators and engines in [api/_lib/agents-v1/](api/_lib/agents-v1) (runs, automations, run receipts), policy rows in [packages/mcp-policy/src/table.js](packages/mcp-policy/src/table.js); replay endpoint [api/agent-run-replay.js](api/agent-run-replay.js) `→ /api/agent-run-replay`; Runs tab [src/agent-run-replay.js](src/agent-run-replay.js), mounted from [src/avatar-page.js](src/avatar-page.js) on `/agents/:id?view=runs` | Built, ships with the next deploy | An MCP client can now edit, start, stop, re-skin and delete an agent, and drive autonomous runs and automations, with create and update validated by the same schemas as the REST path. `delete_agent` and `automation_delete` are destructive: refused without `confirm_delete` and a matching `get_agent` / `automation_get` preview. A run carries two budgets (model turns and dollars), honors cancel between steps, ends with a plain-language summary, and chains a sha256 receipt over every step; `get_agent_run_steps` returns each tool call paired with its result and receipt. The owner-only Runs tab lists every run, replays it step by step with a scrubber, polls a live run, verifies the receipt chain server-side, and cancels. Docs: [docs/mcp.md](docs/mcp.md) `→ /docs/mcp`, [docs/agent-runtime.md](docs/agent-runtime.md#autonomous-runs-budgets-receipts-and-replay). Tests: [tests/mcp-agent-lifecycle.test.js](tests/mcp-agent-lifecycle.test.js), [tests/agent-run-replay-endpoint.test.js](tests/agent-run-replay-endpoint.test.js) || Agents REST API (`/api/v1`) and webhooks | Router [api/v1/rest.js](api/v1/rest.js) over [api/_lib/agents-v1/](api/_lib/agents-v1) (http envelope, agents, runs, automations, skills, [webhooks.js](api/_lib/agents-v1/webhooks.js), [run-stream.js](api/_lib/agents-v1/run-stream.js), [agent-export.js](api/_lib/agents-v1/agent-export.js), [openapi.js](api/_lib/agents-v1/openapi.js)), delivery queue [api/_lib/webhook-dispatch.js](api/_lib/webhook-dispatch.js), retry cron [api/cron/webhook-deliveries.js](api/cron/webhook-deliveries.js), dashboard [src/dashboard-next/pages/developers.js](src/dashboard-next/pages/developers.js) `→ /dashboard/developers` | Built, ships with the next deploy | Agent CRUD, start/stop, sync chat and history, runs with resumable SSE, automations with trigger-now, skills, strategies, export/import, and HTTPS webhooks (`run.finished`, `automation.fired`, `message.received`, `approval.needed`) with HMAC signatures, 8-attempt backoff, a delivery log and replay. Cursor pagination, `{data, meta}` envelope, `Idempotency-Key`. Docs: [docs/api-reference.md](docs/api-reference.md#agents-api-v1), [docs/developer-platform.md](docs/developer-platform.md). Tests: [tests/api/v1-rest-router.test.js](tests/api/v1-rest-router.test.js), [tests/api/agent-export.test.js](tests/api/agent-export.test.js), [tests/api/run-stream.test.js](tests/api/run-stream.test.js), [tests/webhook-dispatch-signing.test.js](tests/webhook-dispatch-signing.test.js) || Platform OpenAPI spec + Postman collection | Spec [public/.well-known/openapi.yaml](public/.well-known/openapi.yaml) `→ /.well-known/openapi.yaml`, generator [scripts/build-postman-collection.mjs](scripts/build-postman-collection.mjs) `→` [public/.well-known/postman-collection.json](public/.well-known/postman-collection.json) `→ /.well-known/postman-collection.json` | Built, ships with the next deploy | A ready-to-import Postman Collection v2.1 generated from the same OpenAPI spec every client already reads, via `openapi-to-postmanv2`; a `clean()` pass strips the converter's per-run random ids and fabricated example responses so the checked-in file is byte-identical across regenerations. `npm run build:postman-collection` regenerates it, `npm run check:postman-collection` (wired into `npm run gate`) fails when it drifts from the spec. Docs: [docs/api-reference.md](docs/api-reference.md) |diff --git a/api/_lib/metered-router.js b/api/_lib/metered-router.jsnew file mode 100644index 000000000..d002f1edf--- /dev/null+++ b/api/_lib/metered-router.js@@ -0,0 +1,280 @@+// Pay-per-request access to POST /api/v1/chat/completions, funded over x402.+//+// A caller with no API key and no session pays for the one request with its own+// Solana wallet, through the x402 `upto` scheme (api/_lib/x402/upto.js):+//+// 1. No payment header: 402 whose `upto` accept is sized to the model's worst+// case for THIS request (`capAtomics`), so the buyer authorizes a cap and+// never more.+// 2. Payment header: verify it, escrow the cap (deposit), run the completion.+// 3. The completion's measured tokens times the model's published price is the+// charge. The claim settles exactly that and the program refunds the rest.+// 4. A completion that fails before any token was produced settles nothing:+// a claim of zero returns the whole deposit.+//+// Streaming: the deposit is escrowed before the first byte, the claim happens+// when the model loop reports its final usage (before the closing SSE frames),+// and a client that drops the stream is charged for the tokens already sent.+//+// The keyed path (account credits) lives in api/_lib/inference-billing.js and+// is untouched by this module.++import { env } from './env.js';+import { clientIp } from './rate-limit.js';+import { estimateTokens } from './inference-billing.js';+import { inferenceModelRow, INFERENCE_MODEL_ROWS } from './pricing/inference-models.js';+import { logPaymentEvent } from './x402/audit-log.js';+import {+ NETWORK_SOLANA_MAINNET,+ X402Error,+ decodePaymentHeader,+ send402,+ verifyPayment,+ resolveResourceUrl,+} from './x402-spec.js';+import {+ buildUptoRequirement,+ normaliseCharge,+ settleUptoClaim,+ settleUptoDeposit,+ uptoEnabled,+} from './x402/upto.js';++export const METERED_ROUTE = '/api/v1/chat/completions';+const ATOMICS_PER_USD = 1_000_000; // USDC has 6 decimals; credits are USD-denominated++/** Tokens for the caller's side of a request (messages plus any client tools). */+export function promptTokensOf(body) {+ return estimateTokens(body?.messages) + estimateTokens(body?.tools);+}++/** USD -> USDC atomics, rounded up so the claim never undercharges the ledger. */+export function usdToAtomics(usd) {+ return BigInt(Math.ceil(Number(usd) * ATOMICS_PER_USD - 1e-6));+}++/** Price tokens at a model row's published per-million rates, in USD. */+export function priceTokens(row, inputTokens, outputTokens) {+ const input = Math.max(0, Number(inputTokens) || 0);+ const output = Math.max(0, Number(outputTokens) || 0);+ const raw = (input * row.input_usd_per_mtok + output * row.output_usd_per_mtok) / 1e6;+ const micro = Math.ceil(raw * 1e6 - 1e-9);+ return Math.max(row.min_call_usd, micro / 1e6);+}++/** The measured charge in USDC atomics for a finished (or cut-off) completion. */+export function chargeAtomics(row, inputTokens, outputTokens) {+ return usdToAtomics(priceTokens(row, inputTokens, outputTokens));+}++/**+ * The most this request can cost, in USDC atomics: every round the loop may run+ * at the model's per-round output limit, each reading the caller's prompt plus+ * the context a round may add. A request that brings its own tools is one round+ * bounded by its own max_tokens.+ */+export function worstCaseAtomics(row, body, { clientTools = false } = {}) {+ const prompt = promptTokensOf(body);+ if (clientTools) {+ const asked = Number(body?.max_tokens ?? body?.max_completion_tokens);+ const out = Number.isFinite(asked) && asked > 0 ? Math.min(Math.round(asked), row.client_tools_max_output) : 4096;+ return chargeAtomics(row, prompt, out);+ }+ const rounds = row.max_rounds;+ let input = 0;+ for (let i = 0; i < rounds; i++) input += prompt + row.context_allowance_round;+ return chargeAtomics(row, input, rounds * row.max_output_tokens_round);+}++export function paymentHeaderOf(req) {+ return req.headers['payment-signature'] || req.headers['x-payment'] || null;+}++/** True when this deployment can sell a request over x402 `upto`. */+export function meteredAvailable() {+ return uptoEnabled() && !!env.X402_PAY_TO_SOLANA && !!env.X402_ASSET_MINT_SOLANA;+}++async function offerFor(row, body, opts) {+ const cap = worstCaseAtomics(row, body, opts);+ const resourceUrl = resolveResourceUrl(null, METERED_ROUTE);+ const offer = await buildUptoRequirement({+ capAtomics: cap,+ network: NETWORK_SOLANA_MAINNET,+ asset: env.X402_ASSET_MINT_SOLANA,+ payTo: env.X402_PAY_TO_SOLANA,+ resourceUrl,+ });+ return { requirement: { ...offer, resource: resourceUrl }, resourceUrl, cap };+}++/** Answer 402 with the `upto` challenge for this request. */+export async function sendMeteredChallenge(res, row, body, opts, errorText) {+ const { requirement, resourceUrl } = await offerFor(row, body, opts);+ return send402(res, {+ resourceUrl,+ accepts: [requirement],+ error: errorText || 'Payment required: pay for this request with x402 upto, or send an API key.',+ description: `${row.id} chat completion, metered by tokens (input ${row.input_usd_per_mtok} and output ${row.output_usd_per_mtok} USD per million tokens)`,+ mimeType: 'application/json',+ serviceName: 'three.ws model router',+ tags: ['llm', 'openai-compatible', 'metered'],+ });+}++/**+ * Verify the caller's payment against this request's own offer and escrow the+ * cap. Resolves { session } to run the completion, or { challenge } when the+ * payment was refused and a fresh 402 has been written.+ */+export async function admitMeteredPayment(req, res, row, body, opts) {+ const { requirement, resourceUrl, cap } = await offerFor(row, body, opts);+ const header = paymentHeaderOf(req);+ let verified;+ try {+ decodePaymentHeader(header);+ verified = await verifyPayment({ paymentHeader: header, requirements: [requirement] });+ } catch (err) {+ if (!(err instanceof X402Error) && !err?.status) throw err;+ if (err.status === 402 || err.status === 400) {+ await sendMeteredChallenge(res, row, body, opts, err.message);+ return { challenge: true };+ }+ throw err;+ }+ if (!verified.upto) {+ await sendMeteredChallenge(res, row, body, opts, 'this endpoint is paid with the x402 upto scheme');+ return { challenge: true };+ }++ let deposit;+ try {+ deposit = await settleUptoDeposit({ paymentPayload: verified.paymentPayload, requirement: verified.requirement });+ } catch (err) {+ throw Object.assign(new Error(`upto deposit failed: ${err?.message || err}`), { status: 502, code: 'upto_deposit_failed' });+ }+ if (!deposit?.success) {+ await sendMeteredChallenge(res, row, body, opts, `upto deposit rejected: ${deposit?.errorReason || 'deposit_failed'}`);+ return { challenge: true };+ }++ const session = {+ row,+ cap,+ resourceUrl,+ payer: verified.payer || null,+ paymentPayload: verified.paymentPayload,+ requirement: verified.requirement,+ depositTransaction: deposit.transaction || null,+ settled: null,+ settling: null,+ ip: clientIp(req),+ userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,+ };+ logPaymentEvent({+ eventType: 'payment_upto_deposit',+ route: METERED_ROUTE,+ resourceUrl,+ payer: session.payer,+ network: session.requirement.network,+ txHash: session.depositTransaction,+ ipAddress: session.ip,+ userAgent: session.userAgent,+ metadata: { cap_atomics: String(cap), model: row.id },+ });+ return { session };+}++/**+ * Claim the measured charge, exactly once. `inputTokens` and `outputTokens` are+ * what the model produced; zero tokens out and zero tokens in cancels the+ * channel so the whole deposit returns to the buyer. Concurrent callers (the+ * usage hook and the close handler) share the one in-flight claim.+ */+export function settleMetered(session, { inputTokens, outputTokens, reason = 'completed', cancel = false }) {+ if (session.settling) return session.settling;+ session.settling = (async () => {+ const atomics = cancel ? 0n : normaliseCharge(chargeAtomics(session.row, inputTokens, outputTokens), session.cap);+ let result;+ try {+ result = await settleUptoClaim({+ paymentPayload: session.paymentPayload,+ requirement: session.requirement,+ amountAtomics: atomics.toString(),+ });+ } catch (err) {+ logPaymentEvent({+ eventType: 'payment_upto_claim_failed',+ route: METERED_ROUTE,+ resourceUrl: session.resourceUrl,+ payer: session.payer,+ network: session.requirement.network,+ ipAddress: session.ip,+ userAgent: session.userAgent,+ metadata: { reason, charge_atomics: atomics.toString(), error: String(err?.message || err).slice(0, 300) },+ });+ throw err;+ }+ const settled = {+ paid_via: 'x402-upto',+ network: session.requirement.network,+ payer: session.payer,+ model: session.row.id,+ input_tokens: Math.max(0, Number(inputTokens) || 0),+ output_tokens: Math.max(0, Number(outputTokens) || 0),+ cap_atomics: String(session.cap),+ charged_atomics: atomics.toString(),+ charged_usd: Number(atomics) / ATOMICS_PER_USD,+ refunded_atomics: (BigInt(session.cap) - atomics).toString(),+ transaction: result?.transaction || null,+ success: result?.success !== false,+ reason,+ };+ session.settled = settled;+ logPaymentEvent({+ eventType: cancel ? 'payment_upto_cancel' : 'payment_settled',+ route: METERED_ROUTE,+ resourceUrl: session.resourceUrl,+ payer: session.payer,+ network: session.requirement.network,+ txHash: settled.transaction,+ amountAtomics: settled.charged_atomics,+ ipAddress: session.ip,+ userAgent: session.userAgent,+ metadata: { reason, model: session.row.id, cap_atomics: settled.cap_atomics, input_tokens: settled.input_tokens, output_tokens: settled.output_tokens },+ });+ return settled;+ })();+ return session.settling;+}++/**+ * Watch a response so a dropped stream can be charged for what was sent. Wraps+ * res.write to count the characters of every streamed `delta.content`, and runs+ * `onClose` when the connection closes before the response was ended (a client+ * that dropped the stream).+ */+export function watchStream(res, { onClose }) {+ let chars = 0;+ const write = res.write.bind(res);+ res.write = (chunk, ...rest) => {+ const text = typeof chunk === 'string' ? chunk : Buffer.isBuffer(chunk) ? chunk.toString('utf8') : '';+ for (const line of text.split('\n')) {+ if (!line.startsWith('data: ') || line.startsWith('data: [DONE]')) continue;+ try {+ const content = JSON.parse(line.slice(6))?.choices?.[0]?.delta?.content;+ if (typeof content === 'string') chars += content.length;+ } catch {+ /* a partial frame carries no countable content */+ }+ }+ return write(chunk, ...rest);+ };+ res.once('close', () => {+ if (res.writableEnded) return;+ onClose({ outputTokens: Math.ceil(chars / 4) });+ });+ return { outputTokensSoFar: () => Math.ceil(chars / 4) };+}++export { INFERENCE_MODEL_ROWS };diff --git a/api/_lib/pricing/inference-models.js b/api/_lib/pricing/inference-models.jsnew file mode 100644index 000000000..df764bea5--- /dev/null+++ b/api/_lib/pricing/inference-models.js@@ -0,0 +1,40 @@+// The metered router's price table, as data.+//+// One row per model id POST /api/v1/chat/completions serves. The per-million+// prices come from the published inference rate in ./catalog.js, so the keyed+// credits path and the pay-per-request path charge the same amount for the+// same tokens and /api/v1/models never drifts from what is billed. The other+// fields bound a single request so the x402 `upto` challenge can be sized to+// the model's worst case before any work runs:+//+// max_rounds model rounds one request may run. The agent loop+// is capped at MAX_TOOL_ROUNDS tool rounds plus the+// answering round (api/agent/run.js).+// max_output_tokens_round completion tokens one round may emit.+// context_allowance_round tokens of tool output and loop history one round+// may add to its prompt on top of the caller's.+// client_tools_max_output ceiling for a request that brings its own `tools`+// (one round, api/_lib/client-tool-round.js).++import { INFERENCE_USD_PER_MTOK, INFERENCE_MIN_CALL_USD } from './catalog.js';++export const INFERENCE_MODEL_ROWS = Object.freeze([+ Object.freeze({+ id: 'three-ws/agent',+ aliases: Object.freeze(['three-ws', 'default']),+ input_usd_per_mtok: INFERENCE_USD_PER_MTOK.input,+ output_usd_per_mtok: INFERENCE_USD_PER_MTOK.output,+ min_call_usd: INFERENCE_MIN_CALL_USD,+ max_rounds: 5,+ max_output_tokens_round: 1024,+ context_allowance_round: 16_000,+ client_tools_max_output: 8192,+ }),+]);++/** The row for a model id or alias, or null when the model is not served. */+export function inferenceModelRow(id) {+ const wanted = String(id || '').trim();+ if (!wanted) return INFERENCE_MODEL_ROWS[0];+ return INFERENCE_MODEL_ROWS.find((r) => r.id === wanted || r.aliases.includes(wanted)) || null;+}diff --git a/api/v1/chat/completions.js b/api/v1/chat/completions.jsindex 37999b68c..6e64468fb 100644--- a/api/v1/chat/completions.js+++ b/api/v1/chat/completions.js@@ -24,6 +24,12 @@// 3. chargeInference books one idempotent credit_ledger row for the summed// tokens of every model round. A failed completion is not charged.//+// A caller with no key and no session can pay for the single request instead,+// over x402 `upto` on Solana (api/_lib/metered-router.js): the unauthenticated+// request is answered 402 with a cap sized to the model's worst case, the+// retry carries the signed payment, and the measured tokens times the model's+// published price are what settle; the rest of the cap is refunded.+//// The agent a call runs for is the one the key was provisioned from// (inference_keys), or the caller's own agent named by `agent_id` in the body// or the `X-Three-Agent` header. Without an agent the call bills the account@@ -43,9 +49,19 @@ import {import { runAgentCompletion } from '../../agent/run.js';import { providerChain } from '../../_lib/llm-tool-chain.js';import { runClientToolCompletion, sanitizeClientTools } from '../../_lib/client-tool-round.js';+import { clientIp } from '../../_lib/rate-limit.js';+import { inferenceModelRow } from '../../_lib/pricing/inference-models.js';+import {+ admitMeteredPayment,+ meteredAvailable,+ paymentHeaderOf,+ promptTokensOf,+ sendMeteredChallenge,+ settleMetered,+ watchStream,+} from '../../_lib/metered-router.js';const MAX_BODY_BYTES = 512_000;-const ACCEPTED_MODELS = new Set([INFERENCE_MODEL_ID, 'three-ws', 'default']);async function resolveCaller(req) {const bearerToken = extractBearer(req);@@ -59,6 +75,7 @@ async function resolveCaller(req) {}const session = await getSessionUser(req);if (session) return { userId: session.id, apiKeyId: null, clientId: null };+ if (meteredAvailable()) return { anonymous: true };return { error: [401, 'missing_api_key', 'Send a three.ws API key with the `inference` scope as `Authorization: Bearer sk_live_...`. The free, unmetered agent loop is POST /api/agent/run.'] };}@@ -88,6 +105,67 @@ function openAiError(res, status, code, message, detail = {}) {return error(res, status, code, message, { type: code, code, ...detail });}+// The pay-per-request lane: no key, no session, one request paid over x402+// `upto`. The cap is escrowed before any model call; the claim settles the+// measured tokens (or nothing, when the completion produced none).+async function handleMetered(req, res, body, row) {+ if (body?.agent_id || req.headers['x-three-agent']) {+ return openAiError(res, 401, 'sign_in_required', 'Naming an agent needs its owner: send an API key with the `inference` scope.');+ }+ let clientTools;+ try {+ clientTools = sanitizeClientTools(body?.tools);+ } catch (err) {+ return openAiError(res, err.status || 400, err.code || 'bad_tools', err.message);+ }+ const sizing = { clientTools: !!clientTools };+ if (!paymentHeaderOf(req)) return sendMeteredChallenge(res, row, body, sizing);++ const admitted = await admitMeteredPayment(req, res, row, body, sizing);+ if (admitted.challenge) return;+ const { session } = admitted;+ const promptTokens = promptTokensOf(body);+ const stream = watchStream(res, {+ onClose: ({ outputTokens }) => {+ if (session.settling) return;+ settleMetered(session, { inputTokens: promptTokens, outputTokens, reason: 'client_closed' }).catch((err) =>+ console.error('metered: claim after close failed', err?.message || err),+ );+ },+ });++ const onUsage = async (usage) => {+ const settled = await settleMetered(session, {+ inputTokens: usage.prompt_tokens,+ outputTokens: usage.completion_tokens,+ });+ if (!res.headersSent) {+ res.setHeader('x-payment-response', Buffer.from(JSON.stringify(settled)).toString('base64'));+ }+ return settled;+ };++ try {+ if (clientTools) {+ const chain = providerChain();+ if (!chain.length) {+ await settleMetered(session, { cancel: true, reason: 'no_lane' });+ return openAiError(res, 503, 'llm_unavailable', 'No model lane is configured right now. Try again shortly.');+ }+ await runClientToolCompletion(req, res, body, { chain, tools: clientTools, modelId: INFERENCE_MODEL_ID, onUsage });+ } else {+ await runAgentCompletion(req, res, body, { rateLimited: true, learning: null, onUsage });+ }+ } finally {+ if (!session.settling) {+ const sent = stream.outputTokensSoFar();+ await settleMetered(session, sent > 0+ ? { inputTokens: promptTokens, outputTokens: sent, reason: 'partial' }+ : { cancel: true, reason: 'no_output' }).catch((err) => console.error('metered: final claim failed', err?.message || err));+ }+ }+}+export default wrap(async function handler(req, res) {if (cors(req, res, { methods: 'POST, OPTIONS', credentials: true })) return;if (!method(req, res, ['POST'])) return;@@ -95,7 +173,9 @@ export default wrap(async function handler(req, res) {const caller = await resolveCaller(req);if (caller.error) return openAiError(res, ...caller.error);- const rl = await limits.apiV1(caller.apiKeyId ? `key:${caller.apiKeyId}` : `user:${caller.userId}`);+ const rl = await limits.apiV1(+ caller.anonymous ? `ip:${clientIp(req)}` : caller.apiKeyId ? `key:${caller.apiKeyId}` : `user:${caller.userId}`,+ );setRateLimitHeaders(res, rl);if (!rl.success) return rateLimited(res, rl);@@ -105,10 +185,13 @@ export default wrap(async function handler(req, res) {} catch (err) {return openAiError(res, err?.status || 400, 'bad_json', err?.message || 'Body must be JSON.');}- if (body?.model && !ACCEPTED_MODELS.has(String(body.model))) {+ const modelRow = inferenceModelRow(body?.model);+ if (!modelRow) {return openAiError(res, 404, 'model_not_found', `Model "${body.model}" is not served here. Use "${INFERENCE_MODEL_ID}" (GET /api/v1/models).`);}+ if (caller.anonymous) return handleMetered(req, res, body, modelRow);+const resolved = await resolveAgent(req, body, caller);if (resolved.error) return openAiError(res, ...resolved.error);const agent = resolved.agent;diff --git a/api/v1/models.js b/api/v1/models.jsindex aaa248336..b6f905def 100644--- a/api/v1/models.js+++ b/api/v1/models.js@@ -19,17 +19,18 @@// models needs no key.import { cors, json, method, wrap } from '../_lib/http.js';-import { inferencePricing } from '../_lib/inference-billing.js';+import { INFERENCE_MODEL_ROWS } from '../_lib/pricing/inference-models.js';+import { meteredAvailable } from '../_lib/metered-router.js';+import { USDC_CREDIT_RATE } from '../_lib/pricing/catalog.js';import { listCatalogModels, freeTierAllowance } from '../_lib/model-catalog.js';// Fixed for the life of the model id, so clients that sort or cache by// `created` see a stable value.const CREATED = Math.floor(Date.UTC(2026, 8, 22) / 1000);-function runtimeModel() {- const pricing = inferencePricing();+function runtimeModel(row) {return {- id: pricing.model,+ id: row.id,object: 'model',created: CREATED,owned_by: 'three.ws',@@ -39,11 +40,22 @@ function runtimeModel() {context_messages: 40,tools: 'server-side, read-only',pricing: {- input_usd_per_mtok: pricing.input_usd_per_mtok,- output_usd_per_mtok: pricing.output_usd_per_mtok,- min_call_usd: pricing.min_call_usd,+ input_usd_per_mtok: row.input_usd_per_mtok,+ output_usd_per_mtok: row.output_usd_per_mtok,+ min_call_usd: row.min_call_usd,+ usdc_credit_rate: USDC_CREDIT_RATE,billed_to: 'account credits (https://three.ws/credits)',},+ pay_per_request: {+ enabled: meteredAvailable(),+ protocol: 'x402',+ scheme: 'upto',+ network: 'solana',+ asset: 'USDC',+ max_rounds: row.max_rounds,+ max_output_tokens_round: row.max_output_tokens_round,+ how: 'POST without a key: the 402 carries a cap sized to this request. Sign it, retry, and only the metered tokens are charged; the rest of the cap is refunded.',+ },};}@@ -61,7 +73,7 @@ export default wrap(async (req, res) => {res.setHeader('cache-control', live ? 'no-store' : 'public, max-age=60');return json(res, 200, {object: 'list',- data: [runtimeModel()],+ data: INFERENCE_MODEL_ROWS.map(runtimeModel),agent_models: catalog.models,health_checked_at: catalog.health_checked_at,free_tier: freeTier,diff --git a/data/changelog.json b/data/changelog.jsonindex efc693c4f..dc5a400eb 100644--- a/data/changelog.json+++ b/data/changelog.json@@ -1,6 +1,13 @@{"$comment": "Curated changelog entries for three.ws, the editorial layer of the public changelog. New PAGE launches are tracked automatically via the `added` field in data/pages.json; this file is for everything else holders care about: improvements, fixes, SDK releases, trading/payments capabilities, security work. scripts/build-page-index.mjs merges both sources into CHANGELOG.md, public/changelog.json, and public/changelog.xml. Newest first. Allowed tags: feature, improvement, fix, sdk, infra, docs, security, desktop (desktop entries become the desktop app's release notes). `link` is optional and must be a live three.ws path.","entries": [+ {+ "date": "2026-10-24",+ "title": "Pay for a model request with a wallet, no account needed",+ "summary": "POST /api/v1/chat/completions now answers an unauthenticated request with an x402 upto challenge on Solana, sized to the model's worst case for that request. Sign it, retry, and only the metered tokens are charged at the published per-token price; the rest of the cap is refunded. Streaming settles when the stream closes, and a dropped stream is charged only for the tokens already sent. GET /api/v1/models now lists the price sheet and round limits.",+ "tags": ["feature", "docs"],+ "link": "/docs/metered-router"+ },{"date": "2026-10-24","title": "Skills are scanned for hidden behaviour before they are listed",diff --git a/data/pages.json b/data/pages.jsonindex 262d232ab..9751bd600 100644--- a/data/pages.json+++ b/data/pages.json@@ -5419,6 +5419,14 @@"changefreq": "monthly","added": "2026-10-10"},+ {+ "path": "/docs/metered-router",+ "title": "Docs: Pay-per-request model access",+ "description": "Call the OpenAI-compatible endpoint with a wallet instead of an account: the x402 upto challenge sized to the request, metered settlement, streaming close and dropped-stream behavior, with curl and SDK examples.",+ "priority": 0.7,+ "changefreq": "monthly",+ "added": "2026-10-24"+ },{"path": "/docs/approvals","title": "Docs: Approvals",diff --git a/docs/inference-billing.md b/docs/inference-billing.mdindex 047a28348..4299bed75 100644--- a/docs/inference-billing.md+++ b/docs/inference-billing.md@@ -296,5 +296,8 @@ never a value; keys are encrypted at rest.| `THREE_CREDIT_BONUS_BPS` | no | Bonus credits for paying credits in $THREE, in basis points. Default: no bonus. See [hold-to-access.md](./hold-to-access.md). || `CREDITS_DEPOSIT_WALLET_SOLANA` | yes, for deposits | The platform deposit wallet; falls back to the $THREE treasury wallet. |+No key? A wallet can pay for a single request over x402 instead: see+[metered-router.md](./metered-router.md).+Related: [Payment sessions](./payment-sessions.md), [Approvals](./approvals.md),[Notifications](./notifications.md), [STRUCTURE.md](../STRUCTURE.md).diff --git a/docs/metered-router.md b/docs/metered-router.mdnew file mode 100644index 000000000..f7657e57c--- /dev/null+++ b/docs/metered-router.md@@ -0,0 +1,77 @@+# Pay-per-request model access over x402++`POST https://three.ws/api/v1/chat/completions` is OpenAI-compatible. With an API key it bills the account's credits ([inference-billing.md](./inference-billing.md)). With **no key and no session** a wallet can pay for one request instead, using the x402 `upto` scheme on Solana ([x402-upto.md](./x402-upto.md)). The caller authorizes a cap, three.ws runs the completion, and only the metered tokens are charged. The rest of the cap goes back to the wallet.++| Piece | Source |+|---|---|+| Price table (data, one row per model) | [api/_lib/pricing/inference-models.js](../api/_lib/pricing/inference-models.js) over the published rate in [api/_lib/pricing/catalog.js](../api/_lib/pricing/catalog.js) |+| Cap sizing, admission, settlement, stream watching | [api/_lib/metered-router.js](../api/_lib/metered-router.js) |+| Endpoint | [api/v1/chat/completions.js](../api/v1/chat/completions.js) |+| Price sheet and `pay_per_request` metadata | `GET /api/v1/models` ([api/v1/models.js](../api/v1/models.js)) |+| Tests | [tests/metered-router.test.js](../tests/metered-router.test.js) |++## How a request flows++1. **402.** A request with no `Authorization` header and no session answers `402 Payment Required` with a standard x402 v2 body and `PAYMENT-REQUIRED` header. Its one `upto` accept carries `amount`, the **cap**: the model's worst case for this request.+2. **Sign and retry.** The client signs a channel `open` that deposits the cap and resends the same request with `PAYMENT-SIGNATURE` (or `X-PAYMENT`).+3. **Escrow, then run.** The deposit settles before any model call, so the work is always covered.+4. **Claim.** When the model loop reports its final usage, the claim settles `input_tokens x input price + output_tokens x output price` (never below the model's minimum call, never above the cap). The program pays three.ws that amount and refunds the rest.+5. **Failure or no output.** A completion that produced no token settles a claim of zero: the whole deposit returns.++The cap is `max_rounds` model rounds, each reading your prompt plus the room a round may add (`context_allowance_round`) and writing up to `max_output_tokens_round`. A request that brings its own `tools` is one round bounded by `max_tokens`. A longer prompt means a larger cap. The cap is only a ceiling; you pay for tokens used.++## Streaming++`stream: true` works the same way. The deposit is escrowed before the first byte. The claim is made when the loop reports final usage, which is before the closing frames, so the last `chat.completion.chunk` (with `stream_options: { include_usage: true }`) carries a `billing` object: `paid_via`, `charged_atomics`, `charged_usd`, `refunded_atomics`, `transaction`. If the client drops the connection mid-stream, the claim settles the tokens already sent (counted from the streamed text, plus the prompt) and nothing more. Non-streaming responses carry the same object base64-encoded in the `x-payment-response` header.++## Prices++`GET /api/v1/models` lists each model with `pricing` (USD per million tokens, input and output, and the minimum call) and a `pay_per_request` block (`enabled`, scheme, network, asset, and the round limits that size the cap). Pay-per-request and keyed credits use the same per-token price.++## curl++```sh+curl -i https://three.ws/api/v1/chat/completions \+ -H 'content-type: application/json' \+ -d '{"model":"three-ws/agent","messages":[{"role":"user","content":"Say hello."}],"stream":false}'+```++```+HTTP/2 402+payment-required: eyJ4NDAyVmVyc2lvbiI6Mi...++{"x402Version":2,"error":"Payment required: ...","accepts":[{"scheme":"upto","network":"solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp","asset":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","amount":"50260", ...}]}+```++Signing needs a client library; the curl above shows the challenge. To pay, use the SDK.++## SDK++```js+import { x402Client } from '@x402/core/client';+import { wrapFetchWithPayment } from '@x402/fetch';+import { UptoSvmScheme } from '@x402/svm/upto/client';+import { createKeyPairSignerFromBytes } from '@solana/kit';+import OpenAI from 'openai';++const signer = await createKeyPairSignerFromBytes(secretKeyBytes); // a Solana wallet holding USDC+const client = new x402Client().register('solana:*', new UptoSvmScheme(signer));++const openai = new OpenAI({+ baseURL: 'https://three.ws/api/v1',+ apiKey: 'x402', // unused; the wallet pays+ fetch: wrapFetchWithPayment(fetch, client),+});++const reply = await openai.chat.completions.create({+ model: 'three-ws/agent',+ messages: [{ role: 'user', content: 'Say hello.' }],+});+```++## Operating notes++- Enabled when the deployment runs `upto` (`X402_UPTO_ENABLED=true`, `X402_FEE_PAYER_SECRET_BASE58`, `X402_PAY_TO_SOLANA`, `X402_ASSET_MINT_SOLANA`). Otherwise an unauthenticated request keeps answering `401 missing_api_key`.+- Unauthenticated calls are rate limited per IP. Naming an `agent_id` needs the agent's owner, so it needs a key.+- Every deposit, claim and cancel is written to the x402 audit log under the route `/api/v1/chat/completions`.+- A crash between the deposit and the claim leaves the channel open until the payer's withdraw delay passes; the payer can then withdraw the deposit.diff --git a/docs/x402-upto.md b/docs/x402-upto.mdindex bcc04ff84..49f41e488 100644--- a/docs/x402-upto.md+++ b/docs/x402-upto.md@@ -32,6 +32,8 @@ export default paidEndpoint({`upto` is additive: the `exact` accepts stay in the challenge, so existing clients keep working unchanged. It is advertised only when the deployment opts in (`X402_UPTO_ENABLED=true`, plus the sponsor key and `X402_PAY_TO_SOLANA` / `X402_ASSET_MINT_SOLANA`). It cannot be combined with `streaming` (the body would ship before the charge is known). `api/x402/llm-proxy.js` is the first route converted: 5 atomics per token, at least 500, capped at five times the flat price.+`POST /api/v1/chat/completions` uses the same primitives directly (not through `paidEndpoint`) so it can stream: it escrows the cap, runs the completion, and claims the metered tokens when the stream's usage is final. See [metered-router.md](./metered-router.md).+SIWX is a poor fit for per-call metered routes (a returning wallet is served without paying again), so the llm-proxy route does not enable it. A fixed-price or time-boxed `upto` route can set `siwx` normally.## Buyerdiff --git a/tests/metered-router.test.js b/tests/metered-router.test.jsnew file mode 100644index 000000000..31393a05c--- /dev/null+++ b/tests/metered-router.test.js@@ -0,0 +1,306 @@+// Pay-per-request /api/v1/chat/completions over x402 `upto`, end to end.+//+// Real: the handler, the agent loop, the OpenAI-wire stream reader, the price+// table, the @x402/svm upto client (signs the channel open) and server scheme+// (advertises the offer, signs the claim voucher). Test-controlled: the chain+// (tests/helpers/upto-local-facilitator.js keeps every signature check real and+// replaces only the ledger) and the model upstream, a local HTTP server that+// speaks the real OpenAI chat-completions streaming wire format.++import http from 'node:http';+import { EventEmitter } from 'node:events';+import { Readable } from 'node:stream';++import { generateKeyPairSigner } from '@solana/kit';+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';++import { UptoLocalFacilitator } from './helpers/upto-local-facilitator.js';++vi.mock('@coinbase/x402', () => ({ createCdpAuthHeaders: vi.fn(async () => ({})) }));++let upstreamUrl = '';+vi.mock('../api/_lib/llm-tool-chain.js', async (importOriginal) => {+ const actual = await importOriginal();+ return { ...actual, providerChain: () => [{ name: 'groq', url: upstreamUrl, key: 'k', model: 'local-model' }] };+});+vi.mock('../api/_lib/rate-limit.js', async (importOriginal) => {+ const actual = await importOriginal();+ const ok = async () => ({ success: true, limit: 120, remaining: 119, reset: Date.now() + 1000 });+ return { ...actual, limits: new Proxy(actual.limits, { get: (t, k) => (k === 'apiV1' || k === 'x402VerifyPenalty' ? ok : t[k]) }) };+});+vi.mock('../api/_lib/auth.js', async (importOriginal) => {+ const actual = await importOriginal();+ return { ...actual, getSessionUser: async () => null };+});+vi.mock('../api/_lib/x402/audit-log.js', () => ({ logPaymentEvent: vi.fn() }));+vi.mock('../api/_lib/usage.js', () => ({ recordEvent: vi.fn() }));++const USDC_MAINNET = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';++let handler;+let uptoMod;+let metered;+let table;+let facilitator;+let operator;+let payer;+let server;+let upstreamMode = { kind: 'ok', usage: { prompt_tokens: 1200, completion_tokens: 300 }, deltas: ['Hello ', 'from ', 'the model.'] };+let upstreamHold = null;++function startUpstream() {+ server = http.createServer((req, res) => {+ req.resume();+ req.on('end', async () => {+ if (upstreamMode.kind === 'down') {+ res.writeHead(500, { 'content-type': 'application/json' });+ return res.end(JSON.stringify({ error: { message: 'upstream unavailable' } }));+ }+ res.writeHead(200, { 'content-type': 'text/event-stream' });+ const frame = (delta, extra = {}) =>+ `data: ${JSON.stringify({ id: 'up-1', object: 'chat.completion.chunk', model: 'local-model', choices: [{ index: 0, delta, finish_reason: null }], ...extra })}\n\n`;+ for (const d of upstreamMode.deltas) res.write(frame({ content: d }));+ if (upstreamMode.kind === 'hold') {+ await new Promise((r) => (upstreamHold = r));+ }+ res.write(`data: ${JSON.stringify({ id: 'up-1', object: 'chat.completion.chunk', model: 'local-model', choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] })}\n\n`);+ res.write(`data: ${JSON.stringify({ id: 'up-1', object: 'chat.completion.chunk', model: 'local-model', choices: [], usage: upstreamMode.usage })}\n\n`);+ res.write('data: [DONE]\n\n');+ res.end();+ });+ });+ return new Promise((resolve) =>+ server.listen(0, '127.0.0.1', () => {+ upstreamUrl = `http://127.0.0.1:${server.address().port}/v1/chat/completions`;+ resolve();+ }),+ );+}++function mockReqRes({ headers = {}, body }) {+ const lower = { 'content-type': 'application/json' };+ for (const [k, v] of Object.entries(headers)) lower[k.toLowerCase()] = v;+ const req = Object.assign(new Readable({ read() {} }), {+ method: 'POST',+ url: '/api/v1/chat/completions',+ headers: lower,+ connection: { remoteAddress: '127.0.0.1' },+ socket: { remoteAddress: '127.0.0.1' },+ });+ req.push(JSON.stringify(body));+ req.push(null);+ const chunks = [];+ const resHeaders = {};+ const res = Object.assign(new EventEmitter(), {+ statusCode: 200,+ writableEnded: false,+ headersSent: false,+ setHeader(k, v) {+ resHeaders[k.toLowerCase()] = v;+ },+ getHeader(k) {+ return resHeaders[k.toLowerCase()];+ },+ write(chunk) {+ res.headersSent = true;+ chunks.push(String(chunk));+ return true;+ },+ end(chunk) {+ if (chunk !== undefined) chunks.push(String(chunk));+ res.headersSent = true;+ res.writableEnded = true;+ res.emit('close');+ },+ });+ Object.defineProperties(res, {+ body: { get: () => chunks.join('') },+ headers: { get: () => resHeaders },+ });+ return { req, res };+}++async function sign(accept) {+ const { UptoSvmScheme } = await import('@x402/svm/upto/client');+ const built = await new UptoSvmScheme(payer).createPaymentPayload(2, accept);+ return Buffer.from(JSON.stringify({ x402Version: 2, accepted: accept, payload: built.payload })).toString('base64');+}++async function challengeFor(body) {+ const { req, res } = mockReqRes({ body });+ await handler(req, res);+ expect(res.statusCode).toBe(402);+ const challenge = JSON.parse(res.body);+ return { res, challenge, accept: challenge.accepts.find((a) => a.scheme === 'upto') };+}++const MESSAGES = [{ role: 'user', content: 'Say hello.' }];++beforeAll(async () => {+ process.env.X402_ALLOW_MEMORY_FALLBACK = '1';+ delete process.env.DATABASE_URL;+ operator = await generateKeyPairSigner();+ payer = await generateKeyPairSigner();+ process.env.X402_PAY_TO_SOLANA = (await generateKeyPairSigner()).address;+ process.env.X402_ASSET_MINT_SOLANA = USDC_MAINNET;+ process.env.X402_UPTO_ENABLED = 'true';+ process.env.X402_FEE_PAYER_SECRET_BASE58 = 'unused-because-the-bundle-is-installed';+ const { generatePrivateKey } = await import('viem/accounts');+ process.env.OFFER_RECEIPT_SIGNING_PRIVATE_KEY = generatePrivateKey();++ await startUpstream();++ uptoMod = await import('../api/_lib/x402/upto.js');+ metered = await import('../api/_lib/metered-router.js');+ table = await import('../api/_lib/pricing/inference-models.js');++ const chainState = (await generateKeyPairSigner()).address;+ facilitator = new UptoLocalFacilitator({ feePayerAddress: operator.address });+ const baseExtra = facilitator.getExtra.bind(facilitator);+ facilitator.getExtra = () => ({ ...baseExtra(), recentBlockhash: chainState, lastValidBlockHeight: '1000', recentSlot: '500' });+ const { UptoSvmScheme: ServerScheme } = await import('@x402/svm/upto/server');+ uptoMod.setUptoBundleForTests({+ facilitator,+ server: new ServerScheme({ receiverAuthorizerSigner: operator }),+ signer: operator,+ });++ ({ default: handler } = await import('../api/v1/chat/completions.js'));+});++afterAll(async () => {+ uptoMod?.setUptoBundleForTests(null);+ await new Promise((r) => server.close(r));+});++beforeEach(() => {+ facilitator.events.length = 0;+ upstreamMode = { kind: 'ok', usage: { prompt_tokens: 1200, completion_tokens: 300 }, deltas: ['Hello ', 'from ', 'the model.'] };+});++describe('unauthenticated request', () => {+ it('answers a valid 402 with an upto offer sized to the worst case', async () => {+ const body = { model: 'three-ws/agent', messages: MESSAGES, stream: false };+ const { res, challenge, accept } = await challengeFor(body);+ console.log('402 accepts:\n' + JSON.stringify(challenge.accepts, null, 2));+ expect(res.headers['payment-required']).toBeTruthy();+ expect(challenge.x402Version).toBe(2);+ expect(accept.scheme).toBe('upto');+ expect(accept.network).toMatch(/^solana:/);+ expect(accept.asset).toBe(USDC_MAINNET);+ expect(accept.amount).toBe(String(metered.worstCaseAtomics(table.inferenceModelRow('three-ws/agent'), body)));+ expect(accept.extra.receiverAuthorizer).toBe(operator.address);+ });++ it('sizes the cap to the request: a longer prompt asks for a larger cap', async () => {+ const small = await challengeFor({ messages: MESSAGES });+ const big = await challengeFor({ messages: [{ role: 'user', content: 'x'.repeat(40_000) }] });+ expect(BigInt(big.accept.amount)).toBeGreaterThan(BigInt(small.accept.amount));+ });++ it('refuses naming an agent without an owner', async () => {+ const { req, res } = mockReqRes({ body: { messages: MESSAGES, agent_id: '00000000-0000-4000-8000-000000000000' } });+ await handler(req, res);+ expect(res.statusCode).toBe(401);+ expect(JSON.parse(res.body).error).toBe('sign_in_required');+ });+});++describe('metered settlement', () => {+ it('settles measured tokens times the published price and refunds the rest of the cap', async () => {+ const body = { model: 'three-ws/agent', messages: MESSAGES, stream: false };+ const { accept } = await challengeFor(body);+ const { req, res } = mockReqRes({ body, headers: { 'x-payment': await sign(accept) } });+ await handler(req, res);++ expect(res.statusCode).toBe(200);+ const out = JSON.parse(res.body);+ expect(out.usage.prompt_tokens).toBe(1200);+ expect(out.usage.completion_tokens).toBe(300);++ // 1200 in at 0.5 and 300 out at 2.0 USD per million tokens = 0.0012 USD.+ const row = table.inferenceModelRow('three-ws/agent');+ const expected = BigInt(Math.round(((1200 * row.input_usd_per_mtok + 300 * row.output_usd_per_mtok) / 1e6) * 1e6));+ expect(expected).toBe(1200n);+ const [deposit, claim] = facilitator.events;+ expect(deposit.kind).toBe('deposit');+ expect(deposit.amount).toBe(BigInt(accept.amount));+ expect(claim.kind).toBe('claim');+ expect(claim.paid).toBe(expected);+ console.log('settlement events: ' + JSON.stringify(facilitator.events, (k, v) => (typeof v === 'bigint' ? String(v) : v)));++ const settled = JSON.parse(Buffer.from(res.headers['x-payment-response'], 'base64').toString('utf8'));+ expect(settled.charged_atomics).toBe('1200');+ expect(settled.refunded_atomics).toBe(String(BigInt(accept.amount) - 1200n));+ });++ it('settles on stream close and reports the charge in the usage chunk', async () => {+ const body = { model: 'three-ws/agent', messages: MESSAGES, stream: true, stream_options: { include_usage: true } };+ const { accept } = await challengeFor(body);+ const { req, res } = mockReqRes({ body, headers: { 'x-payment': await sign(accept) } });+ await handler(req, res);++ expect(res.statusCode).toBe(200);+ expect(res.body).toContain('Hello ');+ expect(res.body).toContain('data: [DONE]');+ const claim = facilitator.events.find((e) => e.kind === 'claim');+ expect(claim.paid).toBe(1200n);+ const usageFrame = res.body.split('\n').filter((l) => l.startsWith('data: {')).map((l) => JSON.parse(l.slice(6))).find((f) => f.usage);+ expect(usageFrame.billing.charged_atomics).toBe('1200');+ expect(usageFrame.billing.paid_via).toBe('x402-upto');+ });++ it('charges only the tokens already sent when the client drops the stream', async () => {+ upstreamMode = { kind: 'hold', usage: { prompt_tokens: 5000, completion_tokens: 5000 }, deltas: ['A'.repeat(40)] };+ const body = { model: 'three-ws/agent', messages: MESSAGES, stream: true };+ const { accept } = await challengeFor(body);+ const { req, res } = mockReqRes({ body, headers: { 'x-payment': await sign(accept) } });+ const running = handler(req, res);++ await vi.waitFor(() => expect(res.body).toContain('AAAA'));+ res.emit('close');+ await vi.waitFor(() => expect(facilitator.events.some((e) => e.kind === 'claim')).toBe(true));++ const row = table.inferenceModelRow('three-ws/agent');+ const expected = metered.chargeAtomics(row, metered.promptTokensOf(body), 10);+ const claim = facilitator.events.find((e) => e.kind === 'claim');+ expect(claim.paid).toBe(expected);+ expect(claim.paid).toBeLessThan(5000n);++ upstreamHold?.();+ await running;+ expect(facilitator.events.filter((e) => e.kind === 'claim')).toHaveLength(1);+ });++ it('returns the whole deposit when the completion fails before any token', async () => {+ upstreamMode = { kind: 'down', deltas: [] };+ const body = { model: 'three-ws/agent', messages: MESSAGES, stream: false };+ const { accept } = await challengeFor(body);+ const { req, res } = mockReqRes({ body, headers: { 'x-payment': await sign(accept) } });+ await handler(req, res);+ expect(res.statusCode).toBeGreaterThanOrEqual(500);+ expect(facilitator.events.map((e) => e.kind)).toEqual(['deposit', 'cancel']);+ });++ it('never charges above the cap', () => {+ const row = table.inferenceModelRow('three-ws/agent');+ const cap = metered.worstCaseAtomics(row, { messages: MESSAGES });+ expect(uptoMod.normaliseCharge(metered.chargeAtomics(row, 10_000_000, 10_000_000), cap)).toBe(cap);+ });+});++describe('deployment without upto', () => {+ it('keeps answering 401 missing_api_key when pay-per-request is not enabled', async () => {+ const saved = process.env.X402_UPTO_ENABLED;+ process.env.X402_UPTO_ENABLED = 'false';+ uptoMod.setUptoBundleForTests(null);+ try {+ const { req, res } = mockReqRes({ body: { messages: MESSAGES } });+ await handler(req, res);+ expect(res.statusCode).toBe(401);+ expect(JSON.parse(res.body).error).toBe('missing_api_key');+ } finally {+ process.env.X402_UPTO_ENABLED = saved;+ }+ });+});