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
// GET /api/monetization/withdrawals?agent_id=X lists withdrawal history
// POST /api/monetization/withdrawals requests a withdrawal
//
// Body (POST): { agent_id, amount_usdc?, network? }
// amount_usdc = null withdraw all available balance
// network 'solana' (default) | 'base' | 'evm'; picks which saved
// payout wallet, and therefore which balance, is drawn on
import { z } from 'zod';
import { sql } from '../_lib/db.js';
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { assertBearerMaySpend } from '../_lib/spend-scope.js';
import { cors, json, method, wrap, error, readJson, rateLimited } from '../_lib/http.js';
import { parse, isUuid } from '../_lib/validate.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { parseLimit, parseOffset } from '../_lib/http-params.js';
import { requireCsrf } from '../_lib/csrf.js';
import { getAvailableBalance } from '../_lib/monetization.js';
const MIN_WITHDRAWAL_USDC = 1; // 1 USDC minimum
const MIN_WITHDRAWAL_ATOMIC = MIN_WITHDRAWAL_USDC * 1_000_000;
// The lifecycle the payout cron (api/cron/[name].js) actually writes. Anything
// else in `?status=` is a caller typo, and answering it with an empty page
// reads as "you have no withdrawals" instead of "that filter is not a status".
const WITHDRAWAL_STATUSES = ['pending', 'processing', 'completed', 'failed'];
const postBody = z.object({
agent_id: z.string().uuid(),
amount_usdc: z.number().finite().positive().nullable().optional(),
// Which payout rail to draw on. Omitted means "use the saved preference",
// which falls back to Solana, the home chain.
network: z.enum(['solana', 'base', 'evm']).optional(),
});
// `base` and `evm` are the same rail: rows written by wallet.js carry chain
// 'base', while older rows carry 'evm'.
const NETWORK_CHAINS = {
solana: ['solana'],
base: ['base', 'evm'],
evm: ['base', 'evm'],
};
/**
* Choose the payout wallet a withdrawal should land on.
* An explicit `network` is honored exactly (no silent cross-chain fallback, so a
* caller asking for Base never gets paid on Solana). Otherwise the stored
* preference wins, then Solana, then whatever the user has configured.
*
* @param {Array<{address: string, chain: string, preferred_network: string|null}>} wallets
* Candidates, already ordered agent-specific first.
* @param {string|undefined} network
* @returns {{address: string, chain: string, preferred_network: string|null}|undefined}
*/
function pickPayoutWallet(wallets, network) {
const on = (net) => wallets.find((w) => (NETWORK_CHAINS[net] ?? []).includes(w.chain));
if (network) return on(network);
return on(wallets[0].preferred_network ?? 'solana') ?? on('solana') ?? wallets[0];
}
async function resolveUser(req) {
const session = await getSessionUser(req);
if (session) return { userId: session.id, source: 'session' };
const bearer = assertBearerMaySpend(await authenticateBearer(extractBearer(req)), req);
if (bearer) return { userId: bearer.userId, source: 'bearer' };
return null;
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'POST'])) return;
const auth = await resolveUser(req);
if (!auth) return error(res, 401, 'unauthorized', 'Sign in required');
const { userId } = auth;
const rl = await limits.authIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
if (req.method === 'GET') {
const params = new URL(req.url, 'http://x').searchParams;
const agentId = params.get('agent_id') || null;
const statusFilter = params.get('status') || null;
// clampInt-backed so `?limit=abc` falls back to the default page instead of
// binding NaN, which reaches Postgres as NULL and silently removes the LIMIT.
const limit = parseLimit(params, { fallback: 20, max: 100 });
const offset = parseOffset(params);
if (agentId && !isUuid(agentId)) {
return error(res, 400, 'validation_error', 'agent_id must be a UUID');
}
if (statusFilter && !WITHDRAWAL_STATUSES.includes(statusFilter)) {
return error(res, 400, 'validation_error', `status must be one of: ${WITHDRAWAL_STATUSES.join(', ')}`);
}
// Verify agent ownership if specified
if (agentId) {
const [agent] = await sql`
SELECT id, user_id FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
if (!agent) return error(res, 404, 'not_found', 'Agent not found');
if (agent.user_id !== userId) return error(res, 403, 'forbidden', 'You don\'t own this agent');
}
// Build withdrawal list query based on filters
let withdrawals;
if (agentId && statusFilter) {
withdrawals = await sql`
SELECT id, agent_id, amount, currency_mint, chain, to_address,
status, tx_signature, error_message, created_at, updated_at
FROM agent_withdrawals
WHERE user_id = ${userId} AND agent_id = ${agentId} AND status = ${statusFilter}
ORDER BY created_at DESC
LIMIT ${limit}::int OFFSET ${offset}::int
`;
} else if (agentId) {
withdrawals = await sql`
SELECT id, agent_id, amount, currency_mint, chain, to_address,
status, tx_signature, error_message, created_at, updated_at
FROM agent_withdrawals
WHERE user_id = ${userId} AND agent_id = ${agentId}
ORDER BY created_at DESC
LIMIT ${limit}::int OFFSET ${offset}::int
`;
} else if (statusFilter) {
withdrawals = await sql`
SELECT id, agent_id, amount, currency_mint, chain, to_address,
status, tx_signature, error_message, created_at, updated_at
FROM agent_withdrawals
WHERE user_id = ${userId} AND status = ${statusFilter}
ORDER BY created_at DESC
LIMIT ${limit}::int OFFSET ${offset}::int
`;
} else {
withdrawals = await sql`
SELECT id, agent_id, amount, currency_mint, chain, to_address,
status, tx_signature, error_message, created_at, updated_at
FROM agent_withdrawals
WHERE user_id = ${userId}
ORDER BY created_at DESC
LIMIT ${limit}::int OFFSET ${offset}::int
`;
}
// Get available balance for context
const balance = await getAvailableBalance(userId);
return json(res, 200, {
withdrawals: withdrawals.map(formatWithdrawal),
balance: {
earned_usdc: balance.earned / 1_000_000,
withdrawn_usdc: balance.withdrawn / 1_000_000,
pending_usdc: balance.pending / 1_000_000,
available_usdc: balance.available / 1_000_000,
},
});
}
// POST: request a withdrawal
const csrfOk = await requireCsrf(req, res, userId);
if (!csrfOk) return;
const rlUser = await limits.withdrawalPerUser(userId);
if (!rlUser.success) return rateLimited(res, rlUser, 'too many withdrawal requests');
const body = parse(postBody, await readJson(req));
const { agent_id, amount_usdc, network } = body;
// Verify agent ownership
const [agent] = await sql`
SELECT id, user_id FROM agent_identities
WHERE id = ${agent_id} AND deleted_at IS NULL
`;
if (!agent) return error(res, 404, 'not_found', 'Agent not found');
if (agent.user_id !== userId) return error(res, 403, 'forbidden', 'You don\'t own this agent');
// Resolve payout wallet. Agent-specific rows outrank the user-level fallback.
const wallets = await sql`
SELECT address, chain, preferred_network
FROM agent_payout_wallets
WHERE user_id = ${userId} AND (agent_id = ${agent_id} OR agent_id IS NULL)
AND approved_at IS NOT NULL AND effective_at <= now()
ORDER BY
CASE WHEN agent_id = ${agent_id} THEN 0 ELSE 1 END,
is_default DESC,
created_at DESC
`;
if (!wallets.length) {
// A replacement inside its cooldown, or one still waiting on the owner's
// approval, is not a payout wallet yet; say when it will be.
const [pending] = await sql`
SELECT address, chain, approved_at, effective_at FROM agent_payout_wallets
WHERE user_id = ${userId} AND (agent_id = ${agent_id} OR agent_id IS NULL)
ORDER BY effective_at ASC LIMIT 1
`;
if (pending) {
return error(res, 422, 'payout_wallet_pending', pending.approved_at
? `Your new payout wallet takes effect at ${new Date(pending.effective_at).toISOString()}; withdrawals resume then`
: 'Your payout wallet change is waiting for your approval in the inbox', { address: pending.address, chain: pending.chain, effective_at: pending.effective_at, approved: Boolean(pending.approved_at) });
}
return error(res, 422, 'no_payout_wallet', 'Configure a payout wallet before requesting a withdrawal');
}
// The chain decides the currency, and the currency decides which balance is
// withdrawable, so picking the wrong wallet strands real earnings. Taking the
// most recently saved row did exactly that: a user who added an EVM address
// after their Solana one could no longer withdraw Solana revenue, because the
// balance was then read in Base USDC and came back as zero.
const wallet = pickPayoutWallet(wallets, network);
if (!wallet) {
return error(res, 422, 'no_payout_wallet', `No payout wallet configured for ${network}`);
}
// Determine currency mint based on chain
const currencyMint = wallet.chain === 'solana'
? 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'
: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
// Calculate available balance
const balance = await getAvailableBalance(userId, currencyMint);
// Determine withdrawal amount
let amountAtomic;
if (amount_usdc === null || amount_usdc === undefined) {
// Withdraw all available
amountAtomic = balance.available;
} else {
amountAtomic = Math.round(amount_usdc * 1_000_000);
}
if (amountAtomic < MIN_WITHDRAWAL_ATOMIC) {
return error(res, 422, 'below_minimum', `Minimum withdrawal is ${MIN_WITHDRAWAL_USDC} USDC`);
}
if (amountAtomic > balance.available) {
return error(res, 422, 'insufficient_balance', `Insufficient balance for withdrawal. Available: ${(balance.available / 1_000_000).toFixed(6)} USDC`);
}
// Reserve the withdrawal atomically. The available-balance check above is a
// fast/UX pre-check only. On its own it is a TOCTOU hole: N concurrent
// requests all read the same `available` and all insert, over-withdrawing
// past the real balance (the per-user rate limit admits several before any
// pending row is committed, so it can't guarantee integrity).
//
// pg_advisory_xact_lock serializes concurrent requests for the same
// (user, mint); the conditional INSERT…SELECT then re-derives available
// (earned − pending/processing/completed, mirroring getAvailableBalance)
// inside the locked transaction and refuses to insert when the amount
// exceeds it. Matches api/billing/withdrawals/index.js.
const lockKey = `withdrawal:${userId}:${currencyMint}`;
const [, inserted] = await sql.transaction([
sql`select pg_advisory_xact_lock(hashtextextended(${lockKey}, 0))`,
sql`
INSERT INTO agent_withdrawals
(user_id, agent_id, amount, currency_mint, chain, to_address, status)
SELECT ${userId}, ${agent_id}, ${amountAtomic}, ${currencyMint}, ${wallet.chain}, ${wallet.address}, 'pending'
WHERE ${amountAtomic} <= (
(
SELECT COALESCE(SUM(re.net_amount), 0)::bigint
FROM agent_revenue_events re
JOIN agent_identities ai ON ai.id = re.agent_id
WHERE coalesce(re.owner_user_id, ai.user_id) = ${userId}
AND re.currency_mint = ${currencyMint}
AND NOT re.settled_to_wallet
) - (
SELECT COALESCE(SUM(w2.amount), 0)::bigint
FROM agent_withdrawals w2
WHERE w2.user_id = ${userId}
AND w2.currency_mint = ${currencyMint}
AND w2.status IN ('pending', 'processing', 'completed')
)
)
RETURNING id, agent_id, amount, currency_mint, chain, to_address, status, tx_signature, created_at, updated_at
`,
]);
const withdrawal = inserted?.[0];
if (!withdrawal) {
return error(res, 422, 'insufficient_balance', `Insufficient balance for withdrawal. Available: ${(balance.available / 1_000_000).toFixed(6)} USDC`);
}
return json(res, 201, {
withdrawal: formatWithdrawal(withdrawal),
balance: {
earned_usdc: balance.earned / 1_000_000,
withdrawn_usdc: balance.withdrawn / 1_000_000,
pending_usdc: (balance.pending + amountAtomic) / 1_000_000,
available_usdc: (balance.available - amountAtomic) / 1_000_000,
},
});
});
function formatWithdrawal(w) {
return {
id: w.id,
agent_id: w.agent_id,
amount_usdc: Number(w.amount) / 1_000_000,
amount_atomic: Number(w.amount),
currency_mint: w.currency_mint,
chain: w.chain,
destination_address: w.to_address,
status: w.status,
tx_hash: w.tx_signature ?? null,
error: w.error_message ?? null,
requested_at: w.created_at,
processed_at: w.updated_at !== w.created_at ? w.updated_at : null,
};
}