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): agents pay for their own model calls from their wallet, with per-agent budgets
qhqfd683a4771afe
diff --git a/api/_lib/inference-billing.js b/api/_lib/inference-billing.jsnew file mode 100644index 000000000..b081ac4ad--- /dev/null+++ b/api/_lib/inference-billing.js@@ -0,0 +1,531 @@+// Inference billing: model calls paid from account credits, capped per agent.+//+// The account's prepaid credits (api/_lib/credits.js, USD-denominated) are the+// one balance every model call on the metered endpoint draws from. An agent's+// wallet refills that balance (api/_lib/inference-topup.js), and an agent's+// owner can cap what its model calls may burn with a daily and a monthly+// inference budget (meta.inference_budget, set through PATCH /api/agents/:id).+//+// Three primitives, used by every metered model-call site:+//+// assertInferenceAllowed() BEFORE the call. Refuses with a typed 402 when+// the account is out of credits or the agent's+// budget is spent. The first refusal in a window+// stops the agent's automations and notifies the+// owner, so nothing keeps failing silently.+// chargeInference() AFTER the call. Prices the tokens at the+// published rate and debits one idempotent ledger+// row (action 'inference.agent', ref_type 'agent').+// inferenceUsage() The read model behind /api/me/usage, the agent+// credits tile and three://agents/{id}/usage.+//+// The budget is judged on spend already booked: a call that starts under the+// budget runs to completion and is charged in full. The next call is the one+// that refuses. That keeps a streamed answer from being cut mid-sentence while+// still guaranteeing the budget can be exceeded by at most one call.++import { sql } from './db.js';+import { getCreditAccount, debitCredits } from './credits.js';+import {+ INFERENCE_USD_PER_MTOK,+ INFERENCE_MIN_CALL_USD,+ USDC_CREDIT_RATE,+} from './pricing/catalog.js';+import { insertNotification } from './notify.js';+import { logAudit } from './audit.js';++export const INFERENCE_ACTION = 'inference.agent';+export const INFERENCE_MODEL_ID = 'three-ws/agent';++// A call is admitted only while the balance covers at least this much, so the+// post-call charge almost never finds the account empty.+export const MIN_BALANCE_TO_CALL_USD = 0.001;++// Upper bound on a budget value, far above any real daily model spend. It keeps+// a typo (an extra few zeros) from reading as "unlimited".+const MAX_BUDGET_USD = 100_000;++export class InferenceBillingError extends Error {+ constructor(status, code, message, detail = {}) {+ super(message);+ this.status = status;+ this.code = code;+ this.detail = detail;+ this.expose = true;+ }+}++// ── pricing ─────────────────────────────────────────────────────────────────++/** Rough token count (about 4 characters per token) for text or JSON-able values. */+export function estimateTokens(value) {+ if (value == null) return 0;+ const text = typeof value === 'string' ? value : JSON.stringify(value);+ return Math.ceil(text.length / 4);+}++/**+ * Price one model call at the published rate. Rounded UP to the micro-dollar+ * so the ledger never undercharges, and never below INFERENCE_MIN_CALL_USD.+ */+export function priceInference({ inputTokens = 0, outputTokens = 0 } = {}) {+ const input = Math.max(0, Number(inputTokens) || 0);+ const output = Math.max(0, Number(outputTokens) || 0);+ const raw = (input * INFERENCE_USD_PER_MTOK.input + output * INFERENCE_USD_PER_MTOK.output) / 1e6;+ const micro = Math.ceil(raw * 1e6 - 1e-9);+ return Math.max(INFERENCE_MIN_CALL_USD, micro / 1e6);+}++/** The published price sheet, for /api/v1/models, docs and the UI. */+export function inferencePricing() {+ return {+ model: INFERENCE_MODEL_ID,+ currency: 'USD',+ 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,+ usdc_credit_rate: USDC_CREDIT_RATE,+ topup_fee_usd: 0,+ };+}++// ── budgets ─────────────────────────────────────────────────────────────────++function budgetValue(v, field) {+ if (v === null || v === undefined || v === '') return null;+ const n = Number(v);+ if (!Number.isFinite(n) || n <= 0) {+ throw new InferenceBillingError(400, 'validation_error', `inferenceBudget.${field} must be a positive number of credits (USD), or null to remove it`);+ }+ if (n > MAX_BUDGET_USD) {+ throw new InferenceBillingError(400, 'validation_error', `inferenceBudget.${field} cannot exceed ${MAX_BUDGET_USD} credits`);+ }+ return Math.round(n * 1e6) / 1e6;+}++/**+ * Validate a client-supplied budget. Accepts `{ daily, monthly }` or+ * `{ daily_usd, monthly_usd }`; `null` (or both fields empty) clears it.+ * @returns {{ daily_usd: number|null, monthly_usd: number|null }|null}+ * @throws {InferenceBillingError} 400 on a malformed value+ */+export function normalizeInferenceBudget(raw) {+ if (raw === null) return null;+ if (typeof raw !== 'object' || Array.isArray(raw)) {+ throw new InferenceBillingError(400, 'validation_error', 'inferenceBudget must be an object like { "daily": 1, "monthly": 20 } or null');+ }+ const daily = budgetValue(raw.daily ?? raw.daily_usd, 'daily');+ const monthly = budgetValue(raw.monthly ?? raw.monthly_usd, 'monthly');+ if (daily == null && monthly == null) return null;+ if (daily != null && monthly != null && daily > monthly) {+ throw new InferenceBillingError(400, 'validation_error', 'inferenceBudget.daily cannot be larger than inferenceBudget.monthly');+ }+ return { daily_usd: daily, monthly_usd: monthly };+}++/** The stored budget on an agent's meta, or null when none is set. */+export function getInferenceBudget(meta) {+ const b = meta?.inference_budget;+ if (!b || typeof b !== 'object') return null;+ const daily = Number(b.daily_usd);+ const monthly = Number(b.monthly_usd);+ const out = {+ daily_usd: Number.isFinite(daily) && daily > 0 ? daily : null,+ monthly_usd: Number.isFinite(monthly) && monthly > 0 ? monthly : null,+ };+ return out.daily_usd == null && out.monthly_usd == null ? null : out;+}++/** UTC window keys: the day and the month a budget window is judged in. */+export function windowKeys(now = new Date()) {+ const iso = now.toISOString();+ return { day: iso.slice(0, 10), month: iso.slice(0, 7) };+}++/**+ * Merge a validated budget into an agent's meta. Changing the budget clears a+ * recorded exhaustion, so raising it is all an owner has to do to recover.+ */+export function applyInferenceBudget(meta, budget) {+ const next = { ...(meta || {}) };+ if (budget == null) {+ delete next.inference_budget;+ return next;+ }+ next.inference_budget = {+ daily_usd: budget.daily_usd,+ monthly_usd: budget.monthly_usd,+ updated_at: new Date().toISOString(),+ };+ return next;+}++/** Inference credits an agent has burned today and this month (UTC). */+export async function agentInferenceSpend(agentId) {+ const [row] = await sql`+ SELECT+ COALESCE(SUM(-amount_usd) FILTER (+ WHERE created_at >= (date_trunc('day', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC')+ ), 0)::float8 AS today,+ COALESCE(SUM(-amount_usd), 0)::float8 AS month,+ COUNT(*) FILTER (+ WHERE created_at >= (date_trunc('day', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC')+ )::int AS calls_today+ FROM credit_ledger+ WHERE action = ${INFERENCE_ACTION} AND ref_type = 'agent' AND ref_id = ${String(agentId)}+ AND created_at >= (date_trunc('month', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC')+ `;+ return {+ today_usd: round6(row?.today),+ month_usd: round6(row?.month),+ calls_today: Number(row?.calls_today || 0),+ };+}++function round6(n) {+ return Math.round((Number(n) || 0) * 1e6) / 1e6;+}++/** Which budget window (if any) the current spend has used up. */+export function exhaustedWindow(budget, spend) {+ if (!budget) return null;+ if (budget.daily_usd != null && spend.today_usd >= budget.daily_usd - 1e-9) return 'daily';+ if (budget.monthly_usd != null && spend.month_usd >= budget.monthly_usd - 1e-9) return 'monthly';+ return null;+}++// ── the pre-call gate ───────────────────────────────────────────────────────++/**+ * Admit or refuse one model call.+ *+ * @param {object} p+ * @param {string} p.userId the account whose credits pay+ * @param {object|null} [p.agent] { id, name, meta, user_id } when the call runs for an agent+ * @returns {Promise<{ balanceUsd: number, budget: object|null, spend: object|null }>}+ * @throws {InferenceBillingError} 402 insufficient_credits | inference_budget_exhausted+ */+export async function assertInferenceAllowed({ userId, agent = null }) {+ const acct = await getCreditAccount(userId);+ if (acct.balanceUsd < MIN_BALANCE_TO_CALL_USD) {+ throw new InferenceBillingError(+ 402,+ 'insufficient_credits',+ 'This account is out of credits. Top up from an agent wallet (POST /api/agents/:id/credits/topup/preview) or at https://three.ws/credits, then retry.',+ {+ balance_usd: acct.balanceUsd,+ recover: agent+ ? { action: 'topup', method: 'POST', path: `/api/agents/${agent.id}/credits/topup/preview` }+ : { action: 'topup', url: 'https://three.ws/credits' },+ },+ );+ }+ if (!agent) return { balanceUsd: acct.balanceUsd, budget: null, spend: null };++ const budget = getInferenceBudget(agent.meta);+ if (!budget) return { balanceUsd: acct.balanceUsd, budget: null, spend: null };++ const spend = await agentInferenceSpend(agent.id);+ const window = exhaustedWindow(budget, spend);+ if (window) {+ const limit = window === 'daily' ? budget.daily_usd : budget.monthly_usd;+ const spent = window === 'daily' ? spend.today_usd : spend.month_usd;+ const stopped = await recordBudgetExhausted({ agent, userId, window, limit, spent });+ throw new InferenceBillingError(+ 402,+ 'inference_budget_exhausted',+ `${agent.name || 'This agent'} has used its ${window} inference budget ($${spent.toFixed(4)} of $${limit.toFixed(4)}). Raise inferenceBudget.${window === 'daily' ? 'daily' : 'monthly'} with PATCH /api/agents/${agent.id}, or wait for the ${window === 'daily' ? 'next UTC day' : 'next UTC month'}.`,+ {+ agent_id: agent.id,+ window,+ budget_usd: limit,+ spent_usd: spent,+ automations_stopped: stopped,+ resets_at: nextReset(window),+ recover: {+ action: 'raise_budget',+ method: 'PATCH',+ path: `/api/agents/${agent.id}`,+ body: { inferenceBudget: { [window === 'daily' ? 'daily' : 'monthly']: round6(limit * 2) } },+ },+ },+ );+ }+ return { balanceUsd: acct.balanceUsd, budget, spend };+}++function nextReset(window, now = new Date()) {+ if (window === 'daily') {+ return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1)).toISOString();+ }+ return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1)).toISOString();+}++/**+ * Record the first refusal in a window, exactly once: stamp the exhaustion on+ * the agent, stop its automations (agent status 'stopped', autopilot off) and+ * notify the owner. A second refusal in the same window changes nothing.+ * @returns {Promise<boolean>} whether the agent's automations are stopped+ */+async function recordBudgetExhausted({ agent, userId, window, limit, spent }) {+ const keys = windowKeys();+ const key = window === 'daily' ? keys.day : keys.month;+ const stamp = { window, key, at: new Date().toISOString(), budget_usd: limit, spent_usd: spent };++ // The WHERE clause is the once-per-window latch: only the request that flips+ // the stamp gets a row back, so concurrent refusals notify exactly once.+ const [won] = await sql`+ UPDATE agent_identities+ SET meta = jsonb_set(+ jsonb_set(+ COALESCE(meta, '{}'::jsonb),+ '{inference_budget,exhausted}',+ ${JSON.stringify(stamp)}::jsonb,+ true+ ),+ '{autopilot,enabled}',+ 'false'::jsonb,+ COALESCE(meta ? 'autopilot', false)+ ),+ updated_at = now()+ WHERE id = ${agent.id}+ AND meta ? 'inference_budget'+ AND COALESCE(meta #>> '{inference_budget,exhausted,key}', '') <> ${key}+ RETURNING id+ `;+ if (!won) return true;++ const stopped = await stopAgentAutomations(agent.id);+ insertNotification(userId, 'inference_budget_exhausted', {+ agent_id: agent.id,+ agent_name: agent.name || null,+ window,+ budget_usd: limit,+ spent_usd: spent,+ automations_stopped: stopped,+ link: `/agent/${agent.id}#credits`,+ });+ logAudit({+ userId,+ action: 'inference.budget_exhausted',+ resourceId: agent.id,+ meta: { window, budget_usd: limit, spent_usd: spent, automations_stopped: stopped },+ });+ return stopped;+}++/**+ * Put the agent in the 'stopped' lifecycle state, which pauses its scheduled+ * automations, wallet intents and runs without deleting anything. Returns false+ * when the lifecycle column is not in this database yet (the automations+ * engine that reads it ships in the same release), so the refusal still lands.+ */+async function stopAgentAutomations(agentId) {+ try {+ await sql`+ UPDATE agent_identities+ SET status = 'stopped', status_changed_at = now(),+ meta = jsonb_set(meta, '{inference_budget,exhausted,stopped_agent}', 'true'::jsonb, true)+ WHERE id = ${agentId} AND status = 'running'+ `;+ return true;+ } catch (err) {+ if (err?.code === '42703') return false;+ throw err;+ }+}++/**+ * Resume an agent this module stopped, once its owner has changed the budget.+ * Only an agent whose stop was recorded as ours is restarted; an agent the+ * owner stopped by hand stays stopped.+ */+export async function resumeAfterBudgetChange(agentId, previousMeta) {+ if (previousMeta?.inference_budget?.exhausted?.stopped_agent !== true) return false;+ try {+ const rows = await sql`+ UPDATE agent_identities SET status = 'running', status_changed_at = now()+ WHERE id = ${agentId} AND status = 'stopped'+ RETURNING id+ `;+ return rows.length > 0;+ } catch (err) {+ if (err?.code === '42703') return false;+ throw err;+ }+}++// ── the post-call charge ────────────────────────────────────────────────────++/**+ * Debit one model call. Idempotent on `callId`. When the balance cannot cover+ * the full price (the call was admitted with a thin balance), the remaining+ * balance is taken instead and the shortfall reported, never a negative balance.+ *+ * @returns {Promise<{ chargedUsd: number, pricedUsd: number, balanceUsd: number, shortfallUsd: number, replay: boolean }>}+ */+export async function chargeInference({+ userId,+ agentId = null,+ apiKeyId = null,+ callId,+ inputTokens,+ outputTokens,+ estimated = false,+ provider = null,+ model = null,+}) {+ const pricedUsd = priceInference({ inputTokens, outputTokens });+ const meta = {+ model: INFERENCE_MODEL_ID,+ agent_id: agentId,+ api_key_id: apiKeyId,+ input_tokens: inputTokens,+ output_tokens: outputTokens,+ estimated,+ lane: provider,+ lane_model: model,+ };+ const base = {+ userId,+ action: INFERENCE_ACTION,+ refType: agentId ? 'agent' : 'account',+ refId: agentId ? String(agentId) : apiKeyId ? String(apiKeyId) : null,+ idempotencyKey: `inference:${callId}`,+ meta,+ };+ try {+ const r = await debitCredits({ ...base, amountUsd: pricedUsd });+ return { chargedUsd: r.chargedUsd, pricedUsd, balanceUsd: r.balanceUsd, shortfallUsd: 0, replay: r.replay };+ } catch (err) {+ if (err?.code !== 'insufficient_credits') throw err;+ const available = Number(err.available_usd) || 0;+ if (available <= 0) {+ return { chargedUsd: 0, pricedUsd, balanceUsd: 0, shortfallUsd: pricedUsd, replay: false };+ }+ const r = await debitCredits({+ ...base,+ amountUsd: available,+ meta: { ...meta, priced_usd: pricedUsd, shortfall_usd: round6(pricedUsd - available) },+ });+ return {+ chargedUsd: r.chargedUsd,+ pricedUsd,+ balanceUsd: r.balanceUsd,+ shortfallUsd: round6(pricedUsd - available),+ replay: r.replay,+ };+ }+}++// ── the read model ──────────────────────────────────────────────────────────++/**+ * Credits, burn rate, days remaining and recent top-ups, for the whole account+ * or one agent. Burn rate is the trailing seven-day average of inference spend.+ */+export async function inferenceUsage({ userId, agent = null }) {+ const agentId = agent?.id ?? null;+ const [acct, burnRow, topups, monthRow] = await Promise.all([+ getCreditAccount(userId),+ sql`+ SELECT COALESCE(SUM(-amount_usd), 0)::float8 AS spent7,+ COUNT(*)::int AS calls7+ FROM credit_ledger+ WHERE user_id = ${userId} AND action = ${INFERENCE_ACTION}+ AND (${agentId}::text IS NULL OR (ref_type = 'agent' AND ref_id = ${agentId ? String(agentId) : null}))+ AND created_at > now() - interval '7 days'+ `,+ sql`+ SELECT id, agent_id, source, status, amount_usdc, credits_usd, signature, error,+ created_at, settled_at+ FROM inference_topups+ WHERE user_id = ${userId}+ AND status IN ('settled', 'pending', 'failed', 'executing')+ AND (${agentId}::uuid IS NULL OR agent_id = ${agentId})+ ORDER BY created_at DESC+ LIMIT 10+ `,+ sql`+ SELECT COALESCE(SUM(-amount_usd), 0)::float8 AS spent,+ COUNT(*)::int AS calls,+ COALESCE(SUM((meta->>'input_tokens')::bigint), 0)::bigint AS input_tokens,+ COALESCE(SUM((meta->>'output_tokens')::bigint), 0)::bigint AS output_tokens+ FROM credit_ledger+ WHERE user_id = ${userId} AND action = ${INFERENCE_ACTION}+ AND (${agentId}::text IS NULL OR (ref_type = 'agent' AND ref_id = ${agentId ? String(agentId) : null}))+ AND created_at >= (date_trunc('month', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC')+ `,+ ]);++ const spent7 = Number(burnRow[0]?.spent7 || 0);+ const burnPerDay = round6(spent7 / 7);+ const out = {+ balance_usd: acct.balanceUsd,+ lifetime_deposited_usd: acct.lifetimeDepositedUsd,+ lifetime_spent_usd: acct.lifetimeSpentUsd,+ burn_rate_usd_per_day: burnPerDay,+ days_remaining: burnPerDay > 0 ? Math.floor((acct.balanceUsd / burnPerDay) * 10) / 10 : null,+ inference_month: {+ spent_usd: round6(monthRow[0]?.spent),+ calls: Number(monthRow[0]?.calls || 0),+ input_tokens: Number(monthRow[0]?.input_tokens || 0),+ output_tokens: Number(monthRow[0]?.output_tokens || 0),+ },+ calls_7d: Number(burnRow[0]?.calls7 || 0),+ pricing: inferencePricing(),+ topups: topups.map((t) => ({+ id: t.id,+ agent_id: t.agent_id,+ source: t.source,+ status: t.status,+ amount_usdc: Number(t.amount_usdc),+ credits_usd: Number(t.credits_usd),+ signature: t.signature,+ explorer_url: t.signature ? `https://solscan.io/tx/${t.signature}` : null,+ error: t.error,+ created_at: t.created_at,+ settled_at: t.settled_at,+ })),+ };++ if (agent) {+ const budget = getInferenceBudget(agent.meta);+ const spend = await agentInferenceSpend(agent.id);+ const window = exhaustedWindow(budget, spend);+ out.agent = {+ id: agent.id,+ name: agent.name || null,+ budget,+ spend,+ exhausted: window+ ? { window, resets_at: nextReset(window), stopped: agent.meta?.inference_budget?.exhausted?.stopped_agent === true }+ : null,+ };+ out.auto_fund = await autoFundIntent(agent.id);+ }+ return out;+}++/** The agent's credits_below / fund_inference rule, as the UI toggle shows it. */+export async function autoFundIntent(agentId) {+ const [row] = await sql`+ SELECT id, enabled, trigger_config, action_config, limits, last_fired_at, last_status, last_note, last_signature+ FROM agent_wallet_intents+ WHERE agent_id = ${agentId} AND trigger_type = 'credits_below' AND action_type = 'fund_inference'+ ORDER BY created_at DESC+ LIMIT 1+ `;+ if (!row) return null;+ return {+ intent_id: row.id,+ enabled: row.enabled,+ threshold_usd: Number(row.trigger_config?.threshold_usd ?? 0),+ amount_usdc: Number(row.action_config?.amount_usdc ?? 0),+ limits: row.limits || {},+ last_fired_at: row.last_fired_at,+ last_status: row.last_status,+ last_note: row.last_note,+ last_signature: row.last_signature,+ };+}diff --git a/api/_lib/inference-topup.js b/api/_lib/inference-topup.jsnew file mode 100644index 000000000..afa12bb7b--- /dev/null+++ b/api/_lib/inference-topup.js@@ -0,0 +1,527 @@+// Wallet-funded credit top-ups: an agent pays for its own inference.+//+// Moves USDC from an agent's custodial Solana wallet to the platform treasury+// and credits the owner's account at the published rate (USDC_CREDIT_RATE, no+// fee). The transfer is a standard x402 `exact` payment: the agent wallet signs+// one USDC TransferChecked to the treasury, and the in-house self-facilitator+// (api/_lib/x402/self-facilitator.js) validates it, co-signs as fee payer and+// broadcasts it. The agent therefore needs USDC only, never SOL for fees, and+// no third party touches the settlement.+//+// Every top-up is guarded exactly like any other outbound agent spend:+// • reserveSpendUsd() claims a pending custody row under the agent's per-tx+// and daily ceilings, the natural-language policy, the kill switch and the+// behavioural anomaly freeze, BEFORE the key is touched;+// • the custody row is finalized with the on-chain signature, so the top-up+// appears in the owner's audit feed and counts toward the daily cap;+// • the credit_ledger 'deposit' row carries the same signature, and is+// idempotent on the top-up id, so a retry never credits twice.+//+// Owner and provisioning flows are two-step: previewTopup() writes a+// single-use preview (recipient, amount, token, chain, credits) that expires in+// ten minutes, and executeTopup() requires `confirm_deposit: true` plus that+// fresh preview_id. An armed wallet intent (source 'intent') is itself the+// owner's standing authorization and calls topupFromIntent() directly.++import { PublicKey } from '@solana/web3.js';+import { getAssociatedTokenAddressSync, TOKEN_PROGRAM_ID } from '@solana/spl-token';++import { sql } from './db.js';+import { env } from './env.js';+import { creditAccount, getCreditAccount } from './credits.js';+import { USDC_CREDIT_RATE } from './pricing/catalog.js';+import { getSolanaAddressBalances, recoverSolanaAgentKeypair } from './agent-wallet.js';+import {+ enforceSpendLimit,+ reserveSpendUsd,+ releaseSpendReservation,+ updateCustodyEvent,+ SpendLimitError,+} from './agent-trade-guards.js';+import { NETWORK_SOLANA_MAINNET } from './x402/solana-networks.js';+import { bootstrapSolanaContext, buildPaymentTx, nextAutoNonce } from './x402/pay.js';+import { loadFeePayerKeypair, settleRingPayment } from './x402/self-facilitator.js';+import { facilitatorFeeMeter, recordSettledFee } from './x402/wallet-fee-meter.js';+import { claimSettleCredit } from './x402/settle-credit.js';+import { PENDING_SCOPE_FACILITATOR, SqlPendingSettlementStore } from './x402/pending-settlements.js';+import { insertNotification } from './notify.js';+import { logAudit } from './audit.js';++export const TOPUP_MIN_USDC = 0.1;+export const TOPUP_MAX_USDC = 1000;+export const PREVIEW_TTL_MINUTES = 10;+export const CUSTODY_CATEGORY = 'inference_topup';++const USDC_DECIMALS = 6;++export class TopupError extends Error {+ constructor(status, code, message, detail = {}) {+ super(message);+ this.status = status;+ this.code = code;+ this.detail = detail;+ this.expose = true;+ }+}++/** Validate and normalize a USDC amount to 6 decimals. */+export function normalizeTopupAmount(raw) {+ const n = Number(raw);+ if (!Number.isFinite(n) || n <= 0) {+ throw new TopupError(400, 'validation_error', 'amount_usdc must be a positive number');+ }+ const rounded = Math.floor(n * 10 ** USDC_DECIMALS) / 10 ** USDC_DECIMALS;+ if (rounded < TOPUP_MIN_USDC) {+ throw new TopupError(400, 'validation_error', `the smallest top-up is ${TOPUP_MIN_USDC} USDC`);+ }+ if (rounded > TOPUP_MAX_USDC) {+ throw new TopupError(400, 'validation_error', `the largest single top-up is ${TOPUP_MAX_USDC} USDC`);+ }+ return rounded;+}++/** Credits a top-up buys at the published rate. No fee is taken. */+export function creditsForUsdc(amountUsdc) {+ return Math.floor(Number(amountUsdc) * USDC_CREDIT_RATE * 1e6) / 1e6;+}++function treasuryAddress() {+ const addr = env.X402_PAY_TO_SOLANA;+ if (!addr) {+ throw new TopupError(503, 'treasury_unconfigured', 'Wallet top-ups are unavailable: the platform treasury address is not configured.');+ }+ return addr;+}++function usdcMint() {+ const mint = env.X402_ASSET_MINT_SOLANA;+ if (!mint) {+ throw new TopupError(503, 'usdc_unconfigured', 'Wallet top-ups are unavailable: the USDC mint is not configured.');+ }+ return mint;+}++/** The sponsor fee payer, or null when this deployment has none (self-pay). */+function sponsorOrNull() {+ try {+ return loadFeePayerKeypair();+ } catch {+ return null;+ }+}++async function loadOwnedAgent(agentId, userId) {+ const [row] = await sql`+ SELECT id, user_id, name, meta FROM agent_identities+ WHERE id = ${agentId} AND deleted_at IS NULL+ `;+ if (!row) throw new TopupError(404, 'not_found', 'agent not found');+ if (String(row.user_id) !== String(userId)) throw new TopupError(403, 'forbidden', 'not your agent');+ const meta = row.meta || {};+ if (!meta.solana_address || !meta.encrypted_solana_secret) {+ throw new TopupError(409, 'wallet_not_ready', 'This agent has no signable Solana wallet yet. Open its wallet page to provision one.');+ }+ return { ...row, meta };+}++function spendLimitToTopupError(e) {+ return new TopupError(403, e.code || 'spend_limit', e.message, e.detail || {});+}++// ── preview ─────────────────────────────────────────────────────────────────++/**+ * Write a single-use preview of a wallet-funded top-up. Nothing moves.+ * @returns {Promise<object>} the confirmation table the owner must approve+ */+export async function previewTopup({ userId, agentId, amountUsdc, source = 'owner' }) {+ const amount = normalizeTopupAmount(amountUsdc);+ const agent = await loadOwnedAgent(agentId, userId);+ const payTo = treasuryAddress();+ const mint = usdcMint();++ const balances = await getSolanaAddressBalances(agent.meta.solana_address, 'mainnet');+ if (balances.usdc == null) {+ throw new TopupError(503, 'rpc_unavailable', 'Could not read the agent wallet balance from Solana. Retry in a moment.');+ }+ if (balances.usdc + 1e-9 < amount) {+ throw new TopupError(402, 'insufficient_usdc', `The agent wallet holds ${balances.usdc} USDC, less than the ${amount} USDC requested. Fund the wallet first.`, {+ wallet_usdc: balances.usdc,+ requested_usdc: amount,+ deposit_address: agent.meta.solana_address,+ });+ }++ // Fail fast on the owner's own policy (freeze, per-tx cap, English rules)+ // so a preview never shows a top-up the guard would refuse. The binding+ // check is the atomic reserve at execution time.+ try {+ await enforceSpendLimit({+ agentId: agent.id,+ meta: agent.meta,+ userId,+ category: CUSTODY_CATEGORY,+ usdValue: amount,+ asset: 'USDC',+ destination: payTo,+ });+ } catch (e) {+ if (e instanceof SpendLimitError) throw spendLimitToTopupError(e);+ throw e;+ }++ const sponsor = sponsorOrNull();+ if (!sponsor && !(balances.sol > 0.00001)) {+ throw new TopupError(409, 'no_fee_payer', 'The agent wallet needs a little SOL (0.00001) to pay the network fee on this deployment.');+ }++ const credits = creditsForUsdc(amount);+ const acct = await getCreditAccount(userId);+ const [row] = await sql`+ INSERT INTO inference_topups+ (user_id, agent_id, source, status, amount_usdc, credits_usd, payer_address, pay_to, network, expires_at)+ VALUES+ (${userId}, ${agent.id}, ${source}, 'previewed', ${amount.toFixed(6)}, ${credits.toFixed(6)},+ ${agent.meta.solana_address}, ${payTo}, 'mainnet', now() + make_interval(mins => ${PREVIEW_TTL_MINUTES}))+ RETURNING id, expires_at+ `;++ return {+ preview_id: row.id,+ expires_at: row.expires_at,+ confirm_flag: 'confirm_deposit',+ agent: { id: agent.id, name: agent.name },+ from: agent.meta.solana_address,+ to: payTo,+ to_label: 'three.ws treasury',+ token: 'USDC',+ mint,+ chain: 'solana',+ network: 'mainnet',+ amount_usdc: amount,+ rate: USDC_CREDIT_RATE,+ fee_usd: 0,+ credits_usd: credits,+ network_fee: sponsor ? 'paid by three.ws' : 'about 0.000005 SOL from the agent wallet',+ wallet_usdc_before: balances.usdc,+ wallet_usdc_after: Math.round((balances.usdc - amount) * 1e6) / 1e6,+ balance_before_usd: acct.balanceUsd,+ balance_after_usd: Math.round((acct.balanceUsd + credits) * 1e6) / 1e6,+ };+}++// ── execute ─────────────────────────────────────────────────────────────────++function rowResult(row, extra = {}) {+ return {+ topup_id: row.id,+ status: row.status,+ agent_id: row.agent_id,+ amount_usdc: Number(row.amount_usdc),+ credits_usd: Number(row.credits_usd),+ signature: row.signature || null,+ explorer_url: row.signature ? `https://solscan.io/tx/${row.signature}` : null,+ api_key_id: row.api_key_id || null,+ ...extra,+ };+}++/**+ * Execute a previewed top-up. Requires `confirmDeposit === true` and a fresh,+ * unused preview owned by the caller. Retrying a settled or pending preview is+ * safe: it returns the recorded result or reconciles the recorded signature.+ */+export async function executeTopup({ userId, previewId, confirmDeposit, sources = ['owner'] }) {+ if (confirmDeposit !== true) {+ throw new TopupError(400, 'confirm_required', 'Moving funds needs confirm_deposit: true together with a preview_id from the matching /preview call. Show the preview to the owner first.');+ }+ if (!previewId) {+ throw new TopupError(400, 'preview_required', 'preview_id is required: call the matching /preview route first.');+ }+ const [row] = await sql`SELECT * FROM inference_topups WHERE id = ${previewId} AND user_id = ${userId}`;+ if (!row || !sources.includes(row.source)) {+ throw new TopupError(404, 'preview_not_found', 'No preview with that id belongs to this account. Create a new one with /preview.');+ }+ if (row.status === 'settled') return rowResult(row, { replay: true });+ if (row.status === 'pending') return reconcileTopup(row);+ if (row.status === 'failed' || row.status === 'expired') {+ throw new TopupError(409, 'preview_used', `This preview already ${row.status === 'failed' ? `failed (${row.error || 'settlement failed'})` : 'expired'}. Create a new one with /preview.`);+ }+ if (row.status === 'executing') {+ throw new TopupError(409, 'in_flight', 'This top-up is already being settled. Retry in a few seconds to read its result.');+ }++ const [claimed] = await sql`+ UPDATE inference_topups SET status = 'executing', executed_at = now()+ WHERE id = ${previewId} AND status = 'previewed' AND expires_at > now()+ RETURNING *+ `;+ if (!claimed) {+ await sql`UPDATE inference_topups SET status = 'expired' WHERE id = ${previewId} AND status = 'previewed' AND expires_at <= now()`;+ throw new TopupError(410, 'preview_expired', `Previews are valid for ${PREVIEW_TTL_MINUTES} minutes. Create a new one with /preview and confirm it.`);+ }+ return runTopup(claimed);+}++/**+ * Fire a top-up from an armed wallet intent. Idempotent per `idempotencyKey`,+ * which the intent engine derives from the rule and its window, so a rule+ * tops up at most once per window however often the sweep runs.+ */+export async function topupFromIntent({ agentId, ownerId, amountUsdc, intentId, idempotencyKey }) {+ const amount = normalizeTopupAmount(amountUsdc);+ const agent = await loadOwnedAgent(agentId, ownerId);+ const payTo = treasuryAddress();+ const credits = creditsForUsdc(amount);+ const [row] = await sql`+ INSERT INTO inference_topups+ (user_id, agent_id, source, status, amount_usdc, credits_usd, payer_address, pay_to,+ network, intent_id, idempotency_key, executed_at)+ VALUES+ (${ownerId}, ${agent.id}, 'intent', 'executing', ${amount.toFixed(6)}, ${credits.toFixed(6)},+ ${agent.meta.solana_address}, ${payTo}, 'mainnet', ${intentId}, ${idempotencyKey}, now())+ ON CONFLICT (idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING+ RETURNING *+ `;+ if (!row) return { status: 'skipped', note: 'already topped up in this window' };+ return runTopup(row);+}++async function markFailed(id, reason) {+ await sql`UPDATE inference_topups SET status = 'failed', error = ${String(reason).slice(0, 300)} WHERE id = ${id}`;+}++async function treasuryAtaExists(conn, payTo, mint) {+ const ata = getAssociatedTokenAddressSync(new PublicKey(mint), new PublicKey(payTo), false, TOKEN_PROGRAM_ID);+ const info = await conn.getAccountInfo(ata, 'confirmed');+ return info != null;+}++/** Reserve, sign, settle through the self-facilitator, then credit. */+async function runTopup(row) {+ const agent = await loadOwnedAgent(row.agent_id, row.user_id).catch(async (e) => {+ await markFailed(row.id, e.message);+ throw e;+ });+ const amount = Number(row.amount_usdc);+ const atomics = BigInt(Math.round(amount * 10 ** USDC_DECIMALS));+ const idem = `inference_topup:${row.id}`;++ let reservationId;+ try {+ const reservation = await reserveSpendUsd({+ agentId: agent.id,+ userId: row.user_id,+ meta: agent.meta,+ category: CUSTODY_CATEGORY,+ usdValue: amount,+ destination: row.pay_to,+ asset: 'USDC',+ rowMeta: {+ topup_id: row.id,+ source: row.source,+ credits_usd: Number(row.credits_usd),+ ...(row.intent_id ? { intent_id: row.intent_id } : {}),+ },+ });+ reservationId = reservation.reservationId;+ } catch (e) {+ if (e instanceof SpendLimitError) {+ await markFailed(row.id, e.message);+ throw spendLimitToTopupError(e);+ }+ await markFailed(row.id, e?.message || 'reserve failed');+ throw e;+ }+ await sql`+ UPDATE agent_custody_events SET idempotency_key = ${idem}, amount_raw = ${atomics.toString()}+ WHERE id = ${reservationId} AND idempotency_key IS NULL+ `;+ await sql`UPDATE inference_topups SET custody_event_id = ${reservationId} WHERE id = ${row.id}`;++ const fail = async (code, message, status = 502) => {+ await releaseSpendReservation(reservationId, code);+ await markFailed(row.id, message);+ throw new TopupError(status, code, message);+ };++ let keypair;+ try {+ keypair = await recoverSolanaAgentKeypair(agent.meta.encrypted_solana_secret, {+ agentId: agent.id,+ userId: row.user_id,+ reason: CUSTODY_CATEGORY,+ meta: { topup_id: row.id, usdc: amount, to: row.pay_to },+ });+ } catch {+ return fail('key_recover_failed', 'The agent wallet key could not be recovered, so nothing was signed.', 500);+ }+ if (keypair.publicKey.toBase58() !== row.payer_address) {+ return fail('wallet_changed', 'The agent wallet changed after this top-up was previewed. Nothing was signed; preview again.', 409);+ }++ const sponsor = sponsorOrNull();+ let settled;+ let requirement;+ try {+ const { conn, blockhash, mintInfo } = await bootstrapSolanaContext({ buyer: keypair });+ requirement = {+ scheme: 'exact',+ network: NETWORK_SOLANA_MAINNET,+ asset: usdcMint(),+ payTo: row.pay_to,+ amount: atomics.toString(),+ extra: sponsor ? { feePayer: sponsor.publicKey.toBase58() } : {},+ };+ const receiverAtaExists = await treasuryAtaExists(conn, row.pay_to, requirement.asset);+ const transaction = buildPaymentTx({+ accept: requirement,+ buyer: keypair,+ blockhash,+ mintInfo,+ receiverAtaExists,+ nonce: nextAutoNonce(),+ selfPay: !sponsor,+ });+ settled = await settleRingPayment({+ paymentPayload: { x402Version: 2, payload: { transaction } },+ requirement,+ conn,+ feePayer: sponsor || undefined,+ feeMeter: facilitatorFeeMeter(),+ pendingStore: new SqlPendingSettlementStore({ scope: PENDING_SCOPE_FACILITATOR }),+ idempotencyKey: idem,+ });+ } catch (e) {+ return fail('settle_failed', `The transfer could not be settled: ${String(e?.message || e).slice(0, 200)}`);+ }++ if (!settled.success && settled.pending && settled.transaction) {+ await updateCustodyEvent(reservationId, { signature: settled.transaction, meta: { confirm: 'pending' } });+ const [p] = await sql`+ UPDATE inference_topups SET status = 'pending', signature = ${settled.transaction}+ WHERE id = ${row.id} RETURNING *+ `;+ return rowResult(p, { note: 'Broadcast, waiting for Solana to confirm. Retry the same call to read the result.' });+ }+ if (!settled.success) {+ return fail('settle_failed', `The self-facilitator refused the transfer: ${settled.reason || 'unknown reason'}. Nothing moved.`);+ }++ const credit = await claimSettleCredit({+ sql,+ row: {+ network: requirement.network,+ payer: settled.payer,+ payTo: requirement.payTo,+ mint: requirement.asset,+ amountAtomic: Number(requirement.amount),+ txSig: settled.transaction,+ feeLamports: settled.feeLamports,+ idempotencyKey: idem,+ feePayer: settled.feePayer,+ },+ });+ if (!credit.granted && !credit.idempotentReplay) {+ await updateCustodyEvent(reservationId, { status: 'failed', signature: settled.transaction, meta: { refused: credit.reason } });+ await markFailed(row.id, `settlement signature refused: ${credit.reason}`);+ throw new TopupError(409, 'settle_refused', `The settlement could not be attributed to this top-up (${credit.reason}). Contact support with signature ${settled.transaction}.`);+ }+ if (credit.granted) recordSettledFee(settled.feePayer, settled.feeLamports);++ return finalizeSettled({ ...row, custody_event_id: reservationId }, settled.transaction);+}++/** Book a confirmed transfer: custody row, credit ledger, top-up row, owner notice. */+async function finalizeSettled(row, signature) {+ if (row.custody_event_id) {+ await updateCustodyEvent(row.custody_event_id, {+ status: 'confirmed',+ signature,+ usd: Number(row.amount_usdc),+ });+ }+ const credited = await creditAccount({+ userId: row.user_id,+ amountUsd: Number(row.credits_usd),+ kind: 'deposit',+ action: 'inference.topup',+ refType: 'agent_wallet_topup',+ refId: String(row.agent_id),+ txSignature: signature,+ asset: 'USDC',+ assetAmount: BigInt(Math.round(Number(row.amount_usdc) * 10 ** USDC_DECIMALS)).toString(),+ priceUsd: USDC_CREDIT_RATE,+ idempotencyKey: `inference_topup:${row.id}`,+ meta: { topup_id: row.id, agent_id: row.agent_id, source: row.source },+ });+ const [done] = await sql`+ UPDATE inference_topups+ SET status = 'settled', signature = ${signature}, ledger_id = ${credited.ledgerId}, settled_at = now(), error = NULL+ WHERE id = ${row.id}+ RETURNING *+ `;+ if (!credited.replay) {+ insertNotification(row.user_id, 'inference_topup', {+ agent_id: row.agent_id,+ amount_usdc: Number(row.amount_usdc),+ credits_usd: Number(row.credits_usd),+ signature,+ source: row.source,+ link: '/credits',+ });+ logAudit({+ userId: row.user_id,+ action: 'inference.topup',+ resourceId: row.agent_id,+ meta: { topup_id: row.id, usdc: Number(row.amount_usdc), credits_usd: Number(row.credits_usd), signature, source: row.source },+ });+ }+ return rowResult(done, { balance_usd: credited.balanceUsd });+}++/**+ * Settle the outcome of a top-up whose broadcast was not yet confirmed. Reads+ * the recorded signature from chain: landed credits the account, reverted+ * releases the reservation, unknown stays pending for the next read.+ */+export async function reconcileTopup(row) {+ if (!row.signature) return rowResult(row);+ const { solanaConnection } = await import('./solana/connection.js');+ const conn = solanaConnection({ url: env.SOLANA_RPC_URL, commitment: 'confirmed' });+ let status = null;+ try {+ status = (await conn.getSignatureStatuses([row.signature], { searchTransactionHistory: true }))?.value?.[0] || null;+ } catch {+ return rowResult(row, { note: 'Solana did not answer; still pending. Retry shortly.' });+ }+ if (status && status.err == null && ['confirmed', 'finalized'].includes(status.confirmationStatus)) {+ return finalizeSettled(row, row.signature);+ }+ if (status && status.err != null) {+ if (row.custody_event_id) await releaseSpendReservation(row.custody_event_id, 'reverted');+ await markFailed(row.id, 'the transfer reverted on chain; nothing moved');+ const [failed] = await sql`SELECT * FROM inference_topups WHERE id = ${row.id}`;+ return rowResult(failed);+ }+ const ageMs = Date.now() - new Date(row.executed_at || row.created_at).getTime();+ if (!status && ageMs > 5 * 60_000) {+ if (row.custody_event_id) await releaseSpendReservation(row.custody_event_id, 'dropped');+ await markFailed(row.id, 'the transfer never landed (blockhash expired); nothing moved');+ const [failed] = await sql`SELECT * FROM inference_topups WHERE id = ${row.id}`;+ return rowResult(failed);+ }+ return rowResult(row, { note: 'Broadcast, waiting for Solana to confirm.' });+}++/** Reconcile every pending top-up for one account (called from the usage read). */+export async function reconcilePendingTopups(userId) {+ const rows = await sql`+ SELECT * FROM inference_topups+ WHERE user_id = ${userId} AND status = 'pending' AND signature IS NOT NULL+ ORDER BY created_at ASC LIMIT 5+ `;+ for (const row of rows) {+ await reconcileTopup(row).catch((err) => console.warn('[inference-topup] reconcile failed', row.id, err?.message));+ }+}diff --git a/api/_lib/migrations/20260922131000_inference_billing.sql b/api/_lib/migrations/20260922131000_inference_billing.sqlnew file mode 100644index 000000000..657bf293d--- /dev/null+++ b/api/_lib/migrations/20260922131000_inference_billing.sql@@ -0,0 +1,74 @@+-- Self-funded inference: an agent pays for its own model usage from its wallet.+--+-- Three pieces of state, all owned by api/_lib/inference-billing.js and+-- api/_lib/inference-topup.js:+--+-- inference_topups one row per wallet-funded credit top-up. A row is born as+-- a preview (the exact recipient, amount and credits the+-- owner is asked to confirm) and is single-use: execution+-- flips it previewed -> executing -> settled | pending |+-- failed, so a preview_id can never move money twice.+-- Previews expire ten minutes after they are created.+-- Rows written by an armed wallet intent (source 'intent')+-- skip the preview state and are born 'executing'.+-- inference_keys API keys minted by POST /api/me/inference/provision. The+-- key itself lives in api_keys (scope 'inference'); this+-- row binds it to the agent whose wallet funded it, so its+-- model calls count against that agent's inference budget.+-- credit_ledger unchanged schema. Inference spends are ordinary 'spend'+-- rows with action 'inference.agent' and ref_type 'agent', so the+-- per-agent budget sums come from the same ledger the+-- balance does. The partial index below keeps that sum an+-- index scan.++CREATE TABLE IF NOT EXISTS inference_topups (+ id uuid PRIMARY KEY DEFAULT gen_random_uuid(),+ user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,+ agent_id uuid NOT NULL,+ source text NOT NULL DEFAULT 'owner', -- owner | provision | intent+ status text NOT NULL DEFAULT 'previewed', -- previewed | executing | pending | settled | failed | expired+ amount_usdc numeric(20, 6) NOT NULL,+ credits_usd numeric(20, 6) NOT NULL, -- amount_usdc * published rate, no fee+ payer_address text NOT NULL, -- the agent's custodial Solana wallet+ pay_to text NOT NULL, -- platform treasury (self-facilitator allowlist)+ network text NOT NULL DEFAULT 'mainnet',+ signature text,+ custody_event_id bigint,+ ledger_id uuid,+ api_key_id uuid, -- provision only: the key minted after settlement+ intent_id uuid, -- intent only: the rule that fired+ error text,+ idempotency_key text, -- intent fires: one top-up per (intent, window)+ created_at timestamptz NOT NULL DEFAULT now(),+ expires_at timestamptz NOT NULL DEFAULT now() + interval '10 minutes',+ executed_at timestamptz,+ settled_at timestamptz,+ CONSTRAINT inference_topups_status_chk+ CHECK (status IN ('previewed', 'executing', 'pending', 'settled', 'failed', 'expired')),+ CONSTRAINT inference_topups_source_chk+ CHECK (source IN ('owner', 'provision', 'intent')),+ CONSTRAINT inference_topups_amount_chk CHECK (amount_usdc > 0)+);++CREATE INDEX IF NOT EXISTS inference_topups_user_created+ ON inference_topups (user_id, created_at DESC);+CREATE INDEX IF NOT EXISTS inference_topups_agent_created+ ON inference_topups (agent_id, created_at DESC);+CREATE UNIQUE INDEX IF NOT EXISTS inference_topups_idem+ ON inference_topups (idempotency_key) WHERE idempotency_key IS NOT NULL;+CREATE UNIQUE INDEX IF NOT EXISTS inference_topups_signature+ ON inference_topups (signature) WHERE signature IS NOT NULL;++CREATE TABLE IF NOT EXISTS inference_keys (+ api_key_id uuid PRIMARY KEY,+ user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,+ agent_id uuid NOT NULL,+ topup_id uuid REFERENCES inference_topups(id),+ created_at timestamptz NOT NULL DEFAULT now()+);++CREATE INDEX IF NOT EXISTS inference_keys_user ON inference_keys (user_id, created_at DESC);++CREATE INDEX IF NOT EXISTS credit_ledger_inference_agent+ ON credit_ledger (ref_id, created_at DESC)+ WHERE action = 'inference.agent' AND ref_type = 'agent';diff --git a/api/_lib/pricing/catalog.js b/api/_lib/pricing/catalog.jsindex b8076f6d9..3c37ab91a 100644--- a/api/_lib/pricing/catalog.js+++ b/api/_lib/pricing/catalog.js@@ -53,6 +53,18 @@ export const TTS_ELEVEN_USD_PER_1K = 0.3;// every platform-key OpenAI synthesis is metered to the caller's credits.export const TTS_OPENAI_USD_PER_1K = 0.03;+// Inference on the three.ws agent runtime (model id `three-ws/agent`, served+// OpenAI-compatible at /api/v1/chat/completions): retail USD per 1,000,000+// tokens, [input, output]. The runtime routes free lanes first and anchors on+// Vertex Gemini, so one flat published rate is honest regardless of which lane+// answered, and a budget in credits means the same thing on every call. A call+// is never cheaper than INFERENCE_MIN_CALL_USD so a budget always converges.+export const INFERENCE_USD_PER_MTOK = Object.freeze({ input: 0.5, output: 2 });+export const INFERENCE_MIN_CALL_USD = 0.0001;+// Wallet-funded top-ups convert USDC to credits at this published rate, no fee:+// 1 USDC buys exactly $1.00 of credits (credits are USD-denominated).+export const USDC_CREDIT_RATE = 1;+// ── The catalog ─────────────────────────────────────────────────────────────────// id → { label, category, policy, usd }. `usd: null` ⇒ price set per-call.export const CATALOG = Object.freeze({@@ -123,6 +135,12 @@ export const CATALOG = Object.freeze({policy: POLICY.CONSUMPTION,usd: null, // per-call: characters * TTS_OPENAI_USD_PER_1K / 1000},+ 'inference.agent': {+ label: 'Inference: three-ws/agent model calls (per 1M tokens)',+ category: 'inference',+ policy: POLICY.CONSUMPTION,+ usd: null, // per-call: tokens priced at INFERENCE_USD_PER_MTOK+ },'selfie.reconstruct': {label: 'Selfie → Avatar reconstruction',category: 'generation',diff --git a/api/_lib/wallet-intents.js b/api/_lib/wallet-intents.jsindex 8198e272e..5d201c08f 100644--- a/api/_lib/wallet-intents.js+++ b/api/_lib/wallet-intents.js@@ -10,8 +10,9 @@// row with meta.intent_id so the owner sees real receipts.//// Triggers : on_tip_received | on_income | on_balance_below | on_schedule-// | on_launch_matching | on_stream_started+// | on_launch_matching | on_stream_started | credits_below// Actions : tip | transfer | buy | snipe | withdraw | split_income | freeze | notify+// | fund_inference (USDC -> account credits, api/_lib/inference-topup.js)//// $THREE is the only coin three.ws promotes. "$THREE"/"three" resolves to its// canonical mint; any other mint is the owner's own runtime input (a snipe@@ -43,6 +44,8 @@ import { THREE_MINT } from './networth-model.js';import { resolveSolanaRecipient } from '../../src/solana/sns.js';import { recentPumpLaunches, enrichCreatorStats } from './pump-launch-feed.js';import { logAudit } from './audit.js';+import { getCreditAccount } from './credits.js';+import { topupFromIntent, normalizeTopupAmount, TopupError } from './inference-topup.js';const WSOL_MINT = 'So11111111111111111111111111111111111111112';const JUPITER_BASE = 'https://lite-api.jup.ag/swap/v1';@@ -57,6 +60,11 @@ export const INTENT_TRIGGERS = Object.freeze(['on_schedule','on_launch_matching','on_stream_started',+ // Fired only by the v1 automation engine (api/_lib/agents-v1/automations.js),+ // never by the sweep or an event hook: the automation owns the trigger and+ // this intent owns the guarded execution.+ 'on_automation',+ 'credits_below',]);export const INTENT_ACTIONS = Object.freeze([@@ -68,6 +76,7 @@ export const INTENT_ACTIONS = Object.freeze(['split_income','freeze','notify',+ 'fund_inference',]);// Actions that move funds (need spend-policy enforcement + a signing keypair).@@ -152,6 +161,10 @@ export function normalizeIntent(raw, { threeMint = THREE_MINT } = {}) {if (!trigger.creator && trigger.max_mcap_usd == null) {return { ok: false, error: 'needs_filter', message: 'a launch rule needs a creator address and/or a max market cap to match on' };}+ } else if (triggerType === 'credits_below') {+ const t = posNum(tcfg.threshold_usd);+ if (t == null) return { ok: false, error: 'needs_threshold', message: 'a credits threshold (USD) is required' };+ trigger.threshold_usd = t;}// on_income / on_stream_started carry no required config.@@ -159,6 +172,17 @@ export function normalizeIntent(raw, { threeMint = THREE_MINT } = {}) {const action = { type: actionType };if (actionType === 'freeze') {// no params — the kill switch+ } else if (actionType === 'fund_inference') {+ // Top up the owner's account credits from this agent's USDC. The window is+ // one UTC day: however often the trigger holds, a rule tops up once a day.+ if (!['credits_below', 'on_schedule'].includes(triggerType)) {+ return { ok: false, error: 'bad_pairing', message: 'fund_inference runs on a credits_below or on_schedule trigger' };+ }+ try {+ action.amount_usdc = normalizeTopupAmount(acfg.amount_usdc);+ } catch (e) {+ return { ok: false, error: 'needs_amount', message: e.message };+ }} else if (actionType === 'notify') {action.message = str(acfg.message, 280) || null;action.channel = ['email', 'log'].includes(acfg.channel) ? acfg.channel : 'email';@@ -173,7 +197,9 @@ export function normalizeIntent(raw, { threeMint = THREE_MINT } = {}) {const slip = num(acfg.slippage_pct);action.slippage_pct = slip != null ? clamp(slip, 0, 50) : 5;// For a non-launch buy the mint must be known up front.- if (triggerType !== 'on_launch_matching' && !action.mint) {+ // An automation on a launch trigger supplies the matched mint at fire time too.+ action.mint_from_event = triggerType === 'on_automation' && acfg.mint_from_event === true;+ if (triggerType !== 'on_launch_matching' && !action.mint && !action.mint_from_event) {return { ok: false, error: 'needs_mint', message: 'name the token to buy ($THREE or a mint address)' };}} else {@@ -210,6 +236,10 @@ export function normalizeIntent(raw, { threeMint = THREE_MINT } = {}) {}}+ if (triggerType === 'credits_below' && !['fund_inference', 'notify'].includes(actionType)) {+ return { ok: false, error: 'bad_pairing', message: 'a credits_below rule can top up credits (fund_inference) or notify you' };+ }+// ── owner-set caps (clamped under the spend policy at execution time) ──const lim = r.limits || {};const limits = {@@ -236,6 +266,7 @@ function defaultTitle(triggerType, actionType, action) {on_schedule: 'On schedule',on_launch_matching: 'On matching launch',on_stream_started: 'On stream start',+ credits_below: 'On low credits',}[triggerType] || 'Intent';const A = {tip: 'tip back',@@ -246,6 +277,7 @@ function defaultTitle(triggerType, actionType, action) {split_income: 'split income',freeze: 'freeze the wallet',notify: 'notify me',+ fund_inference: 'top up credits',}[actionType] || actionType;return `${T} → ${A}`;}@@ -268,6 +300,8 @@ export function describeIntent(intent) {return `${t.cadence === 'weekly' ? `Every ${['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'][t.weekday ?? 5]}` : 'Daily'} at ${String(t.hour).padStart(2, '0')}:00 UTC, ${a.type} ${amt}${dest ? ` to ${dest}` : ''}.`;case 'on_launch_matching':return `When a launch matches${t.creator ? ` creator ${t.creator.slice(0, 4)}…` : ''}${t.max_mcap_usd ? ` under $${Math.round(t.max_mcap_usd / 1000)}k` : ''}, ${a.type} ${a.amount_sol} SOL.`;+ case 'credits_below':+ return `When credits fall below $${t.threshold_usd}, ${a.type === 'fund_inference' ? `top up ${a.amount_usdc} USDC from the wallet, at most once a day` : 'notify me'}.`;case 'on_stream_started':return `When a money stream starts, ${a.type} ${amt}${dest ? ` to ${dest}` : ''}.`;default:@@ -416,17 +450,18 @@ const COMPILE_TOOL = {description:'on_tip_received: someone tips the agent. on_income: any income arrives. on_balance_below: SOL balance drops under a floor. ' +'on_schedule: a daily/weekly time. on_launch_matching: a new pump.fun launch matches a creator and/or market cap. ' +- 'on_stream_started: a money stream to the agent begins.',+ 'on_stream_started: a money stream to the agent begins. credits_below: the owner\'s account credits (USD) drop under a floor.',},trigger_config: {type: 'object',description:'Fields by trigger. on_tip_received: { min_sol }. on_balance_below: { threshold_sol }. on_schedule: ' +'{ cadence: "daily"|"weekly", weekday: 0-6 (Sun=0..Sat=6, Fri=5), hour: 0-23 (UTC) }. on_launch_matching: ' +- '{ creator: base58|null, max_mcap_usd, min_mcap_usd }.',+ '{ creator: base58|null, max_mcap_usd, min_mcap_usd }. credits_below: { threshold_usd }.',properties: {min_sol: { type: 'number' },threshold_sol: { type: 'number' },+ threshold_usd: { type: 'number' },cadence: { type: 'string', enum: ['daily', 'weekly'] },weekday: { type: 'number' },hour: { type: 'number' },@@ -441,7 +476,8 @@ const COMPILE_TOOL = {description:'tip/transfer: send SOL to a destination. buy/snipe: spend SOL to acquire a token. withdraw: send SOL to an ' +'owner-controlled address. split_income: send a % of income to a destination. freeze: halt all spending ' +- '(kill switch). notify: just DM the owner.',+ '(kill switch). notify: just DM the owner. fund_inference: move USDC from the agent wallet into account credits ' ++ 'that pay for model calls (only with credits_below or on_schedule).',},action_config: {type: 'object',@@ -449,7 +485,7 @@ const COMPILE_TOOL = {'Fields by action. tip/transfer: { amount_sol } OR { pct, of: "tip"|"income"|"balance" }, destination. ' +'buy/snipe: { mint ("$THREE" or base58, omit for on_launch_matching), amount_sol, slippage_pct }. ' +'withdraw: { amount_sol } OR { above_sol } OR { pct }, destination. split_income: { pct, destination }. ' +- 'notify: { message }. "half of what they sent" → pct 50, of "tip".',+ 'notify: { message }. fund_inference: { amount_usdc }. "half of what they sent" → pct 50, of "tip".',properties: {amount_sol: { type: 'number' },above_sol: { type: 'number' },@@ -459,6 +495,7 @@ const COMPILE_TOOL = {mint: { type: 'string' },slippage_pct: { type: 'number' },message: { type: 'string' },+ amount_usdc: { type: 'number' },},},limits: {@@ -494,6 +531,7 @@ function compileSystemPrompt({ agentName, network, balanceSol, holdings, limits,'- NEVER invent an amount, destination, creator address, token, or schedule. If the rule is missing any of these, set needs_clarification=true with one short question.','- "tip back half of what they sent" → trigger on_tip_received, action tip, action_config { pct: 50, of: "tip" }, destination is the tipper (leave destination empty — the engine fills the tipper in at fire time).','- "when my balance is under X, freeze and DM me" → trigger on_balance_below { threshold_sol: X }, action freeze.',+ '- "when credits fall below 100, top up 5 USDC from the wallet" → trigger credits_below { threshold_usd: 100 }, action fund_inference { amount_usdc: 5 }. Credits are USD; the engine tops up at most once a day.','- "split 10% of everything I earn to <addr/name>" → trigger on_income, action split_income { pct: 10, destination: <addr/.sol> }.','- "every Friday withdraw profit above 2 SOL to <addr>" → trigger on_schedule { cadence: "weekly", weekday: 5, hour: 13 }, action withdraw { above_sol: 2, destination: <addr> }.','- "snipe launches from <creator> under $40k, max 1 SOL each" → trigger on_launch_matching { creator, max_mcap_usd: 40000 }, action snipe { amount_sol: 1 } (omit mint — it is the matched launch).',@@ -715,13 +753,10 @@ async function claimRejection({ agentId, intentId, idemKey, usd, network, dailyUreturn { status: 'skipped', note: 'already fired for this event' };}-async function gatedSpend({ ctx, intent, discriminator, category, usd, lamports, rowMeta, doSpend }) {- const { agentId, ownerId, userId, network, dryRun, now } = ctx;-- // 1) intent-level caps (per-action / daily / total): the owner's own ceilings.- // The per-action cap is exact here (one value against a constant); the daily and- // lifetime budgets are re-checked atomically inside the claim in step 3, so this- // pass exists to reject early with a precise message, not to be the gate.+// Intent-level caps (per-action / daily / total): the owner's own ceilings for one+// rule. Returns a skip/pause verdict, or null when the spend fits every cap.+async function intentCapVerdict({ ctx, intent, usd }) {+ const { agentId, now } = ctx;const lim = intent.limits || {};if (lim.per_action_usd != null && usd > lim.per_action_usd + 1e-9) {return { status: 'skipped', note: `over this rule's per-action cap ($${lim.per_action_usd})`, usd };@@ -739,6 +774,46 @@ async function gatedSpend({ ctx, intent, discriminator, category, usd, lamports,return { status: 'paused', note: `would exceed this rule's lifetime cap ($${lim.total_usd})`, usd };}}+ return null;+}++// Top up the owner's credits from the agent wallet (USDC through the+// self-facilitator). The top-up path runs its own spend-policy reserve, so this+// only applies the rule's caps and maps the outcome onto the intent vocabulary.+async function fundInference({ ctx, intent, discriminator }) {+ const usd = Number(intent.action.amount_usdc);+ const capped = await intentCapVerdict({ ctx, intent, usd });+ if (capped) return capped;+ if (ctx.dryRun) return { status: 'would_run', note: `would top up ${usd} USDC of credits from the agent wallet`, usd };+ try {+ const r = await topupFromIntent({+ agentId: ctx.agentId,+ ownerId: ctx.ownerId,+ amountUsdc: usd,+ intentId: intent.id,+ idempotencyKey: `intent:${intent.id}:${discriminator}`,+ });+ if (r.status === 'skipped') return { status: 'skipped', note: r.note };+ if (r.status === 'settled') {+ return { status: 'ok', signature: r.signature, explorer: explorerTxUrl(r.signature, 'mainnet'), usd, note: `topped up $${r.credits_usd} of credits` };+ }+ return { status: 'paused', note: r.note || 'top-up broadcast, waiting for confirmation', signature: r.signature, usd };+ } catch (e) {+ if (e instanceof TopupError && e.status < 500) return { status: 'paused', note: e.message, usd };+ return { status: 'error', note: (e?.message || 'top-up failed').slice(0, 240), usd };+ }+}++async function gatedSpend({ ctx, intent, discriminator, category, usd, lamports, rowMeta, doSpend }) {+ const { agentId, ownerId, userId, network, dryRun, now } = ctx;++ // 1) intent-level caps (per-action / daily / total): the owner's own ceilings.+ // The per-action cap is exact here (one value against a constant); the daily and+ // lifetime budgets are re-checked atomically inside the claim in step 3, so this+ // pass exists to reject early with a precise message, not to be the gate.+ const capped = await intentCapVerdict({ ctx, intent, usd });+ if (capped) return capped;+ const lim = intent.limits || {};// 2) the agent spend policy: the SAME hard ceiling every outbound path obeys.// This runs every non-daily guard (freeze, allowlist, NL policy rules, per-tx@@ -935,6 +1010,10 @@ async function executeAction(intent, ctx, event = {}) {const n = await notifyOwner({ ctx, intent, discriminator: disc, subject: `${ctx.agentName || 'Your agent'}: wallet frozen`, body: note });return { status: 'ok', note, frozen: true, notify: n.status };}+ case 'fund_inference': {+ // One top-up per UTC day per rule, whatever fired it.+ return fundInference({ ctx, intent, discriminator: ctx.discriminator || `credits:${now.toISOString().slice(0, 10)}` });+ }case 'notify': {const disc = ctx.discriminator || `notify:${now.toISOString().slice(0, 13)}`;const body = a.message || describeIntent(intent);@@ -971,8 +1050,11 @@ async function executeAction(intent, ctx, event = {}) {// ── execution context (loads the agent, gates safety, recovers the key once) ─────async function buildExecContext({ agentId, userId, network, dryRun, needsKey }) {- const [row] = await sql`SELECT id, user_id, name, meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL`;+ const [row] = await sql`SELECT id, user_id, name, meta, status FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL`;if (!row) return { error: 'not_found' };+ // A stopped agent pauses every intent without deleting it. An owner's dry run+ // still reports what would happen.+ if (row.status === 'stopped' && !dryRun) return { error: 'agent_stopped' };const meta = row.meta || {};const address = meta.solana_address;const encryptedSecret = meta.encrypted_solana_secret;@@ -1053,6 +1135,47 @@ export async function runIntentNow({ agentId, userId, intentId, network = 'mainnreturn { ran: true, dryRun, results: [{ ...intentSummary(intent), ...res }] };}+/**+ * Execute one intent for a v1 automation whose trigger just fired. Same guarded+ * path as the sweep: freeze, spend policy, the intent's own caps, and the+ * idempotent custody claim keyed by `discriminator` (one execution per fire).+ *+ * @param {object} o+ * @param {string} o.agentId+ * @param {string} o.intentId+ * @param {string} o.discriminator unique per fire, e.g. `auto:<id>:<event>`+ * @param {object} [o.event] trigger event ({ amount_sol, from, signature, mint })+ * @param {string} [o.network]+ */+export async function fireIntentForAutomation({ agentId, intentId, discriminator, event = {}, network = 'mainnet' }) {+ const intent = await getIntent(agentId, intentId);+ if (!intent) return { status: 'error', note: 'backing intent not found' };+ if (!intent.enabled) return { status: 'skipped', note: 'backing intent disabled' };+ const built = await buildExecContext({+ agentId,+ userId: null,+ network,+ dryRun: false,+ needsKey: SPENDING_ACTIONS.has(intent.action.type),+ });+ if (built.error) {+ const res = { status: 'paused', note: built.error };+ await stampFire(intent, res).catch(() => {});+ return res;+ }+ const ctx = built.ctx;+ ctx.discriminator = discriminator;+ if (intent.action.mint_from_event && event.mint) ctx.overrideMint = event.mint;+ let res;+ try {+ res = await executeAction(intent, ctx, event);+ } catch (e) {+ res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) };+ }+ await stampFire(intent, res, ctx.now).catch(() => {});+ return res;+}+function intentSummary(intent) {return { id: intent.id, title: intent.title, trigger: intent.trigger.type, action: intent.action.type };}@@ -1064,6 +1187,7 @@ function synthEvent(intent, ctx) {return { amount_sol: sampleSol, usd: sampleSol * ctx.price, from: null, signature: null, sample: true };}if (t.type === 'on_balance_below') return { balance_sol: ctx.balanceSol };+ if (t.type === 'credits_below') return { credits_usd: null };return {};}@@ -1204,7 +1328,18 @@ export async function runIntentSweep({ network = 'mainnet', now = new Date(), latallySweep(summary, intent.trigger.type, r);}- // 3) launch-matching intents — one shared pull of recent launches, matched per rule.+ // 3) credits-floor intents: top the owner's account credits up from the agent+ // wallet when they fall under the rule's threshold (fund_inference).+ const credits = (await sql`+ SELECT * FROM agent_wallet_intents WHERE enabled = true AND trigger_type = 'credits_below' AND network = ${network}+ `).map(rowToIntent);+ for (const intent of credits) {+ summary.scanned++;+ const r = await fireCreditsIntent(intent, network, now);+ tallySweep(summary, intent.trigger.type, r);+ }++ // 4) launch-matching intents: one shared pull of recent launches, matched per rule.const launch = (await sql`SELECT * FROM agent_wallet_intents WHERE enabled = true AND trigger_type = 'on_launch_matching' AND network = ${network}`).map(rowToIntent);@@ -1267,6 +1402,22 @@ async function fireBalanceIntent(intent, network, now) {return res;}+async function fireCreditsIntent(intent, network, now) {+ const built = await buildExecContext({ agentId: intent.agent_id, userId: null, network, dryRun: false, needsKey: false });+ if (built.error) { const res = { status: 'paused', note: built.error }; await stampFire(intent, res, now).catch(() => {}); return res; }+ const ctx = built.ctx; ctx.now = now;+ const acct = await getCreditAccount(ctx.ownerId);+ if (acct.balanceUsd >= intent.trigger.threshold_usd) {+ return { status: 'skipped', note: `credits $${acct.balanceUsd.toFixed(2)} are above the $${intent.trigger.threshold_usd} floor` };+ }+ ctx.discriminator = `credits:${now.toISOString().slice(0, 10)}`;+ let res;+ try { res = await executeAction(intent, ctx, { credits_usd: acct.balanceUsd }); }+ catch (e) { res = { status: 'error', note: (e?.message || 'failed').slice(0, 240) }; }+ await stampFire(intent, res, now).catch(() => {});+ return res;+}+async function fireLaunchIntent(intent, network, now, launches, solPrice) {const t = intent.trigger;// Match by creator and/or market cap. Creator-gated rules enrich on demand.@@ -1316,5 +1467,6 @@ function traitLabel(trigger, action) {if (action === 'split_income') return 'Shares its income';if (trigger === 'on_launch_matching' && action === 'snipe') return 'Snipes fresh launches';if (action === 'freeze') return 'Self-protects on low balance';+ if (action === 'fund_inference') return 'Pays for its own thinking';return null;}diff --git a/api/agent/run.js b/api/agent/run.jsindex 61acff62b..69f181b0e 100644--- a/api/agent/run.js+++ b/api/agent/run.js@@ -75,9 +75,16 @@ function chunkFrame(id, delta, finishReason = null) {/*** Run one full agent completion over `body.messages` and answer in OpenAI- * format (SSE when body.stream, JSON otherwise). Shared by POST /api/agent/run- * and the chat proxy's `three-ws/agent` model branch; `opts.rateLimited` skips- * the limiter when the caller already applied its own.+ * format (SSE when body.stream, JSON otherwise). Shared by POST /api/agent/run,+ * the chat proxy's `three-ws/agent` model branch and the metered+ * /api/v1/chat/completions; `opts.rateLimited` skips the limiter when the+ * caller already applied its own.+ *+ * Token usage is summed over every model round and reported the OpenAI way: a+ * `usage` object on the JSON response, and a final usage chunk on a stream when+ * the request asked for `stream_options.include_usage`. `opts.onUsage(usage,+ * completionId)` receives the same totals once the answer is complete, which is+ * where a metered caller books the charge.*/export async function runAgentCompletion(req, res, body, opts = {}) {if (!opts.rateLimited) {@@ -115,6 +122,9 @@ export async function runAgentCompletion(req, res, body, opts = {}) {};let streamedAny = false;+ // Platform cost rides along (null when any round hit an unpriced lane) so a+ // metered caller can record honest spend next to what it billed.+ const usage = { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0, estimated: false, cost_micro_usd: 0, lanes: [] };const loop = createAgentLoop({chain,toolSchemas: agentToolSchemas(),@@ -125,6 +135,15 @@ export async function runAgentCompletion(req, res, body, opts = {}) {if (stream) sse(chunkFrame(completionId, { content: delta }));},onEvent: (event) => {+ if (event.kind === 'model_call' && event.usage) {+ usage.prompt_tokens += event.usage.input || 0;+ usage.completion_tokens += event.usage.output || 0;+ usage.total_tokens = usage.prompt_tokens + usage.completion_tokens;+ if (event.usage.estimated) usage.estimated = true;+ usage.cost_micro_usd =+ usage.cost_micro_usd == null || event.costMicroUsd == null ? null : usage.cost_micro_usd + event.costMicroUsd;+ usage.lanes.push({ provider: event.provider, model: event.model });+ }if (stream && event.kind === 'tool_call') sse(`: tool ${event.tool}\n\n`);},});@@ -161,11 +180,29 @@ export async function runAgentCompletion(req, res, body, opts = {}) {return error(res, 502, 'agent_loop_failed', detail);}+ const openAiUsage = {+ prompt_tokens: usage.prompt_tokens,+ completion_tokens: usage.completion_tokens,+ total_tokens: usage.total_tokens,+ };+ const billed = opts.onUsage ? await opts.onUsage(usage, completionId) : null;+if (stream) {// A run whose final round emitted no deltas (e.g. everything came from a// non-streaming provider quirk) still owes the client the content.if (!streamedAny && finalContent) sse(chunkFrame(completionId, { content: finalContent }));sse(chunkFrame(completionId, {}, 'stop'));+ if (body?.stream_options?.include_usage) {+ sse(`data: ${JSON.stringify({+ id: completionId,+ object: 'chat.completion.chunk',+ created: Math.floor(Date.now() / 1000),+ model: AGENT_MODEL_ID,+ choices: [],+ usage: openAiUsage,+ ...(billed ? { billing: billed } : {}),+ })}\n\n`);+ }sse('data: [DONE]\n\n');return res.end();}@@ -178,6 +215,8 @@ export async function runAgentCompletion(req, res, body, opts = {}) {choices: [{ index: 0, message: { role: 'assistant', content: finalContent }, finish_reason: 'stop' },],+ usage: openAiUsage,+ ...(billed ? { billing: billed } : {}),});}diff --git a/api/agents.js b/api/agents.jsindex a26093a86..ceacfae1f 100644--- a/api/agents.js+++ b/api/agents.js@@ -6,6 +6,7 @@* POST /api/agents — create a new agent identity* GET /api/agents/:id — get one agent (public fields if not owner)* PUT /api/agents/:id — update agent (owner only)+ * PATCH /api/agents/:id : partial update; also { inferenceBudget: { daily, monthly } | null }* DELETE /api/agents/:id — soft-delete agent (owner only)* POST /api/agents/:id/wallet — link / update wallet* DELETE /api/agents/:id/wallet — unlink wallet@@ -28,6 +29,11 @@ import { trackAgentOwnerVisit } from './_lib/retention.js';import { env } from './_lib/env.js';import { z } from 'zod';import { isUuid } from './_lib/validate.js';+import {+ normalizeInferenceBudget,+ applyInferenceBudget,+ resumeAfterBudgetChange,+} from './_lib/inference-billing.js';const animationEntrySchema = z.object({name: z.string().trim().min(1).max(60),@@ -550,6 +556,26 @@ async function handleUpdate(req, res, id, auth) {`meta.studio exceeds 256KB (${studioBytes} bytes)`);}}+ // The inference budget (and its exhaustion stamp) is written only through+ // the validated `inferenceBudget` field below, never by a raw meta merge.+ delete mergedMeta.inference_budget;+ if (existingMeta.inference_budget) mergedMeta.inference_budget = existingMeta.inference_budget;+ }++ // PATCH { inferenceBudget: { daily, monthly } | null }: cap the credits this+ // agent's model calls may burn (api/_lib/inference-billing.js). Changing it+ // clears a recorded exhaustion and restarts an agent the budget had stopped.+ const budgetInput = body.inferenceBudget !== undefined ? body.inferenceBudget : body.inference_budget;+ let budgetChanged = false;+ if (budgetInput !== undefined) {+ let budget;+ try {+ budget = normalizeInferenceBudget(budgetInput);+ } catch (err) {+ return error(res, err.status || 400, err.code || 'validation_error', err.message);+ }+ mergedMeta = applyInferenceBudget(mergedMeta || existing.meta || {}, budget);+ budgetChanged = true;}// Brain Studio compiles its visual graph (meta.studio.brain) down to the real@@ -574,6 +600,7 @@ async function handleUpdate(req, res, id, auth) {WHERE id = ${id}RETURNING *`;+ if (budgetChanged) await resumeAfterBudgetChange(id, existing.meta);return json(res, 200, { agent: decorate(updated) });}diff --git a/api/agents/[id].js b/api/agents/[id].jsindex a01848fdb..1fd42548b 100644--- a/api/agents/[id].js+++ b/api/agents/[id].js@@ -18,6 +18,7 @@* /api/agents/:id/registration — public EIP-8004 registry document (Metaplex Agent Registry URI)* /api/agents/:id/sign — owner-only: sign message with server wallet* /api/agents/:id/usage — owner-only: LLM usage stats+ * /api/agents/:id/credits : owner-only: credits, inference budget, wallet-funded top-ups (credits/topup/preview, credits/topup, credits/auto-fund)* /api/agents/:id/achievements — public: earned + locked achievements from real platform data* /api/agents/:id/reserves : public proof-of-reserves (alias of /solana/reserves)*@@ -173,6 +174,11 @@ export default wrap(async function handler(req, res) {return mod.handleSign(req, res, id);}+ if (sub === 'credits') {+ const mod = await import('./_id/credits.js');+ return mod.handleCredits(req, res, id, action, parts[5]);+ }+if (sub === 'usage') {const mod = await import('./_id/_sub.js');return mod.handleUsage(req, res, id);diff --git a/api/agents/_id/credits.js b/api/agents/_id/credits.jsnew file mode 100644index 000000000..b1662b62b--- /dev/null+++ b/api/agents/_id/credits.js@@ -0,0 +1,165 @@+// /api/agents/:id/credits: the agent-side surface of self-funded inference.+//+// GET /api/agents/:id/credits owner: credits, burn rate, days left,+// this agent's inference budget and+// spend, recent top-ups, auto-fund rule+// POST /api/agents/:id/credits/topup/preview owner: { amount_usdc } → single-use+// preview (recipient, amount, token,+// chain, credits). Nothing moves.+// POST /api/agents/:id/credits/topup owner: { preview_id, confirm_deposit: true }+// → USDC agent wallet → treasury through+// the self-facilitator, credits booked+// GET /api/agents/:id/credits/auto-fund owner: the credits_below rule, or null+// PUT /api/agents/:id/credits/auto-fund owner: { enabled, threshold_usd, amount_usdc }+// → create or update that rule+//+// Bearer callers need `wallet:write` to move funds or change the rule and+// `wallet:read` (or `profile`) to read; a browser session is the owner itself.+// The move is api/_lib/inference-topup.js; the read model is+// api/_lib/inference-billing.js; the rule is api/_lib/wallet-intents.js.++import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../../_lib/auth.js';+import { sql } from '../../_lib/db.js';+import { cors, error, json, method, readJson, wrap, rateLimited } from '../../_lib/http.js';+import { requireCsrf } from '../../_lib/csrf.js';+import { limits, clientIp } from '../../_lib/rate-limit.js';+import { inferenceUsage, autoFundIntent } from '../../_lib/inference-billing.js';+import { previewTopup, executeTopup, reconcilePendingTopups } from '../../_lib/inference-topup.js';+import { normalizeIntent, createIntent, updateIntent, describeIntent } from '../../_lib/wallet-intents.js';++async function resolveCaller(req) {+ const session = await getSessionUser(req);+ if (session) return { userId: session.id, scope: null };+ const bearer = await authenticateBearer(extractBearer(req));+ if (bearer) return { userId: bearer.userId, scope: bearer.scope || '' };+ return null;+}++function scopeOk(caller, ...scopes) {+ if (caller.scope === null) return true;+ return scopes.some((s) => hasScope(caller.scope, s));+}++async function ownedAgent(agentId, userId) {+ const [row] = await sql`+ SELECT id, user_id, name, meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL+ `;+ if (!row) return { status: 404, code: 'not_found', message: 'agent not found' };+ if (String(row.user_id) !== String(userId)) return { status: 403, code: 'forbidden', message: 'not your agent' };+ return { agent: row };+}++function sendTyped(res, err) {+ if (err?.expose && err.status) {+ return error(res, err.status, err.code, err.message, err.detail || {});+ }+ throw err;+}++export const handleCredits = wrap(async (req, res, agentId, action, sub) => {+ if (cors(req, res, { methods: 'GET,POST,PUT,OPTIONS', credentials: true })) return;++ const caller = await resolveCaller(req);+ if (!caller) return error(res, 401, 'unauthorized', 'sign in, or send a three.ws API key as a Bearer token');++ const owned = await ownedAgent(agentId, caller.userId);+ if (owned.status) return error(res, owned.status, owned.code, owned.message);+ const agent = owned.agent;++ // GET /credits+ if (!action) {+ if (!method(req, res, ['GET'])) return;+ if (!scopeOk(caller, 'wallet:read', 'wallet:write', 'profile')) {+ return error(res, 403, 'insufficient_scope', 'reading credits needs the wallet:read scope');+ }+ const rl = await limits.authedReadIp(clientIp(req));+ if (!rl.success) return rateLimited(res, rl);+ await reconcilePendingTopups(caller.userId);+ return json(res, 200, await inferenceUsage({ userId: caller.userId, agent }));+ }++ if (action === 'auto-fund') return handleAutoFund(req, res, caller, agent);++ if (action !== 'topup') return error(res, 404, 'not_found', `unknown credits route: ${action}`);+ if (!method(req, res, ['POST'])) return;+ if (!scopeOk(caller, 'wallet:write')) {+ return error(res, 403, 'insufficient_scope', 'moving funds from an agent wallet needs the wallet:write scope');+ }+ if (!(await requireCsrf(req, res, caller.userId))) return;+ const rl = await limits.authIp(clientIp(req));+ if (!rl.success) return rateLimited(res, rl);++ const body = (await readJson(req).catch(() => null)) || {};+ try {+ if (sub === 'preview') {+ const preview = await previewTopup({+ userId: caller.userId,+ agentId: agent.id,+ amountUsdc: body.amount_usdc ?? body.amount,+ });+ return json(res, 200, preview);+ }+ if (sub) return error(res, 404, 'not_found', `unknown topup route: ${sub}`);+ const result = await executeTopup({+ userId: caller.userId,+ previewId: body.preview_id,+ confirmDeposit: body.confirm_deposit,+ sources: ['owner'],+ });+ if (result.agent_id && result.agent_id !== agent.id) {+ return error(res, 409, 'agent_mismatch', 'that preview belongs to a different agent');+ }+ return json(res, result.status === 'pending' ? 202 : 200, result);+ } catch (err) {+ return sendTyped(res, err);+ }+});++async function handleAutoFund(req, res, caller, agent) {+ if (!method(req, res, ['GET', 'PUT'])) return;+ if (req.method === 'GET') {+ if (!scopeOk(caller, 'wallet:read', 'wallet:write', 'profile')) {+ return error(res, 403, 'insufficient_scope', 'reading the auto-fund rule needs the wallet:read scope');+ }+ return json(res, 200, { auto_fund: await autoFundIntent(agent.id) });+ }++ if (!scopeOk(caller, 'wallet:write')) {+ return error(res, 403, 'insufficient_scope', 'changing the auto-fund rule needs the wallet:write scope');+ }+ if (!(await requireCsrf(req, res, caller.userId))) return;+ const rl = await limits.authIp(clientIp(req));+ if (!rl.success) return rateLimited(res, rl);++ const body = (await readJson(req).catch(() => null)) || {};+ const current = await autoFundIntent(agent.id);+ const enabled = body.enabled !== false;++ // Turning an absent rule off is a no-op, not an error.+ if (!current && !enabled) return json(res, 200, { auto_fund: null });++ const threshold = body.threshold_usd ?? current?.threshold_usd;+ const amount = body.amount_usdc ?? current?.amount_usdc;+ const norm = normalizeIntent({+ title: 'Keep the agent thinking',+ trigger_type: 'credits_below',+ trigger_config: { threshold_usd: threshold },+ action_type: 'fund_inference',+ action_config: { amount_usdc: amount },+ limits: {+ per_action_usd: amount,+ daily_usd: body.daily_usd ?? current?.limits?.daily_usd ?? amount,+ total_usd: body.total_usd ?? current?.limits?.total_usd ?? null,+ },+ });+ if (!norm.ok) return error(res, 400, norm.error, norm.message);+ const readback = describeIntent(norm.intent);+ norm.intent.readback = readback;++ if (current) {+ await updateIntent(agent.id, caller.userId, current.intent_id, { intent: norm.intent, enabled });+ } else {+ await createIntent(agent.id, caller.userId, norm.intent, { sourceText: readback });+ }+ return json(res, 200, { auto_fund: await autoFundIntent(agent.id), readback });+}diff --git a/api/inference/[action].js b/api/inference/[action].jsnew file mode 100644index 000000000..0e55f15c3--- /dev/null+++ b/api/inference/[action].js@@ -0,0 +1,167 @@+// Account-level inference billing routes.+//+// GET /api/me/usage credits, burn rate, days remaining at the+// current rate, this month's model calls and+// tokens, and the last top-ups with their+// signatures. ?agent_id=<uuid> narrows it to one+// agent and adds that agent's budget.+// POST /api/me/inference/provision/preview { agent_id, amount_usdc } → the confirmation+// table for funding a new inference key from+// that agent's wallet. Nothing moves.+// POST /api/me/inference/provision { preview_id, confirm_deposit: true, name? }+// → settles the top-up, then mints an API key+// scoped to `inference` alone, bound to the+// agent, and returns it ONCE.+//+// vercel.json maps the /api/me/* paths here (?action=usage | provision-preview |+// provision). Reads accept a session or any Bearer key carrying `inference`,+// `wallet:read` or `profile`; provisioning moves funds, so a Bearer caller+// needs `wallet:write`.++import { getSessionUser, authenticateBearer, extractBearer, hasScope } from '../_lib/auth.js';+import { sql } from '../_lib/db.js';+import { cors, error, json, method, readJson, wrap, rateLimited } from '../_lib/http.js';+import { requireCsrf } from '../_lib/csrf.js';+import { limits, clientIp } from '../_lib/rate-limit.js';+import { mintApiKey } from '../_lib/api-keys.js';+import { inferenceUsage, inferencePricing } from '../_lib/inference-billing.js';+import { previewTopup, executeTopup, reconcilePendingTopups } from '../_lib/inference-topup.js';+import { isUuid } from '../_lib/validate.js';++const BASE_URL = 'https://three.ws/api/v1';++async function resolveCaller(req) {+ const session = await getSessionUser(req);+ if (session) return { userId: session.id, scope: null };+ const bearer = await authenticateBearer(extractBearer(req));+ if (bearer) return { userId: bearer.userId, scope: bearer.scope || '', apiKeyId: bearer.apiKeyId || null };+ return null;+}++function scopeOk(caller, ...scopes) {+ if (caller.scope === null) return true;+ return scopes.some((s) => hasScope(caller.scope, s));+}++function sendTyped(res, err) {+ if (err?.expose && err.status) return error(res, err.status, err.code, err.message, err.detail || {});+ throw err;+}++export default wrap(async (req, res) => {+ if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;+ const action = String(req.query?.action || '');++ const caller = await resolveCaller(req);+ if (!caller) return error(res, 401, 'unauthorized', 'sign in, or send a three.ws API key as a Bearer token (npx three-ws login)');++ if (action === 'usage') return handleUsage(req, res, caller);+ if (action === 'provision-preview' || action === 'provision') return handleProvision(req, res, caller, action);+ return error(res, 404, 'not_found', `unknown inference route: ${action || '(none)'}`);+});++async function handleUsage(req, res, caller) {+ if (!method(req, res, ['GET'])) return;+ if (!scopeOk(caller, 'inference', 'wallet:read', 'wallet:write', 'profile')) {+ return error(res, 403, 'insufficient_scope', 'reading usage needs the inference, wallet:read or profile scope');+ }+ const rl = await limits.authedReadIp(clientIp(req));+ if (!rl.success) return rateLimited(res, rl);++ const agentId = req.query?.agent_id ? String(req.query.agent_id) : null;+ let agent = null;+ if (agentId) {+ if (!isUuid(agentId)) return error(res, 400, 'bad_request', 'agent_id must be an agent id');+ const [row] = await sql`+ SELECT id, user_id, name, meta FROM agent_identities WHERE id = ${agentId} AND deleted_at IS NULL+ `;+ if (!row || String(row.user_id) !== String(caller.userId)) return error(res, 404, 'not_found', 'agent not found');+ agent = row;+ }+ await reconcilePendingTopups(caller.userId);+ const usage = await inferenceUsage({ userId: caller.userId, agent });+ return json(res, 200, { ...usage, base_url: BASE_URL });+}++async function handleProvision(req, res, caller, action) {+ if (!method(req, res, ['POST'])) return;+ if (!scopeOk(caller, 'wallet:write')) {+ return error(res, 403, 'insufficient_scope', 'funding an inference key from an agent wallet needs the wallet:write scope');+ }+ if (!(await requireCsrf(req, res, caller.userId))) return;+ const rl = await limits.authIp(clientIp(req));+ if (!rl.success) return rateLimited(res, rl);++ const body = (await readJson(req).catch(() => null)) || {};+ try {+ if (action === 'provision-preview') {+ const agentId = String(body.agent_id || '');+ if (!isUuid(agentId)) return error(res, 400, 'bad_request', 'agent_id is required: the agent whose wallet funds the key');+ const preview = await previewTopup({+ userId: caller.userId,+ agentId,+ amountUsdc: body.amount_usdc ?? body.amount,+ source: 'provision',+ });+ return json(res, 200, {+ ...preview,+ key: { scope: 'inference', bound_agent_id: agentId, base_url: BASE_URL },+ });+ }++ const topup = await executeTopup({+ userId: caller.userId,+ previewId: body.preview_id,+ confirmDeposit: body.confirm_deposit,+ sources: ['provision'],+ });+ if (topup.status === 'pending') return json(res, 202, topup);+ if (topup.status !== 'settled') return error(res, 502, 'topup_failed', 'the top-up did not settle, so no key was minted', topup);++ // The key is minted once per settled top-up. A retry of a provision that+ // already minted reports the key's prefix; the secret was shown once.+ if (topup.api_key_id) {+ const [k] = await sql`SELECT id, prefix, scope FROM api_keys WHERE id = ${topup.api_key_id}`;+ return json(res, 200, {+ ...topup,+ key: { id: k?.id, prefix: k?.prefix, scope: k?.scope, token: null, base_url: BASE_URL },+ note: 'This top-up already minted its key; the secret is only shown once. Revoke it at /dashboard/api and provision again if it was lost.',+ });+ }+ const name = typeof body.name === 'string' && body.name.trim() ? body.name.trim().slice(0, 80) : 'Inference key';+ const minted = await mintApiKey({+ userId: caller.userId,+ name,+ scopes: ['inference'],+ req,+ via: 'inference_provision',+ });+ const [claimed] = await sql`+ UPDATE inference_topups SET api_key_id = ${minted.row.id}+ WHERE id = ${topup.topup_id} AND api_key_id IS NULL+ RETURNING id+ `;+ if (!claimed) {+ await sql`UPDATE api_keys SET revoked_at = now() WHERE id = ${minted.row.id}`;+ return error(res, 409, 'already_provisioned', 'A concurrent request already minted the key for this top-up.');+ }+ await sql`+ INSERT INTO inference_keys (api_key_id, user_id, agent_id, topup_id)+ VALUES (${minted.row.id}, ${caller.userId}, ${topup.agent_id}, ${topup.topup_id})+ `;+ return json(res, 201, {+ ...topup,+ api_key_id: minted.row.id,+ key: {+ id: minted.row.id,+ prefix: minted.row.prefix,+ scope: minted.row.scope,+ token: minted.secret,+ base_url: BASE_URL,+ model: inferencePricing().model,+ },+ });+ } catch (err) {+ return sendTyped(res, err);+ }+}diff --git a/api/v1/_catalog.js b/api/v1/_catalog.jsindex f76349144..4f0221915 100644--- a/api/v1/_catalog.js+++ b/api/v1/_catalog.js@@ -34,6 +34,7 @@ export const API_META = {'memory:write','agents:read','agents:write',+ 'inference',],},rate_limit: {@@ -49,6 +50,32 @@ export const API_META = {};export const CATALOG = [+ {+ id: 'v1.chat.completions',+ method: 'POST',+ path: '/api/v1/chat/completions',+ auth: 'required',+ scope: 'inference',+ summary:+ 'OpenAI-compatible chat completions on the three.ws agent runtime (model three-ws/agent), ' ++ 'billed to account credits at the published per-token rate. Point any OpenAI client at ' ++ 'https://three.ws/api/v1 with a key carrying the inference scope.',+ params: {+ messages: 'array: OpenAI chat messages [{ role, content }] (required)',+ model: 'string: three-ws/agent (default)',+ stream: 'boolean: SSE chat.completion.chunk frames (default true)',+ stream_options: 'object: { include_usage: true } adds a final usage + billing chunk',+ agent_id: 'string: bill against this agent\'s inference budget (keys from /api/me/inference/provision are already bound)',+ },+ },+ {+ id: 'v1.models',+ method: 'GET',+ path: '/api/v1/models',+ auth: 'public',+ summary: 'OpenAI-compatible model list for /api/v1/chat/completions, with published per-token prices.',+ params: {},+ },{id: 'v1.ai.text_to_3d',method: 'POST',diff --git a/api/v1/chat/completions.js b/api/v1/chat/completions.jsnew file mode 100644index 000000000..222e55c5f--- /dev/null+++ b/api/v1/chat/completions.js@@ -0,0 +1,153 @@+// POST /api/v1/chat/completions: the metered, OpenAI-compatible model endpoint.+//+// A drop-in base URL for any client that accepts one: point it at+// https://three.ws/api/v1, use a three.ws API key carrying the `inference`+// scope (POST /api/me/inference/provision mints one funded from an agent+// wallet), and ask for model `three-ws/agent`. The completion is the same+// server-side agent loop /api/agent/run serves (api/agent/run.js+// runAgentCompletion: free lanes first, the Vertex credits anchor last, the+// read-only tool registry), billed to the caller's account credits at the+// published rate (api/_lib/pricing/catalog.js INFERENCE_USD_PER_MTOK).+//+// Billing, in order:+// 1. assertInferenceAllowed: 402 insufficient_credits when the account is+// empty, 402 inference_budget_exhausted when the agent this call runs for+// has used its daily or monthly budget (and that first refusal stops the+// agent's automations and notifies the owner).+// 2. The completion runs.+// 3. chargeInference books one idempotent credit_ledger row for the summed+// tokens of every model round. A failed completion is not charged.+//+// 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+// and no budget applies.++import { authenticateBearer, extractBearer, getSessionUser, hasScope } from '../../_lib/auth.js';+import { sql } from '../../_lib/db.js';+import { cors, error, method, rateLimited, readJson, setRateLimitHeaders, wrap } from '../../_lib/http.js';+import { limits } from '../../_lib/rate-limit.js';+import { isUuid } from '../../_lib/validate.js';+import { recordEvent } from '../../_lib/usage.js';+import {+ assertInferenceAllowed,+ chargeInference,+ INFERENCE_MODEL_ID,+} from '../../_lib/inference-billing.js';+import { runAgentCompletion } from '../../agent/run.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);+ if (bearerToken) {+ const bearer = await authenticateBearer(bearerToken);+ if (!bearer) return { error: [401, 'invalid_api_key', 'That API key or token is not valid, expired, or revoked.'] };+ if (!hasScope(bearer.scope, 'inference')) {+ return { error: [403, 'insufficient_scope', 'This key cannot call models. Mint one with the `inference` scope at /dashboard/api, or fund one from an agent wallet: npx three-ws fund --amount 5 --agent <id>.'] };+ }+ return { userId: bearer.userId, apiKeyId: bearer.apiKeyId || null, clientId: bearer.clientId || null };+ }+ const session = await getSessionUser(req);+ if (session) return { userId: session.id, apiKeyId: null, clientId: null };+ 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.'] };+}++async function resolveAgent(req, body, caller) {+ if (caller.apiKeyId) {+ const [bound] = await sql`+ SELECT i.id, i.user_id, i.name, i.meta+ FROM inference_keys k JOIN agent_identities i ON i.id = k.agent_id+ WHERE k.api_key_id = ${caller.apiKeyId} AND i.deleted_at IS NULL+ `;+ if (bound) return { agent: bound };+ }+ const named = body?.agent_id || req.headers['x-three-agent'] || null;+ if (!named) return { agent: null };+ if (!isUuid(String(named))) return { error: [400, 'bad_agent_id', 'agent_id must be the id of one of your agents.'] };+ const [row] = await sql`+ SELECT id, user_id, name, meta FROM agent_identities WHERE id = ${String(named)} AND deleted_at IS NULL+ `;+ if (!row || String(row.user_id) !== String(caller.userId)) {+ return { error: [404, 'agent_not_found', 'No agent with that id belongs to this account.'] };+ }+ return { agent: row };+}++// OpenAI-style error body, so an OpenAI SDK surfaces the message verbatim.+function openAiError(res, status, code, message, detail = {}) {+ return error(res, status, code, message, { type: code, code, ...detail });+}++export default wrap(async function handler(req, res) {+ if (cors(req, res, { methods: 'POST, OPTIONS', credentials: true })) return;+ if (!method(req, res, ['POST'])) return;++ 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}`);+ setRateLimitHeaders(res, rl);+ if (!rl.success) return rateLimited(res, rl);++ let body;+ try {+ body = await readJson(req, MAX_BODY_BYTES);+ } 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))) {+ return openAiError(res, 404, 'model_not_found', `Model "${body.model}" is not served here. Use "${INFERENCE_MODEL_ID}" (GET /api/v1/models).`);+ }++ const resolved = await resolveAgent(req, body, caller);+ if (resolved.error) return openAiError(res, ...resolved.error);+ const agent = resolved.agent;++ try {+ await assertInferenceAllowed({ userId: caller.userId, agent });+ } catch (err) {+ if (err?.expose) return openAiError(res, err.status, err.code, err.message, err.detail || {});+ throw err;+ }++ const started = Date.now();+ return runAgentCompletion(req, res, body, {+ rateLimited: true,+ onUsage: async (usage, completionId) => {+ const charge = await chargeInference({+ userId: caller.userId,+ agentId: agent?.id ?? null,+ apiKeyId: caller.apiKeyId,+ callId: completionId,+ inputTokens: usage.prompt_tokens,+ outputTokens: usage.completion_tokens,+ estimated: usage.estimated,+ provider: usage.lanes.at(-1)?.provider ?? null,+ model: usage.lanes.at(-1)?.model ?? null,+ });+ recordEvent({+ userId: caller.userId,+ apiKeyId: caller.apiKeyId,+ clientId: caller.clientId,+ agentId: agent?.id ?? null,+ kind: 'llm',+ tool: 'v1.chat.completions',+ latencyMs: Date.now() - started,+ provider: usage.lanes.at(-1)?.provider ?? null,+ model: usage.lanes.at(-1)?.model ?? null,+ inputTokens: usage.prompt_tokens,+ outputTokens: usage.completion_tokens,+ costMicroUsd: usage.cost_micro_usd,+ meta: { billed_usd: charge.chargedUsd, estimated: usage.estimated, rounds: usage.lanes.length },+ });+ return {+ charged_usd: charge.chargedUsd,+ balance_usd: charge.balanceUsd,+ agent_id: agent?.id ?? null,+ ...(charge.shortfallUsd > 0 ? { shortfall_usd: charge.shortfallUsd } : {}),+ };+ },+ });+});diff --git a/api/v1/models.js b/api/v1/models.jsnew file mode 100644index 000000000..5d82b8306--- /dev/null+++ b/api/v1/models.js@@ -0,0 +1,41 @@+// GET /api/v1/models: the OpenAI-compatible model list for the metered endpoint.+//+// OpenAI clients call this to populate their model picker, so it answers in the+// `{ object: "list", data: [...] }` shape they expect, with the published+// three.ws price attached to each model. Public: listing models needs no key.++import { cors, json, method, wrap } from '../_lib/http.js';+import { inferencePricing } from '../_lib/inference-billing.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);++export default wrap(async (req, res) => {+ if (cors(req, res, { methods: 'GET, OPTIONS' })) return;+ if (!method(req, res, ['GET'])) return;+ const pricing = inferencePricing();+ res.setHeader('cache-control', 'public, max-age=300');+ return json(res, 200, {+ object: 'list',+ data: [+ {+ id: pricing.model,+ object: 'model',+ created: CREATED,+ owned_by: 'three.ws',+ description:+ 'The three.ws agent runtime: a tool-using loop with live token prices, web search, Solana balances, ' ++ 'a rug/honeypot safety verdict, smart-money activity and .sol resolution. Read-only: it cannot move funds.',+ 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,+ billed_to: 'account credits (https://three.ws/credits)',+ },+ },+ ],+ });+});diff --git a/vercel.json b/vercel.jsonindex 1b5e8bc53..aa9c27eb1 100644--- a/vercel.json+++ b/vercel.json@@ -3082,6 +3082,18 @@"src": "/api/agents/x402/manifest","dest": "/api/agents/x402/[action]?action=manifest"},+ {+ "src": "/api/me/usage/?",+ "dest": "/api/inference/[action]?action=usage"+ },+ {+ "src": "/api/me/inference/provision/preview/?",+ "dest": "/api/inference/[action]?action=provision-preview"+ },+ {+ "src": "/api/me/inference/provision/?",+ "dest": "/api/inference/[action]?action=provision"+ },{"src": "/api/x402-facilitator/?","dest": "/api/x402-facilitator/[action]?action=index"@@ -3166,6 +3178,10 @@"src": "/api/agents/([^/]+)/actions","dest": "/api/agents/[id]"},+ {+ "src": "/api/agents/([^/]+)/credits(/.*)?",+ "dest": "/api/agents/[id]"+ },{"src": "/api/agents/([^/]+)/usage","dest": "/api/agents/[id]"