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.

7.6 KB
Raw Blame
// POST /api/agent/send-sol — the avatar widget's autonomous payout.
//
// The avatar holds a custodial Solana wallet (AVATAR_WALLET_SECRET). When the
// chat brain decides to pay (the `sendSol` tool) or a user clicks "send", the
// widget calls this endpoint. It converts a USD amount to SOL at the live
// price, signs with the avatar's key server-side, submits on-chain, and returns
// the confirmed signature.
//
// Body: { usd?: number, sol?: number, to?: string, memo?: string }
//   - Exactly one of `usd` / `sol` is required (USD preferred).
//   - `to` omitted → AVATAR_DEFAULT_RECIPIENT ("send me").
// Guardrails: per-call USD cap (AVATAR_MAX_SEND_USD), pubkey validation,
// IP rate-limit, optional shared-secret header (AVATAR_DEMO_TOKEN).

import { createHash, timingSafeEqual } from 'node:crypto';
import { z } from 'zod';
import { cors, json, method, readJson, wrap, error, rateLimited } from '../_lib/http.js';
import { parse } from '../_lib/validate.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { logAudit } from '../_lib/audit.js';
import { recordPaymentMetric } from '../_lib/axiom.js';
import {
	avatarWalletConfig,
	loadAvatarKeypair,
	getConnection,
	getSolBalance,
	solUsdPrice,
	sendSol,
	isValidPubkey,
	explorerTxUrl,
	explorerAccountUrl,
	LAMPORTS_PER_SOL,
} from '../_lib/avatar-wallet.js';

// A confirmed transfer leaves headroom for the signature fee (5000 lamports)
// plus a small priority cushion so the avatar never drains itself below fees.
const FEE_BUFFER_LAMPORTS = 15_000;

const bodySchema = z
	.object({
		usd: z.number().positive().max(1000).optional(),
		sol: z.number().positive().max(100).optional(),
		to: z.string().trim().min(32).max(64).optional(),
		memo: z.string().trim().max(160).optional(),
	})
	.refine((b) => b.usd != null || b.sol != null, {
		message: 'provide `usd` or `sol`',
	});

export default wrap(async (req, res) => {
	if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
	if (!method(req, res, ['POST'])) return;

	const cfg = avatarWalletConfig();
	if (!cfg.configured) {
		return error(
			res,
			503,
			'wallet_unconfigured',
			'avatar wallet is not configured. Set AVATAR_WALLET_SECRET (run scripts/gen-avatar-wallet.mjs).',
		);
	}

	// Optional shared-secret gate. When set, the widget must echo it.
	if (cfg.demoToken) {
		const provided = req.headers['x-avatar-token'];
		// Constant-time compare over fixed-length digests so the shared secret
		// cannot be recovered byte by byte from response timing.
		const digest = (v) => createHash('sha256').update(String(v ?? '')).digest();
		if (typeof provided !== 'string' || !timingSafeEqual(digest(provided), digest(cfg.demoToken))) {
			return error(res, 401, 'unauthorized', 'missing or invalid x-avatar-token');
		}
	}

	const rl = await limits.authIp(clientIp(req));
	if (!rl.success) return rateLimited(res, rl, 'too many payout requests, try again shortly');

	const body = parse(bodySchema, await readJson(req));

	// When the recipient is locked, the wallet can only ever pay the configured
	// default — any client-supplied `to` is ignored.
	let recipient;
	if (cfg.lockRecipient) {
		if (!cfg.defaultRecipient) {
			return error(res, 503, 'recipient_locked', 'AVATAR_LOCK_RECIPIENT is set but AVATAR_DEFAULT_RECIPIENT is missing');
		}
		recipient = cfg.defaultRecipient;
	} else {
		// Sending to a client-supplied address that isn't the configured default is
		// the drain vector: without a gate, anyone (rotating IPs past the per-IP
		// limit) can repeatedly pay themselves up to the per-send cap until the
		// wallet is empty. Require the demo-token gate to be configured before
		// honoring an arbitrary `to`; otherwise the wallet can only pay its default.
		if (body.to && body.to !== cfg.defaultRecipient && !cfg.demoToken) {
			return error(
				res,
				403,
				'recipient_not_allowed',
				'sends to arbitrary recipients require AVATAR_DEMO_TOKEN; otherwise set AVATAR_LOCK_RECIPIENT to pin payouts to AVATAR_DEFAULT_RECIPIENT',
			);
		}
		recipient = body.to || cfg.defaultRecipient;
	}
	if (!recipient) {
		return error(res, 400, 'no_recipient', 'no recipient: pass `to` or set AVATAR_DEFAULT_RECIPIENT');
	}
	if (!isValidPubkey(recipient)) {
		return error(res, 400, 'bad_recipient', 'recipient is not a valid Solana address');
	}

	let solPriceUsd;
	try {
		solPriceUsd = await solUsdPrice();
	} catch {
		return error(res, 502, 'price_unavailable', 'could not fetch the live SOL price, try again shortly');
	}

	// Resolve the amount in both USD and lamports, then enforce the USD cap.
	const usd = body.usd != null ? body.usd : body.sol * solPriceUsd;
	if (usd > cfg.maxSendUsd) {
		return error(
			res,
			400,
			'amount_too_large',
			`amount $${usd.toFixed(2)} exceeds the per-send cap of $${cfg.maxSendUsd.toFixed(2)}`,
		);
	}
	const solAmount = body.sol != null ? body.sol : usd / solPriceUsd;
	const lamports = Math.round(solAmount * LAMPORTS_PER_SOL);
	if (lamports <= 0) {
		return error(res, 400, 'amount_too_small', 'amount rounds to zero lamports');
	}

	// Wallet-wide daily payout ceiling (defense in depth on top of the per-send
	// cap + per-IP limit): bounds total outflow if the demo token leaks or a
	// caller rotates IPs. Keyed on the wallet pubkey so it's a single shared
	// budget. Checked here — after all validation — so failed requests don't burn it.
	const daily = await limits.avatarPayoutDaily(cfg.address);
	if (!daily.success) {
		return rateLimited(res, daily, 'avatar wallet has hit its daily payout limit, try again later');
	}

	const connection = getConnection(cfg.rpcUrl);
	const keypair = loadAvatarKeypair(process.env.AVATAR_WALLET_SECRET);

	// Balance guard — fail clearly before signing if the wallet can't cover it.
	const { lamports: balance } = await getSolBalance(connection, keypair.publicKey);
	if (balance < lamports + FEE_BUFFER_LAMPORTS) {
		return error(
			res,
			409,
			'insufficient_funds',
			`avatar wallet has ${(balance / LAMPORTS_PER_SOL).toFixed(5)} SOL, needs about ${((lamports + FEE_BUFFER_LAMPORTS) / LAMPORTS_PER_SOL).toFixed(5)} SOL. Fund ${cfg.address}.`,
			{ address: cfg.address, fundUrl: explorerAccountUrl(cfg.address, cfg.network) },
		);
	}

	let signature;
	const sendStartedAt = Date.now();
	try {
		signature = await sendSol({
			connection,
			fromKeypair: keypair,
			to: recipient,
			lamports,
			memo: body.memo || `three.ws avatar · $${usd.toFixed(2)} SOL`,
		});
	} catch (err) {
		recordPaymentMetric({
			kind: 'avatar_payout',
			status: 'failed',
			network: cfg.network,
			amountUsd: usd,
			latencyMs: Date.now() - sendStartedAt,
			reason: err?.message || 'unknown',
		});
		return error(res, 502, 'send_failed', `on-chain transfer failed: ${err?.message || 'unknown error'}`);
	}
	recordPaymentMetric({
		kind: 'avatar_payout',
		status: 'ok',
		network: cfg.network,
		amountUsd: usd,
		latencyMs: Date.now() - sendStartedAt,
		signature,
	});

	// Immutable trail for the one custodial money-out path: who triggered a
	// payout (by IP/UA — this endpoint is session-less, gated by demo-token /
	// recipient-lock), how much, and the on-chain signature. Reconciliation and
	// incident response depend on this row. Fire-and-forget; never blocks the response.
	logAudit({
		userId: null,
		action: 'avatar_payout',
		resourceId: signature,
		meta: {
			from: cfg.address,
			to: recipient,
			lamports,
			sol: solAmount,
			usd,
			sol_price_usd: solPriceUsd,
			network: cfg.network,
		},
		req,
	});

	return json(res, 200, {
		ok: true,
		signature,
		network: cfg.network,
		from: cfg.address,
		to: recipient,
		lamports,
		sol: solAmount,
		usd,
		solPriceUsd,
		explorer: explorerTxUrl(signature, cfg.network),
	});
});