Skip to content

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.

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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.sql
new file mode 100644
index 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.js
index 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.js
index 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, dailyU
return { 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 = 'mainn
return { 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(), la
tallySweep(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.js
index 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.js
index 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].js
index 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.js
new file mode 100644
index 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].js
new file mode 100644
index 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.js
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.json
index 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]"