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
import type { RefusalReason, RiskLimits } from './types.js'
/** Everything the risk engine needs to rule on a single intent. */
export interface RiskContext {
/** `buy` grows exposure and hits spend/position caps; `sell` reduces it and is exempt from those. */
side: 'buy' | 'sell'
/** USD notional of this order (agent computes it from live prices; USDG≈USD, WETH×ethUsd). */
notionalUsd: number
/** USD value the token position would reach AFTER a buy fills. */
positionUsdAfter: number
/** USD this agent has already spent this UTC day. */
spentTodayUsd: number
/** USD the whole fleet has spent this UTC day. */
fleetSpentTodayUsd: number
/** ms epoch of this agent's last executed trade, or null. */
lastTradeAt: number | null
/** Slippage bound (bps) the order would execute with. */
slippageBps: number
/** Whether the global kill switch is tripped. */
killed: boolean
/** Current time (ms) — injected for deterministic tests. */
now: number
/** Fleet-wide daily spend ceiling (USD). */
fleetMaxDailySpendUsdg: number
}
/** Result of a risk check. */
export interface RiskVerdict {
ok: boolean
reason?: RefusalReason
/** Human explanation, safe to journal and surface on the dashboard. */
detail: string
}
/**
* The risk engine. It is the last gate before any order — paper or live —
* reaches execution, and it fails CLOSED: any check it cannot satisfy refuses
* the trade rather than letting it through. Refusals are ordered from
* cheapest/most-fatal (kill switch) to most-specific (caps) so the journaled
* reason is the most meaningful one.
*
* Sells are intentionally exempt from spend and position caps: those caps exist
* to bound how much risk you take ON, and refusing a de-risking sell because of
* a spend cap would trap an agent in a losing position. Sells still honor the
* kill switch, cooldown, and slippage bound.
*/
export class RiskEngine {
constructor(private readonly limits: RiskLimits) {}
get riskLimits(): RiskLimits {
return this.limits
}
check(ctx: RiskContext): RiskVerdict {
if (ctx.killed) {
return { ok: false, reason: 'kill_switch', detail: 'kill switch is tripped — no new orders' }
}
if (ctx.notionalUsd <= 0) {
return { ok: false, reason: 'zero_amount', detail: 'order notional is zero or negative' }
}
// Cooldown throttles trade frequency regardless of side.
if (ctx.lastTradeAt !== null) {
const elapsed = (ctx.now - ctx.lastTradeAt) / 1000
if (elapsed < this.limits.cooldownSeconds) {
const wait = (this.limits.cooldownSeconds - elapsed).toFixed(1)
return { ok: false, reason: 'cooldown', detail: `cooldown active — ${wait}s until next trade allowed` }
}
}
// Slippage bound must never exceed the configured cap.
if (ctx.slippageBps > this.limits.maxSlippageBps) {
return {
ok: false,
reason: 'slippage_bound',
detail: `slippage ${ctx.slippageBps}bps exceeds cap ${this.limits.maxSlippageBps}bps`,
}
}
// Spend/position caps only constrain buys (exposure-increasing orders).
if (ctx.side === 'buy') {
if (ctx.positionUsdAfter > this.limits.maxPositionUsdg) {
return {
ok: false,
reason: 'position_cap',
detail: `position would reach $${ctx.positionUsdAfter.toFixed(2)}, over cap $${this.limits.maxPositionUsdg}`,
}
}
if (ctx.spentTodayUsd + ctx.notionalUsd > this.limits.maxDailySpendUsdg) {
return {
ok: false,
reason: 'daily_cap',
detail: `daily spend would reach $${(ctx.spentTodayUsd + ctx.notionalUsd).toFixed(2)}, over cap $${this.limits.maxDailySpendUsdg}`,
}
}
if (ctx.fleetSpentTodayUsd + ctx.notionalUsd > ctx.fleetMaxDailySpendUsdg) {
return {
ok: false,
reason: 'fleet_daily_cap',
detail: `fleet daily spend would reach $${(ctx.fleetSpentTodayUsd + ctx.notionalUsd).toFixed(2)}, over cap $${ctx.fleetMaxDailySpendUsdg}`,
}
}
}
return { ok: true, detail: 'within all risk limits' }
}
}
/** UTC-midnight ms boundary for `now` — the daily-cap accounting window. */
export function utcDayStart(now: number): number {
const d = new Date(now)
return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate())
}