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
// @three-ws/agent-guards — safety rails for autonomous agents.
//
// Two complementary surfaces:
// (a) LOCAL, pure-function guards — `policy({...})` builds a normalized leash and
// `guard(tx, policy)` → { allow, reason, message, detail } re-implements the
// real server spend-policy / trade-guard checks client-side. Deterministic,
// zero-dep, ideal to run BEFORE you sign a transaction.
// (b) A `createGuards({ baseUrl, fetch, ... })` client that wraps the live
// /api/agents/:id/trade(+/limits) and /api/agents/:id/wallet/limits endpoints.
//
// The local checks mirror api/_lib/agent-trade-guards.js and
// api/_lib/agent-spend-policy.js field-for-field, reason-for-reason, so a leash
// you enforce client-side never disagrees with the one the platform enforces.
// All trading is SOL-quoted on Solana; the only coin three.ws promotes is $THREE.
import { createHttp, ThreeWsError } from './http.js';
export { ThreeWsError, PaymentRequiredError, DEFAULT_BASE_URL } from './http.js';
export {
DELEGATION_DOMAIN,
canonicalDelegationFields,
delegationMessage,
verifyDelegationSignature,
checkDelegationCap,
} from './delegation.js';
// 1 SOL = 1e9 lamports — the on-chain unit the per-trade / daily-budget caps use.
export const LAMPORTS_PER_SOL = 1_000_000_000n;
// Fee + rent headroom kept above a buy so it never fails for lack of lamports to
// pay the network fee / open the token ATA. Mirrors SOL_FEE_HEADROOM_LAMPORTS in
// api/_lib/agent-trade-guards.js (~0.003 SOL).
export const SOL_FEE_HEADROOM_LAMPORTS = 3_000_000n;
// Server-side TRADE_LIMIT_DEFAULTS — the discretionary-trade policy applied when
// an owner has not set one. null caps mean "uncapped".
export const TRADE_LIMIT_DEFAULTS = Object.freeze({
per_trade_sol: null,
daily_budget_sol: null,
max_price_impact_pct: 15,
max_slippage_bps: 1000,
max_concurrent: null,
kill_switch: false,
});
// Server-side SPEND_LIMIT_DEFAULTS — the cross-path USD ceiling applied when an
// owner has not set one.
export const SPEND_LIMIT_DEFAULTS = Object.freeze({
daily_usd: null,
per_tx_usd: null,
withdraw_allowlist: [],
frozen: false,
});
// Base58 alphabet, 32–44 chars — every ed25519 pubkey. A cheap, dependency-free
// pre-filter mirroring BASE58_RE in agent-trade-guards.js (we don't run the full
// PublicKey curve check client-side, but the shape gate catches obvious garbage).
const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
const MAX_ALLOWLIST = 50;
// ── local policy builder ──────────────────────────────────────────────────────
function numOrNull(v) {
if (v === null || v === undefined || v === '') return null;
const n = Number(v);
if (!Number.isFinite(n) || n < 0) return null;
return n;
}
function clampNum(v, def, { min = 0, max = Infinity, round = false } = {}) {
const n = Number(v);
if (!Number.isFinite(n) || n < min) return def;
const c = Math.min(max, n);
return round ? Math.round(c) : c;
}
function normalizeAllowlist(raw) {
const list = (Array.isArray(raw) ? raw : [])
.map((a) => (typeof a === 'string' ? a.trim() : ''))
.filter((a) => BASE58_RE.test(a));
const seen = new Set();
const out = [];
for (const a of list) {
if (!seen.has(a)) {
seen.add(a);
out.push(a);
}
if (out.length >= MAX_ALLOWLIST) break;
}
return out;
}
/**
* Build a normalized, bounded policy from a loose patch. Mirrors the server's
* `normalizeTradeLimits` + `normalizeSpendLimits` so the same input produces the
* same leash whether it's applied here or on the platform: numeric caps coerce to
* a non-negative number or null, `max_price_impact_pct` clamps 0–100,
* `max_slippage_bps` 0–10000, `max_concurrent` 1–10000, and booleans coerce
* strictly to `=== true`. Pass the result to `guard()`.
*/
export function policy(raw = {}) {
const r = raw && typeof raw === 'object' ? raw : {};
return {
// discretionary-trade (SOL) caps — meta.trade_limits
per_trade_sol: numOrNull(r.per_trade_sol),
daily_budget_sol: numOrNull(r.daily_budget_sol),
max_price_impact_pct: clampNum(r.max_price_impact_pct, TRADE_LIMIT_DEFAULTS.max_price_impact_pct, { max: 100 }),
max_slippage_bps: clampNum(r.max_slippage_bps, TRADE_LIMIT_DEFAULTS.max_slippage_bps, { max: 10000, round: true }),
max_concurrent: r.max_concurrent == null ? null : clampNum(r.max_concurrent, null, { min: 1, max: 10000, round: true }),
kill_switch: r.kill_switch === true,
// cross-path USD spend policy — meta.spend_limits
daily_usd: numOrNull(r.daily_usd),
per_tx_usd: numOrNull(r.per_tx_usd),
withdraw_allowlist: normalizeAllowlist(r.withdraw_allowlist),
frozen: r.frozen === true,
};
}
// ── local guard predicates ────────────────────────────────────────────────────
// Each returns null when the trade clears, or { reason, detail } when blocked —
// the same shape and the same reason codes the server's guard predicates use.
function toLamports(sol) {
// SOL → lamports without float drift on the integer part (mirrors solToLamports).
if (sol == null) return null;
const [whole, frac = ''] = String(sol).split('.');
const fracPadded = (frac + '000000000').slice(0, 9);
return BigInt(whole || '0') * LAMPORTS_PER_SOL + BigInt(fracPadded || '0');
}
function lamportsToSolStr(lamports, dp = 4) {
const n = Number(BigInt(lamports)) / 1e9;
return n.toFixed(dp).replace(/\.?0+$/, '') || '0';
}
/** Discretionary trading paused for this agent. */
export function checkKillSwitch(killed) {
return killed ? { reason: 'kill_switch', detail: {} } : null;
}
/** Wallet freeze — blocks every autonomous path; owner withdraw stays open. */
export function checkFrozen(frozen, category) {
if (frozen && category !== 'withdraw') return { reason: 'wallet_frozen', detail: { category } };
return null;
}
/** Open-position concurrency ceiling. Blocked when openCount >= maxConcurrent. */
export function checkConcurrency(openCount, maxConcurrent) {
if (maxConcurrent == null) return null;
if (Number(openCount) >= Number(maxConcurrent)) {
return { reason: 'max_positions', detail: { open: Number(openCount), max: Number(maxConcurrent) } };
}
return null;
}
/** Per-trade spend cap (lamports). Blocked when amount > cap. */
export function checkPerTradeCap(amountLamports, capLamports) {
if (capLamports == null) return null;
const amt = BigInt(amountLamports);
const cap = BigInt(capLamports);
if (amt > cap) {
return { reason: 'per_trade_cap', detail: { amount_lamports: amt.toString(), cap_lamports: cap.toString() } };
}
return null;
}
/** Rolling daily budget (lamports). Blocked when spent + amount > budget. */
export function checkDailyBudgetLamports(spentLamports, amountLamports, budgetLamports) {
if (budgetLamports == null) return null;
const spent = BigInt(spentLamports);
const amt = BigInt(amountLamports);
const budget = BigInt(budgetLamports);
if (spent + amt > budget) {
return {
reason: 'daily_budget',
detail: { spent_lamports: spent.toString(), amount_lamports: amt.toString(), budget_lamports: budget.toString() },
};
}
return null;
}
/** Wallet must cover the spend plus a fee/rent headroom. Blocked when short. */
export function checkSolHeadroom(walletLamports, spendLamports, headroomLamports = SOL_FEE_HEADROOM_LAMPORTS) {
const wallet = BigInt(walletLamports);
const spend = BigInt(spendLamports);
const head = BigInt(headroomLamports);
if (wallet < spend + head) {
return {
reason: 'insufficient_sol',
detail: { wallet_lamports: wallet.toString(), required_lamports: (spend + head).toString() },
};
}
return null;
}
/** Price-impact circuit breaker. Blocked when impact > max. */
export function checkPriceImpact(priceImpactPct, maxPct) {
if (maxPct == null || priceImpactPct == null) return null;
if (Number(priceImpactPct) > Number(maxPct)) {
return { reason: 'price_impact', detail: { impact_pct: Number(priceImpactPct), max_pct: Number(maxPct) } };
}
return null;
}
/** Per-transaction USD ceiling. Blocked when usd > cap (with the server's 1e-9 slack). */
export function checkPerTxUsd(usdValue, perTxUsd, category = 'trade') {
if (perTxUsd == null || usdValue == null) return null;
if (Number(usdValue) > Number(perTxUsd) + 1e-9) {
return { reason: 'per_tx_exceeded', detail: { category, usd: Number(usdValue), per_tx_usd: Number(perTxUsd) } };
}
return null;
}
/** Rolling daily USD ceiling. Blocked when spentUsd + usd > cap. */
export function checkDailyUsd(spentUsd, usdValue, dailyUsd, category = 'trade') {
if (dailyUsd == null || usdValue == null) return null;
const spent = Number(spentUsd) || 0;
if (spent + Number(usdValue) > Number(dailyUsd) + 1e-9) {
return {
reason: 'daily_exceeded',
detail: { category, usd: Number(usdValue), spent_usd: spent, daily_usd: Number(dailyUsd) },
};
}
return null;
}
/** Withdraw allowlist — destination gate. Blocked when the target isn't allowed. */
export function checkAllowlist(destination, allowlist) {
if (!Array.isArray(allowlist) || allowlist.length === 0) return null;
const dest = typeof destination === 'string' ? destination.trim() : '';
if (!dest || !allowlist.includes(dest)) {
return { reason: 'destination_not_allowed', detail: { destination: dest || null, allowlist_size: allowlist.length } };
}
return null;
}
// Map a guard reason → an actionable, plain-language message — the same wording
// the server's GUARD_RESPONSE / SpendLimitError surface, so a UI reads identically
// whether the rejection came from here or the API.
const REASON_MESSAGE = {
kill_switch: () => 'Trading is paused for this agent. Re-enable discretionary trading under Limits & Safety to continue.',
wallet_frozen: () => 'This wallet is frozen. Autonomous spending (trades, snipes, payments) is paused. Unfreeze it under Limits & Safety to resume.',
per_trade_cap: (d) => `This trade of ${lamportsToSolStr(d.amount_lamports)} SOL is over the per-trade cap of ${lamportsToSolStr(d.cap_lamports)} SOL. Lower the amount or raise the cap under Limits & Safety.`,
daily_budget: (d) => `This trade would bring today's spend to ${lamportsToSolStr(BigInt(d.spent_lamports) + BigInt(d.amount_lamports))} SOL, over the daily budget of ${lamportsToSolStr(d.budget_lamports)} SOL. Wait for the window to roll over or raise the budget.`,
per_tx_exceeded: (d) => `This ${d.category} is $${Number(d.usd).toFixed(2)}, over the per-transaction limit of $${Number(d.per_tx_usd).toFixed(2)}.`,
daily_exceeded: (d) => `This ${d.category} would bring today's spend to $${(Number(d.spent_usd) + Number(d.usd)).toFixed(2)}, over the daily limit of $${Number(d.daily_usd).toFixed(2)}.`,
max_positions: (d) => `This agent already holds ${d.open} open ${d.open === 1 ? 'trade' : 'trades'} (max ${d.max}). Close one before opening another.`,
insufficient_sol: (d) => `The agent wallet needs about ${lamportsToSolStr(d.required_lamports)} SOL (including network fees) but holds ${lamportsToSolStr(d.wallet_lamports)}. Fund the wallet and retry.`,
price_impact: (d) => `Price impact is ${Number(d.impact_pct).toFixed(2)}% — above the ${Number(d.max_pct).toFixed(2)}% safety breaker. Lower the trade size or raise the impact limit under Limits & Safety.`,
destination_not_allowed: () => 'That destination is not on this agent’s withdraw allowlist. Add it under Limits & Safety, or send to an allowed address.',
};
function decision(blocked) {
if (!blocked) return { allow: true, reason: null, message: null, detail: {} };
const msg = REASON_MESSAGE[blocked.reason] || (() => `Trade rejected: ${blocked.reason}`);
return { allow: false, reason: blocked.reason, message: msg(blocked.detail || {}), detail: blocked.detail || {} };
}
/**
* Run a proposed transaction through every local guard, in the SAME order the
* server pipeline applies them. Returns `{ allow, reason, message, detail }`.
*
* `tx` describes the proposed movement and the live numbers the guards compare
* against (the caller fetches these — open count, 24h spend, wallet balance,
* quote — exactly as the server does):
* side 'buy' | 'sell' buys spend SOL; sells move SOL inward
* category 'trade'|'snipe'|'x402'|'withdraw' default 'trade'
* amountSol number SOL to spend on a buy (→ per-trade + daily-budget cap)
* amountLamports bigint alternative to amountSol, in lamports
* priceImpactPct number quoted price impact (→ breaker)
* walletLamports bigint current wallet balance (→ headroom)
* spentLamports bigint rolling-24h SOL buys (→ daily SOL budget)
* openCount number open discretionary positions (→ concurrency)
* usdValue number USD-equivalent of this tx (→ per-tx + daily USD)
* spentUsd number rolling-24h USD outflow (→ daily USD)
* destination string base58 recipient (→ withdraw allowlist)
*/
export function guard(tx = {}, pol = {}) {
const p = pol.__normalized ? pol : policy(pol);
const side = tx.side === 'sell' ? 'sell' : 'buy';
const category = tx.category || 'trade';
const isBuy = side === 'buy' && category === 'trade';
// 0. Freeze — blocks every autonomous path; owner withdraw stays open.
let blocked = checkFrozen(p.frozen, category);
if (blocked) return decision(blocked);
// Withdraw is an owner recovery path: only the allowlist gates it here.
if (category === 'withdraw') {
return decision(checkAllowlist(tx.destination, p.withdraw_allowlist));
}
// 1. Kill switch (discretionary trades).
blocked = checkKillSwitch(p.kill_switch);
if (blocked) return decision(blocked);
// 2. Price-impact breaker (buys and sells).
blocked = checkPriceImpact(tx.priceImpactPct, p.max_price_impact_pct);
if (blocked) return decision(blocked);
if (isBuy) {
const lamports = tx.amountLamports != null ? BigInt(tx.amountLamports) : toLamports(tx.amountSol);
if (lamports == null) {
throw new ThreeWsError('guard() needs `amountSol` or `amountLamports` for a buy.', { code: 'invalid_input' });
}
// 3. Per-trade SOL cap.
const capLamports = p.per_trade_sol == null ? null : toLamports(p.per_trade_sol);
blocked = checkPerTradeCap(lamports, capLamports);
if (blocked) return decision(blocked);
// 4. Concurrency ceiling.
blocked = checkConcurrency(tx.openCount ?? 0, p.max_concurrent);
if (blocked) return decision(blocked);
// 5. Rolling daily SOL budget.
const budgetLamports = p.daily_budget_sol == null ? null : toLamports(p.daily_budget_sol);
blocked = checkDailyBudgetLamports(tx.spentLamports ?? 0n, lamports, budgetLamports);
if (blocked) return decision(blocked);
// 6. Cross-path USD ceiling (per-tx, then rolling daily).
blocked = checkPerTxUsd(tx.usdValue, p.per_tx_usd, category);
if (blocked) return decision(blocked);
blocked = checkDailyUsd(tx.spentUsd, tx.usdValue, p.daily_usd, category);
if (blocked) return decision(blocked);
// 7. SOL fee/rent headroom floor.
if (tx.walletLamports != null) {
blocked = checkSolHeadroom(tx.walletLamports, lamports);
if (blocked) return decision(blocked);
}
return decision(null);
}
// Sell: only moves SOL inward, so it skips the spend caps but still honors the
// kill switch (above), the price-impact breaker (above), and the headroom floor.
if (tx.walletLamports != null) {
blocked = checkSolHeadroom(tx.walletLamports, 0n);
if (blocked) return decision(blocked);
}
return decision(null);
}
// ── shaping helpers for the HTTP client ────────────────────────────────────────
function shapeTradeLimits(raw) {
const l = raw || {};
return {
perTradeSol: l.per_trade_sol ?? null,
dailyBudgetSol: l.daily_budget_sol ?? null,
maxPriceImpactPct: l.max_price_impact_pct ?? null,
maxSlippageBps: l.max_slippage_bps ?? null,
maxConcurrent: l.max_concurrent ?? null,
killSwitch: Boolean(l.kill_switch),
updatedAt: l.updated_at ?? null,
raw: l,
};
}
function shapeSpendLimits(raw) {
const l = raw || {};
return {
dailyUsd: l.daily_usd ?? null,
perTxUsd: l.per_tx_usd ?? null,
withdrawAllowlist: Array.isArray(l.withdraw_allowlist) ? l.withdraw_allowlist : [],
frozen: Boolean(l.frozen),
updatedAt: l.updated_at ?? null,
raw: l,
};
}
function shapeDecision(data) {
const d = data || {};
const blocked = d.blocked_reason || null;
return {
allowed: Boolean(d.allowed),
reason: blocked ? blocked.code : null,
message: blocked ? blocked.message : null,
detail: blocked ? blocked.detail || {} : {},
side: d.side ?? null,
mint: d.mint ?? null,
venue: d.venue ?? null,
priceImpactPct: d.price_impact_pct ?? null,
raw: d,
};
}
function pruneBody(obj) {
const out = {};
for (const [k, v] of Object.entries(obj)) {
if (v === undefined) continue;
out[k] = v;
}
return out;
}
// ── HTTP client ────────────────────────────────────────────────────────────────
/**
* Create a guards client bound to a base URL + fetch + optional owner auth.
* Setting or reading a policy is an owner-only action — pass `apiKey` (a bearer
* token) or a session `cookie`. For paid/x402-gated callers, pass a payment-aware
* `fetch` (e.g. @three-ws/x402-fetch) and the http core auto-settles 402s.
*/
export function createGuards(options = {}) {
const request = createHttp(options);
const cookie = options.cookie || null;
function authHeaders(extra) {
const h = { ...(extra || {}) };
if (cookie) h.cookie = cookie;
return h;
}
/** Bind every call to one agent id — the ergonomic surface the README documents. */
function forAgent(agentId, opts = {}) {
const id = requireAgentId(agentId);
const sig = opts.signal;
async function getTradeLimits({ signal = sig } = {}) {
const res = await request(`/api/agents/${id}/trade/limits`, { headers: authHeaders(), signal });
const data = unwrap(res);
return { ...shapeTradeLimits(data.limits), defaults: data.defaults ?? null, raw: data };
}
async function setTradeLimits(patch, { signal = sig } = {}) {
if (!patch || typeof patch !== 'object') {
throw new ThreeWsError('setTradeLimits(patch) needs an object of limit keys to change.', { code: 'invalid_input' });
}
const res = await request(`/api/agents/${id}/trade/limits`, {
method: 'PUT', body: pruneBody(tradePatch(patch)), headers: authHeaders(), signal,
});
return shapeTradeLimits(unwrap(res).limits);
}
async function getSpendLimits({ network, signal = sig } = {}) {
const res = await request(`/api/agents/${id}/wallet/limits`, { query: { network }, headers: authHeaders(), signal });
const data = unwrap(res);
return {
...shapeSpendLimits(data.limits),
spentTodayUsd: data.spent_today_usd ?? null,
spentTodaySol: data.spent_today_sol ?? null,
raw: data,
};
}
async function setSpendLimits(patch, { network, signal = sig } = {}) {
if (!patch || typeof patch !== 'object') {
throw new ThreeWsError('setSpendLimits(patch) needs an object of limit keys to change.', { code: 'invalid_input' });
}
const res = await request(`/api/agents/${id}/wallet/limits`, {
method: 'PUT', query: { network }, body: pruneBody(spendPatch(patch)), headers: authHeaders(), signal,
});
return shapeSpendLimits(unwrap(res).limits);
}
// Build the /trade body shared by checkTrade (simulate) and trade (execute).
function tradeBody(input) {
validateTradeInput(input);
return pruneBody({
side: input.side,
mint: input.mint,
amount: input.amount,
slippageBps: input.slippageBps,
network: input.network,
idempotency_key: input.idempotencyKey,
});
}
/** Pre-flight a trade against every guard without moving funds (simulate:true). */
async function checkTrade(input, { signal = sig } = {}) {
// The quote endpoint returns the guard verdict + the numbers behind it.
const res = await request(`/api/agents/${id}/trade/quote`, {
method: 'POST', body: tradeBody(input), headers: authHeaders(), signal,
});
return shapeDecision(unwrap(res));
}
/** Execute the real trade — same quote → guard → sign → confirm pipeline. */
async function trade(input, { signal = sig } = {}) {
const res = await request(`/api/agents/${id}/trade`, {
method: 'POST', body: { ...tradeBody(input), simulate: input.simulate === true }, headers: authHeaders(), signal,
});
const data = unwrap(res);
return { ...data, raw: data };
}
return { id, getTradeLimits, setTradeLimits, getSpendLimits, setSpendLimits, checkTrade, trade };
}
return { forAgent };
}
// A module-level default client for the zero-config path: `import { guards }`.
let shared = null;
function defaultClient() {
return (shared ||= createGuards());
}
/**
* Bind the default client to one agent. `options.token` / `options.apiKey` is the
* owner's bearer token; `options.cookie` is a session; `options.baseUrl` overrides
* the origin. For one-off configs use `createGuards(options).forAgent(id)`.
*/
export function guards(agentId, options = {}) {
if (options.baseUrl || options.fetch || options.apiKey || options.token || options.cookie || options.headers) {
const apiKey = options.apiKey || options.token;
return createGuards({ ...options, apiKey }).forAgent(agentId, options);
}
return defaultClient().forAgent(agentId, options);
}
// ── input validation + patch normalization (pre-network) ───────────────────────
function requireAgentId(agentId) {
const id = typeof agentId === 'string' ? agentId.trim() : '';
if (!id) throw new ThreeWsError('guards(agentId) needs a non-empty agent id string.', { code: 'invalid_input' });
return encodeURIComponent(id);
}
const SIDES = ['buy', 'sell'];
function validateTradeInput(input) {
if (!input || typeof input !== 'object') {
throw new ThreeWsError('trade input must be an object { side, mint, amount }.', { code: 'invalid_input' });
}
if (!SIDES.includes(input.side)) {
throw new ThreeWsError(`Invalid side "${input.side}". Expected "buy" or "sell".`, { code: 'invalid_input' });
}
if (!input.mint || typeof input.mint !== 'string' || !BASE58_RE.test(input.mint.trim())) {
throw new ThreeWsError('trade input needs a base58 Solana `mint`.', { code: 'invalid_input' });
}
const isMax = input.side === 'sell' && (input.amount === 'max' || input.amount === 'MAX' || input.amount === 'all');
if (!isMax) {
const n = Number(input.amount);
if (!Number.isFinite(n) || n <= 0) {
throw new ThreeWsError(
input.side === 'buy'
? '`amount` (SOL to spend) must be a positive number.'
: '`amount` (tokens to sell) must be a positive number or "max".',
{ code: 'invalid_input' },
);
}
}
}
// Keep only recognized trade-limit keys so a typo never silently widens the leash.
function tradePatch(patch) {
const out = {};
for (const k of ['per_trade_sol', 'daily_budget_sol', 'max_price_impact_pct', 'max_slippage_bps', 'max_concurrent', 'kill_switch']) {
if (k in patch) out[k] = patch[k];
}
return out;
}
function spendPatch(patch) {
const out = {};
for (const k of ['daily_usd', 'per_tx_usd', 'withdraw_allowlist', 'frozen']) {
if (k in patch) out[k] = patch[k];
}
return out;
}
// Every limits/trade endpoint wraps its payload in { data: ... }.
function unwrap(res) {
if (!res || typeof res !== 'object') {
throw new ThreeWsError('Unexpected empty response from the agent-guards endpoint.', { code: 'bad_response' });
}
return res.data ?? res;
}