Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// /api/vaults/:id
// GET /api/vaults/:id live vault detail (NAV, terms, positions, backers, reputation)
// PATCH /api/vaults/:id owner-only: pause / resume / update terms / close
//
// The GET is role-aware: anyone can see the public picture (the agent, its verified
// reputation, live NAV + P&L, terms, backer roster); the signed-in caller also sees
// their own position; the owner additionally sees accrued fees and the funding
// roster detail. NAV is re-derived from chain on every read, never a stale cache.
import { cors, json, method, error, readJson, wrap } from '../_lib/http.js';
import { authWrite, resolveUserId, loadAgent, traderBadge } from '../_lib/vault-auth.js';
import { assertBearerMaySpend } from '../_lib/spend-scope.js';
import {
getVault, getOpenPositions, getBacker, listBackers,
setVaultStatus, updateVaultTerms, recordVaultEvent,
} from '../_lib/vault-store.js';
import { computeVaultNav } from '../_lib/vault-wallet.js';
import {
sharePriceE6, roiBps, toBig, usdcToAtomics, settleRedemption,
TERM_BOUNDS, clampTermBps, backerHostileTermChanges,
} from '../_lib/vault-accounting.js';
import { isUuid } from '../_lib/validate.js';
import { requireRealFundsAgreement } from '../_lib/real-funds-agreement.js';
function idFromReq(req) {
const fromQuery = req.query?.id;
if (typeof fromQuery === 'string' && fromQuery) return fromQuery;
const path = new URL(req.url, 'http://x').pathname;
const m = path.match(/\/api\/vaults\/([^/]+)/);
return m ? decodeURIComponent(m[1]) : null;
}
async function handleGet(req, res, id) {
const who = await resolveUserId(req).catch(() => null);
const vault = await getVault(id);
if (!vault) return error(res, 404, 'not_found', 'vault not found');
const isOwner = who && who.userId === vault.owner_user_id;
const [agent, positions, backers, badge] = await Promise.all([
loadAgent(vault.agent_id).catch(() => null),
getOpenPositions(vault.id),
listBackers(vault.id, { limit: 50 }),
traderBadge(vault.agent_id, vault.network).catch(() => null),
]);
const nav = await computeVaultNav(vault, positions);
const totalShares = toBig(vault.total_shares);
const priceE6 = sharePriceE6(nav.navAtomics, totalShares);
// The caller's own position (so the UI can show "your stake / your P&L").
let myPosition = null;
if (who) {
const b = await getBacker(vault.id, who.userId);
if (b && toBig(b.shares) > 0n) {
const settle = settleRedemption({
shares: b.shares, backerShares: b.shares, costBasisAtomics: b.cost_basis_atomics,
navAtomics: nav.navAtomics, totalShares, feeBps: vault.performance_fee_bps,
});
myPosition = {
shares: String(b.shares), cost_basis_atomics: String(b.cost_basis_atomics),
deposited_atomics: String(b.deposited_atomics), redeemed_atomics: String(b.redeemed_atomics),
realized_gain_atomics: String(b.realized_gain_atomics), fees_paid_atomics: String(b.fees_paid_atomics),
backer_agent_id: b.backer_agent_id,
current_value_atomics: String(settle.grossPayout),
unrealized_gain_atomics: String(settle.gain),
estimated_net_atomics: String(settle.netPayout),
};
}
}
const data = {
id: vault.id, agent_id: vault.agent_id, network: vault.network, status: vault.status,
halt_reason: vault.halt_reason, paused_at: vault.paused_at, created_at: vault.created_at,
vault_address: vault.vault_address,
agent: agent ? { id: agent.id, name: agent.name, description: agent.description, image: agent.image } : null,
reputation: badge,
terms: {
performance_fee_bps: vault.performance_fee_bps,
max_drawdown_bps: vault.max_drawdown_bps,
per_backer_cap_atomics: vault.per_backer_cap_atomics != null ? String(vault.per_backer_cap_atomics) : null,
max_per_trade_atomics: String(vault.max_per_trade_atomics),
daily_budget_atomics: String(vault.daily_budget_atomics),
},
nav: {
nav_atomics: String(nav.navAtomics),
free_atomics: String(nav.freeAtomics),
usdc_atomics: String(nav.usdcAtomics),
share_price_e6: String(priceE6),
roi_bps: roiBps(nav.navAtomics, totalShares),
total_shares: String(totalShares),
priced: nav.priced,
peak_share_price_e6: String(vault.peak_share_price_e6),
},
positions: nav.positions.map((p) => ({ mint: p.mint, amount_raw: p.amount_raw, mark_atomics: p.mark_atomics })),
backer_count: backers.length,
backers: backers.map((b) => ({
shares: String(b.shares),
deposited_atomics: String(b.deposited_atomics),
// Pseudonymous: the roster shows stake size, never the user id.
is_me: who ? b.user_id === who.userId : false,
})),
my_position: myPosition,
is_owner: !!isOwner,
...(isOwner ? { accrued_fee_atomics: String(vault.accrued_fee_atomics) } : {}),
};
return json(res, 200, { data }, { 'cache-control': isOwner || who ? 'no-store' : 'public, max-age=10, s-maxage=20' });
}
async function handlePatch(req, res, id) {
const who = await authWrite(req, res);
if (!who) return;
const vault = await getVault(id);
if (!vault) return error(res, 404, 'not_found', 'vault not found');
if (vault.owner_user_id !== who.userId) return error(res, 403, 'forbidden', 'only the vault owner can change it');
let body;
try { body = (await readJson(req)) || {}; } catch (e) { return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid body'); }
const action = String(body.action || 'terms');
// Resume restarts trading with backers' funds and terms raises its budgets
// and fee; pause and close only stop trading, so they need no spend grant.
if (!who.session && action !== 'pause' && action !== 'close') assertBearerMaySpend({ scope: who.scope }, req);
if (action === 'pause') {
if (vault.status === 'closed') return error(res, 409, 'closed', 'vault is closed');
const next = await setVaultStatus(vault.id, 'paused', { haltReason: 'owner_pause' });
await recordVaultEvent({ vaultId: vault.id, type: 'pause', userId: who.userId, reason: 'owner paused trading' });
return json(res, 200, { data: { vault: next } }, { 'cache-control': 'no-store' });
}
if (action === 'resume') {
if (vault.status === 'closed') return error(res, 409, 'closed', 'vault is closed');
if (!(await requireRealFundsAgreement(req, res, { userId: who.userId, network: vault.network, context: 'vault-resume' }))) return;
const next = await setVaultStatus(vault.id, 'open', { haltReason: null });
await recordVaultEvent({ vaultId: vault.id, type: 'resume', userId: who.userId, reason: 'owner resumed trading' });
return json(res, 200, { data: { vault: next } }, { 'cache-control': 'no-store' });
}
if (action === 'close') {
const next = await setVaultStatus(vault.id, 'closing', { haltReason: 'owner_close' });
await recordVaultEvent({ vaultId: vault.id, type: 'close', userId: who.userId, reason: 'owner closing vault; backers may redeem' });
return json(res, 200, { data: { vault: next } }, { 'cache-control': 'no-store' });
}
if (action === 'terms') {
const patch = {};
if (body.performanceFeeBps != null) {
const bps = clampTermBps(body.performanceFeeBps, TERM_BOUNDS.performanceFeeBps);
if (bps == null) return error(res, 400, 'validation_error', 'performanceFeeBps must be a number');
patch.performanceFeeBps = bps;
}
if (body.maxDrawdownBps != null) {
const bps = clampTermBps(body.maxDrawdownBps, TERM_BOUNDS.maxDrawdownBps);
if (bps == null) return error(res, 400, 'validation_error', 'maxDrawdownBps must be a number');
patch.maxDrawdownBps = bps;
}
if (body.maxPerTradeUsdc != null) {
const v = Number(body.maxPerTradeUsdc);
if (!(v > 0)) return error(res, 400, 'validation_error', 'maxPerTradeUsdc must be a positive number');
patch.maxPerTradeAtomics = usdcToAtomics(v);
}
if (body.dailyBudgetUsdc != null) {
const v = Number(body.dailyBudgetUsdc);
if (!(v > 0)) return error(res, 400, 'validation_error', 'dailyBudgetUsdc must be a positive number');
patch.dailyBudgetAtomics = usdcToAtomics(v);
}
if ('perBackerCapUsdc' in body) {
const v = body.perBackerCapUsdc;
if (v != null && !Number.isFinite(Number(v))) return error(res, 400, 'validation_error', 'perBackerCapUsdc must be a number or null');
patch.perBackerCapAtomics = v == null || Number(v) <= 0 ? null : usdcToAtomics(Number(v));
}
const effectivePerTrade = patch.maxPerTradeAtomics ?? toBig(vault.max_per_trade_atomics);
const effectiveDaily = patch.dailyBudgetAtomics ?? toBig(vault.daily_budget_atomics);
if (effectivePerTrade > effectiveDaily) return error(res, 400, 'validation_error', 'per-trade ceiling cannot exceed the daily budget');
// Backers deposited under the terms on record. While any shares are
// outstanding the owner may tighten those terms but not loosen them; to
// change them for real, close the vault so backers can redeem first.
if (toBig(vault.total_shares) > 0n) {
const hostile = backerHostileTermChanges(vault, patch);
if (hostile.length) {
return error(res, 409, 'terms_locked_for_backers', `${hostile.join(', ')} cannot be raised while backers hold shares. Lower it, or close the vault so backers can redeem first.`);
}
}
const next = await updateVaultTerms(vault.id, patch);
await recordVaultEvent({ vaultId: vault.id, type: 'terms', userId: who.userId, reason: 'terms updated', meta: { patch: Object.fromEntries(Object.entries(patch).map(([k, v]) => [k, v == null ? null : String(v)])) } });
return json(res, 200, { data: { vault: next } }, { 'cache-control': 'no-store' });
}
return error(res, 400, 'bad_action', 'action must be pause, resume, close, or terms');
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,PATCH,OPTIONS', credentials: true })) return;
const id = idFromReq(req);
if (!id || !isUuid(id)) return error(res, 404, 'not_found', 'vault not found');
if (req.method === 'PATCH') return handlePatch(req, res, id);
if (!method(req, res, ['GET', 'PATCH'])) return;
return handleGet(req, res, id);
});