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/agents/:id/solana — wallet, activity, and airdrop handlers.
// Dispatched from api/agents/[id].js with the `action` sub-path.
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { assertBearerMaySpend } from '../_lib/spend-scope.js';
import { requireRealFundsAgreement } from '../_lib/real-funds-agreement.js';
import { sql } from '../_lib/db.js';
import { confirmOrThrow, pollConfirmation } from '../_lib/solana/confirm.js';
import { cors, json, method, error, readJson, rateLimited, serverError } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { requireCsrf } from '../_lib/csrf.js';
import { generateSolanaAgentWallet, recoverSolanaAgentKeypair, encryptSecret } from '../_lib/agent-wallet.js';
import { solanaConnection, solanaPublicConnection, isUnrecoverableSecret } from '../_lib/agent-pumpfun.js';
import { reverseLookupAddress } from '../../src/solana/sns.js';
import { maybeWritePatronMemory } from '../_lib/patronage.js';
import {
Keypair, PublicKey, LAMPORTS_PER_SOL, SystemProgram,
TransactionMessage, VersionedTransaction,
} from '@solana/web3.js';
import {
getAssociatedTokenAddressSync, createTransferCheckedInstruction,
createAssociatedTokenAccountIdempotentInstruction, createCloseAccountInstruction, getMint,
TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, ASSOCIATED_TOKEN_PROGRAM_ID,
} from '@solana/spl-token';
import { grindMintKeypair, estimateAttempts, BASE58_ALPHABET, addressMatchesPattern } from '../_lib/pump-vanity.js';
import { randomUUID } from 'node:crypto';
import { recordEvent } from '../_lib/usage.js';
import { cacheGet, cacheSet } from '../_lib/cache.js';
import { withDeadline, staleEnvelope } from '../_lib/rpc-degrade.js';
import { logAudit } from '../_lib/audit.js';
import { replaceSolanaList, activeAddresses, allowlistRow, getWhitelist } from '../_lib/destination-whitelist.js';
import { explorerTxUrl } from '../_lib/avatar-wallet.js';
import {
validateSolanaAddress, enforceSpendLimit, SpendLimitError, lamportsToUsd,
getSpendLimits, setSpendLimits, listCustodyEvents, updateCustodyEvent, recordCustodyEvent,
getDailySpendUsd, getTradeLimits, setTradeLimits, getDailySpendLamports,
getBurnerPolicy, setBurnerPolicy, getAutoSpendUsd,
setPolicyRules, getPolicyRules, checkDestinationSweepRisk,
} from '../_lib/agent-trade-guards.js';
// Natural-language spend policies — owner authors rules in English (compiler),
// code enforces them deterministically (rules engine). Owner-only Policy surface.
import {
describePolicyRules, backtestPolicy, syntheticProbes, normalizePolicyRules, MAX_RULES,
} from '../_lib/spend-policy-rules.js';
import { compilePolicyFromText } from '../_lib/spend-policy-compiler.js';
import { registerDelegation, getActiveDelegation, DelegationError } from '../_lib/agent-spend-delegation.js';
// SOL-outflow spend policy enforced on agent-signed launches/buys/swaps. Exposed
// read-only on the limits GET so the launch console can show the real ceiling.
import { resolveSpendPolicy } from '../_lib/agent-spend-policy.js';
import { getBalances, walletUsdTotal } from '../_lib/balances.js';
import {
THREE_MINT, computeLook, computeMarks, normalizePrefs,
} from '../_lib/networth-model.js';
import {
getRoyaltyConfig, clampCreatorBps, getDescendantLedger, getAncestorLedger,
ROYALTY_PER_CREATOR_CAP_BPS, ROYALTY_TOTAL_CAP_BPS, ROYALTY_ELIGIBLE_ASSET,
} from '../_lib/fork-royalties.js';
// USDC mints per cluster — the only SPL token we can price 1:1 for the spend
// ceiling without an external quote. $THREE is the only coin; USDC is the
// payment-rail asset, not a coin we promote.
const USDC_MINT_BY_CLUSTER = {
mainnet: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
devnet: '4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU',
};
// SOL "max" headroom: keep the account rent-exempt and leave fee budget so a
// sweep can never brick the wallet or fail on fees.
const SOL_FEE_RESERVE_LAMPORTS = 15_000n; // ~3× a single-signature base fee
const RENT_EXEMPT_FALLBACK_LAMPORTS = 890_880n; // getMinimumBalanceForRentExemption(0)
const TOKEN_ACCOUNT_RENT_FALLBACK_LAMPORTS = 2_039_280n; // 165-byte SPL token account
const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]+$/;
const AIRDROP_LAMPORTS = LAMPORTS_PER_SOL;
// ── Solana RPC cache ──────────────────────────────────────────────────────────
// Keys: "sol:bal:<address>:<network>" and "sol:sigs:<address>:<network>:<limit>"
// Prevents Helius free-plan 429s on repeated wallet card polls.
//
// Backed by the shared cache adapter (Upstash Redis when configured, in-memory
// otherwise). Redis matters here: Vercel runs many serverless replicas, and a
// per-replica Map only dedupes RPC calls within one warm instance — under real
// traffic every replica still hammers the RPC. A shared 60 s window collapses
// that to at most one balance fetch per address per minute across the fleet.
const SOL_CACHE_TTL_S = 60;
// Map an RPC failure to a stable code the wallet card can render. We surface
// rate-limiting distinctly so the UI shows "Balance unavailable" instead of a
// misleading "0 SOL" when the RPC is throttled rather than the wallet empty.
function classifyBalanceError(err) {
const msg = err?.message || '';
const rateLimited = err?.status === 429 || /\b429\b|rate.?limit|too many|max usage/i.test(msg);
return rateLimited ? 'rpc_rate_limited' : 'rpc_error';
}
/**
* The agent wallet's SOL balance exactly as the wallet card shows it: the same
* 60s fleet cache, the same primary-then-public RPC fallback. Every surface that
* quotes "your balance" (the chat gateways' /balance, for one) reads it here so
* the numbers can never disagree.
* @returns {Promise<{ lamports:number|null, error:string|null }>}
*/
export async function readAgentSolBalance(address, network) {
const net = network === 'devnet' ? 'devnet' : 'mainnet';
const key = `sol:bal:${address}:${net}`;
const cached = await cacheGet(key);
if (cached !== null) return { lamports: cached, error: null };
const res = await _solRpcWithBackoffFallback(
solanaConnection(net),
solanaPublicConnection(net),
(c) => c.getBalance(new PublicKey(address)),
'getBalance',
);
if (!res.ok) return { lamports: null, error: classifyBalanceError(res.error) };
await cacheSet(key, res.value, SOL_CACHE_TTL_S);
return { lamports: res.value, error: null };
}
// Calls `fn(conn)` with exponential backoff (500 ms → 1000 ms) before the
// public-RPC fallback fires. Returns { ok, value } or { ok: false, error }.
async function _solRpcWithBackoffFallback(primaryConn, fallbackConn, fn, label) {
// Attempt 1 — primary
try {
return { ok: true, value: await fn(primaryConn) };
} catch (err1) {
const is429 =
err1?.message?.includes('429') ||
err1?.message?.includes('Too Many Requests') ||
err1?.status === 429;
console.warn(`[agents/solana] ${label} primary failed${is429 ? ' (429)' : ''}: ${err1?.message || err1}`);
// 500 ms wait before first retry
await new Promise((r) => setTimeout(r, 500));
// Attempt 2 — retry primary (backoff)
try {
return { ok: true, value: await fn(primaryConn) };
} catch (err2) {
console.warn(`[agents/solana] ${label} primary retry failed: ${err2?.message || err2}`);
// 1000 ms wait before falling back to public RPC
await new Promise((r) => setTimeout(r, 1_000));
}
}
// Attempt 3 — public fallback
if (fallbackConn) {
try {
return { ok: true, value: await fn(fallbackConn) };
} catch (err3) {
console.error(`[agents/solana] ${label} fallback failed: ${err3?.message || err3}`);
return { ok: false, error: err3 };
}
}
return { ok: false, error: new Error(`${label}: all RPC attempts failed`) };
}
// Bonfida reverse-lookup is rate-limited and pulls a few KB per call. Memoize
// 10 minutes per-address so wallet card refreshes (every 30s) don't refetch.
const SNS_CACHE_TTL_MS = 10 * 60_000;
const _snsCache = new Map();
async function _reverseSnsCached(address) {
const hit = _snsCache.get(address);
if (hit && Date.now() - hit.at < SNS_CACHE_TTL_MS) return hit.value;
let value = null;
try { value = await reverseLookupAddress(address); } catch { value = null; }
_snsCache.set(address, { at: Date.now(), value });
return value;
}
// Encrypt a custodial Solana secret for storage. Delegates to the shared secret
// box so imported / regenerated wallets are written with the SAME v2 scheme
// (dedicated WALLET_ENCRYPTION_KEY + random per-record salt) as freshly-generated
// ones. Previously this path wrote a weaker v1 ciphertext (JWT_SECRET + constant
// salt); recoverSolanaAgentKeypair still reads those legacy records.
const _encryptSecret = (plaintext) => encryptSecret(plaintext);
// A bearer needs wallet:write for any write here (import/wipe a key, withdraw,
// policy edits). `spendCheck: false` defers that to a handler that first learns
// whether the request is a no-funds simulation (the withdraw preview).
async function resolveAuth(req, { spendCheck = true } = {}) {
const session = await getSessionUser(req);
if (session) return { userId: session.id, sessionId: session.sid || null };
const bearer = await authenticateBearer(extractBearer(req));
if (!bearer) return null;
if (spendCheck) assertBearerMaySpend(bearer, req);
return { userId: bearer.userId, bearer };
}
// A deposit address is safe to advertise only when the stored custodial key can
// actually sign for that exact address. Balance reads alone cannot prove this:
// an address whose encryption key was retired still has a perfectly valid,
// publicly-readable on-chain balance. Keep this verdict in the API so every
// funding surface can fail closed instead of independently guessing from the
// presence of an address.
async function walletSigningStatus(meta = {}) {
if (!meta.solana_address) return { signable: false, reason: 'wallet_missing' };
if (!meta.encrypted_solana_secret) return { signable: false, reason: 'key_missing' };
try {
const keypair = await recoverSolanaAgentKeypair(meta.encrypted_solana_secret);
if (keypair.publicKey.toBase58() !== meta.solana_address) {
return { signable: false, reason: 'key_mismatch' };
}
return { signable: true, reason: null };
} catch (e) {
return {
signable: false,
reason: isUnrecoverableSecret(e) ? 'key_retired' : 'key_error',
};
}
}
// ── activity ──────────────────────────────────────────────────────────────────
async function handleActivity(req, res, id) {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET'])) return;
const auth = await resolveAuth(req);
if (!auth) return error(res, 401, 'unauthorized', 'sign in required');
const rl = await limits.walletRead(auth.userId);
if (!rl.success) return rateLimited(res, rl);
const [row] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
if (row.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');
const address = row.meta?.solana_address;
if (!address) return error(res, 404, 'not_found', 'agent has no solana wallet');
const url = new URL(req.url, 'http://x');
const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
const limit = Math.min(parseInt(url.searchParams.get('limit') || '20', 10) || 20, 50);
const pk = new PublicKey(address);
const primaryConn = solanaConnection(network);
const fallbackConn = solanaPublicConnection(network);
const sigsCacheKey = `sol:sigs:${address}:${network}:${limit}`;
let sigs = await cacheGet(sigsCacheKey);
if (sigs === null) {
const sigInfos = await _solRpcWithBackoffFallback(
primaryConn,
fallbackConn,
(c) => c.getSignaturesForAddress(pk, { limit }),
'getSignaturesForAddress',
);
if (!sigInfos.ok) {
console.error('[agents/solana/activity] signature fetch failed on all RPCs', sigInfos.error);
return error(res, 502, 'rpc_error', 'failed to fetch on-chain activity');
}
sigs = sigInfos.value;
await cacheSet(sigsCacheKey, sigs, SOL_CACHE_TTL_S);
}
// getParsedTransactions is the expensive call and the one most often rate-limited.
// Degrade gracefully: if it fails everywhere, we still return the signature list
// without the lamport delta / summary enrichment instead of 502-ing the whole call.
let parsed = null;
if (sigs.length) {
const parsedRes = await _solRpcWithBackoffFallback(
primaryConn,
fallbackConn,
(c) => c.getParsedTransactions(sigs.map((s) => s.signature), {
maxSupportedTransactionVersion: 1,
commitment: 'confirmed',
}),
'getParsedTransactions',
);
if (parsedRes.ok) {
parsed = parsedRes.value;
} else {
console.warn('[agents/solana/activity] parsed-tx enrichment unavailable', parsedRes.error?.message);
}
}
const signatures = sigs.map((s, i) => {
const tx = parsed?.[i] ?? null;
let lamportDelta = null;
let summary = null;
if (tx?.meta && tx?.transaction) {
const keys = tx.transaction.message.accountKeys.map((k) => k.pubkey?.toString());
const idx = keys.indexOf(address);
if (idx >= 0 && tx.meta.preBalances && tx.meta.postBalances) {
lamportDelta = tx.meta.postBalances[idx] - tx.meta.preBalances[idx];
}
const ix = tx.transaction.message.instructions?.[0];
if (ix?.parsed?.type) summary = ix.parsed.type;
else if (ix?.programId) summary = `program ${ix.programId.toString().slice(0, 6)}…`;
}
return {
signature: s.signature,
slot: s.slot,
block_time: s.blockTime ?? null,
success: !s.err && !tx?.meta?.err,
error: s.err || tx?.meta?.err || null,
lamport_delta: lamportDelta,
sol_delta: lamportDelta == null ? null : lamportDelta / 1e9,
summary,
};
});
return json(res, 200, {
data: { address, network, signatures, parsed_available: parsed !== null },
});
}
// ── airdrop ───────────────────────────────────────────────────────────────────
async function handleAirdrop(req, res, id) {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const auth = await resolveAuth(req);
if (!auth) return error(res, 401, 'unauthorized', 'sign in required');
const rl = await limits.authIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const [row] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
if (row.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');
const address = row.meta?.solana_address;
if (!address) return error(res, 404, 'not_found', 'agent has no solana wallet');
let signature;
try {
const conn = solanaConnection('devnet');
signature = await conn.requestAirdrop(new PublicKey(address), AIRDROP_LAMPORTS);
await confirmOrThrow(conn, signature, 'confirmed');
} catch (err) {
console.error('[agents/solana/airdrop] failed', err);
return error(res, 502, 'faucet_unavailable',
err?.message?.includes('429') || err?.message?.includes('limit')
? 'Devnet faucet is rate-limited — try again in a minute.'
: `Devnet airdrop failed: ${err?.message || 'unknown'}`);
}
recordEvent({ userId: auth.userId, agentId: id, kind: 'solana_airdrop', tool: 'devnet', status: 'ok', meta: { address, signature, lamports: AIRDROP_LAMPORTS } });
return json(res, 200, { data: { signature, address, network: 'devnet', lamports: AIRDROP_LAMPORTS, sol: AIRDROP_LAMPORTS / 1e9 } });
}
// ── public wallet read ─────────────────────────────────────────────────────────
// GET /api/agents/:id/solana — no auth required. Returns wallet address + balance
// so external services (explorers, dashboards, other agents) can look up an
// agent's on-chain identity without a session. Write operations (POST, DELETE)
// still require owner auth — see handleWallet below.
async function handlePublicWalletRead(req, res, id) {
const url = new URL(req.url, 'http://x');
const network = (url.searchParams.get('network') || 'mainnet').toString();
const net = network === 'devnet' ? 'devnet' : 'mainnet';
const [row] = await sql`SELECT id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
const address = row.meta?.solana_address ?? null;
if (!address) {
return json(res, 200, {
data: {
agentId: id,
wallet: null,
balance: null,
chain: 'solana',
deposits_enabled: false,
deposits_disabled_reason: 'wallet_missing',
},
});
}
const signing = await walletSigningStatus(row.meta);
let lamports = null;
let balanceError = null;
const balCacheKey = `sol:bal:${address}:${net}`;
const cached = await cacheGet(balCacheKey);
if (cached !== null) {
lamports = cached;
} else {
const balResult = await _solRpcWithBackoffFallback(
solanaConnection(net),
solanaPublicConnection(net),
(c) => c.getBalance(new PublicKey(address)),
'getBalance',
);
if (balResult.ok) {
lamports = balResult.value;
await cacheSet(balCacheKey, lamports, SOL_CACHE_TTL_S);
} else {
balanceError = classifyBalanceError(balResult.error);
}
}
console.info(`[agents/solana] public read agentId=${id} address=${address} net=${net} lamports=${lamports}${balanceError ? ` balance_error=${balanceError}` : ''}`);
return json(res, 200, {
data: {
agentId: id,
wallet: address,
balance: lamports == null ? null : lamports / 1e9,
chain: 'solana',
network: net,
lamports,
deposits_enabled: signing.signable,
...(!signing.signable ? { deposits_disabled_reason: signing.reason } : {}),
...(balanceError ? { balance_error: balanceError } : {}),
},
});
}
// ── wallet ────────────────────────────────────────────────────────────────────
async function handleWallet(req, res, id) {
if (cors(req, res, { methods: 'GET,POST,DELETE,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'POST', 'DELETE'])) return;
const auth = await resolveAuth(req);
// Unauthenticated GET: serve public wallet info without requiring sign-in.
// Write operations (POST, DELETE) still require owner auth below.
if (req.method === 'GET' && !auth) return handlePublicWalletRead(req, res, id);
if (!auth) return error(res, 401, 'unauthorized', 'sign in required');
const rl = req.method === 'GET'
? await limits.walletRead(auth.userId)
: await limits.authIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const [row] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
// A signed-in visitor browsing someone else's agent gets the public wallet
// card, not a 403 — the same read an unauthenticated visitor gets. Only the
// mutating methods (POST/DELETE provision/import/wipe the keypair) are
// owner-gated below.
if (row.user_id !== auth.userId) {
if (req.method === 'GET') return handlePublicWalletRead(req, res, id);
return error(res, 403, 'forbidden', 'not your agent');
}
// Provisioning, importing, and wiping a custodial keypair all change which
// keys control the agent's funds — gate the mutating methods behind CSRF so
// a cross-site forged request can never replace or delete the wallet.
if (req.method !== 'GET' && !(await requireCsrf(req, res, auth.userId))) return;
let meta = { ...(row.meta || {}) };
if (req.method === 'DELETE') {
delete meta.solana_address;
delete meta.encrypted_solana_secret;
delete meta.solana_vanity_prefix;
delete meta.solana_vanity_suffix;
delete meta.solana_wallet_source;
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${id}`;
return json(res, 200, { data: { ok: true } });
}
if (req.method === 'POST') {
const body = await readJson(req).catch(() => ({}));
const importing = body && (body.secret_key || body.vanity_prefix || body.vanity_suffix);
if (importing) {
const sk = body.secret_key;
if (!Array.isArray(sk) || sk.length !== 64 || !sk.every((n) => Number.isInteger(n) && n >= 0 && n <= 255)) {
return error(res, 400, 'validation_error', 'secret_key must be a 64-byte number array');
}
let kp;
try { kp = Keypair.fromSecretKey(Uint8Array.from(sk)); }
catch { return error(res, 400, 'validation_error', 'secret_key did not parse as a valid Solana keypair'); }
const address = kp.publicKey.toBase58();
if (body.vanity_prefix) {
if (!BASE58_RE.test(body.vanity_prefix) || body.vanity_prefix.length > 6) return error(res, 400, 'validation_error', 'vanity_prefix is not valid base58 (max 6 chars)');
if (!address.startsWith(body.vanity_prefix)) return error(res, 400, 'validation_error', 'vanity_prefix does not match the keypair address');
}
if (body.vanity_suffix) {
if (!BASE58_RE.test(body.vanity_suffix) || body.vanity_suffix.length > 6) return error(res, 400, 'validation_error', 'vanity_suffix is not valid base58 (max 6 chars)');
if (!address.endsWith(body.vanity_suffix)) return error(res, 400, 'validation_error', 'vanity_suffix does not match the keypair address');
}
if (meta.solana_address) return error(res, 409, 'conflict', 'agent already has a Solana wallet — DELETE /api/agents/:id/solana first to replace');
const encrypted_secret = await _encryptSecret(Buffer.from(kp.secretKey).toString('base64'));
meta = {
...meta,
solana_address: address,
encrypted_solana_secret: encrypted_secret,
solana_wallet_source: 'imported_vanity',
...(body.vanity_prefix ? { solana_vanity_prefix: body.vanity_prefix } : {}),
...(body.vanity_suffix ? { solana_vanity_suffix: body.vanity_suffix } : {}),
};
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${id}`;
} else if (!meta.solana_address) {
try {
const sol = await generateSolanaAgentWallet();
meta = { ...meta, solana_address: sol.address, encrypted_solana_secret: sol.encrypted_secret, solana_wallet_source: 'generated' };
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${id}`;
} catch (e) {
console.error('[agents/solana] wallet generation failed', e);
return serverError(res, 502, 'provision_failed', e);
}
}
}
if (!meta.solana_address) return error(res, 404, 'not_found', 'agent has no solana wallet — POST to provision');
const network = (req.query?.network || new URL(req.url, 'http://x').searchParams.get('network') || 'mainnet').toString();
const net = network === 'devnet' ? 'devnet' : 'mainnet';
const { lamports, error: balanceError } = await readAgentSolBalance(meta.solana_address, net);
// SNS is mainnet-only. Skip the lookup on devnet — it always returns null
// and just burns a network round-trip. Prefer the user's manually-attached
// SNS id (meta.sns_domain) over the on-chain favorite so the wallet card
// matches whatever they picked on the SNS dashboard.
const attachedSns = meta.sns_domain ? `${meta.sns_domain}.sol` : null;
const favoriteSns = net === 'mainnet' && !attachedSns
? await _reverseSnsCached(meta.solana_address)
: null;
// Can we still SIGN for this wallet, or are we showing a balance whose funds
// can never move? A custodial secret sealed under a retired WALLET_ENCRYPTION_KEY
// still reads back a perfectly healthy on-chain balance, so the wallet card looked
// identical to a working one right up until the owner typed an amount, confirmed a
// withdrawal, and got a 500. Measured 2026-08-01: two customer agents holding
// 0.35 SOL are in exactly that state. The check is a local AES-GCM attempt on one
// record (no network, sub-millisecond). The public read exposes only the deposit
// safety verdict; the owner read additionally exposes the signing verdict.
const signing = await walletSigningStatus(meta);
const signable = signing.signable;
const signableReason = signing.reason;
return json(res, req.method === 'POST' ? 201 : 200, {
data: {
address: meta.solana_address,
network,
lamports,
sol: lamports == null ? null : lamports / 1e9,
...(balanceError ? { balance_error: balanceError } : {}),
signable,
...(signableReason ? { signable_reason: signableReason } : {}),
deposits_enabled: signable,
...(!signable ? { deposits_disabled_reason: signableReason } : {}),
vanity_prefix: meta.solana_vanity_prefix || null,
vanity_suffix: meta.solana_vanity_suffix || null,
source: meta.solana_wallet_source || (meta.encrypted_solana_secret ? 'generated' : null),
sns_domain: attachedSns || favoriteSns,
sns_source: attachedSns ? 'attached' : (favoriteSns ? 'favorite' : null),
},
});
}
// ── owner gate ──────────────────────────────────────────────────────────────
// Shared loader for the owner-only custody handlers: auth → load agent → verify
// ownership → return the custodial wallet's address + encrypted secret + meta.
// Returns { error } (already-shaped) on any failure so callers can early-return.
async function loadOwnedWallet(req, res, id, authOpts) {
const auth = await resolveAuth(req, authOpts);
if (!auth) { error(res, 401, 'unauthorized', 'sign in required'); return { error: true }; }
const [row] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) { error(res, 404, 'not_found', 'agent not found'); return { error: true }; }
if (row.user_id !== auth.userId) { error(res, 403, 'forbidden', 'not your agent'); return { error: true }; }
const meta = { ...(row.meta || {}) };
return { auth, meta, address: meta.solana_address || null, encryptedSecret: meta.encrypted_solana_secret || null };
}
// ── withdraw / sweep ──────────────────────────────────────────────────────────
// POST /api/agents/:id/solana/withdraw (also aliased at /api/agents/:id/wallet/withdraw)
// Owner-authenticated. Sweeps SOL or a held SPL token from the agent's custodial
// wallet to an owner-chosen address, signed server-side. Idempotent, governed by
// the shared spend policy, rent + fee reserved on a SOL "max".
async function handleWithdraw(req, res, id) {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const owned = await loadOwnedWallet(req, res, id, { spendCheck: false });
if (owned.error) return;
const { auth, meta, address: fromAddress, encryptedSecret } = owned;
// Owner-only daily withdraw cap + per-IP burst guard.
const rlUser = await limits.withdrawalPerUser(auth.userId);
if (!rlUser.success) return rateLimited(res, rlUser);
const rlIp = await limits.authIp(clientIp(req));
if (!rlIp.success) return rateLimited(res, rlIp);
if (!fromAddress || !encryptedSecret) {
return error(res, 404, 'not_found', 'agent has no solana wallet to withdraw from');
}
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
const network = body.network === 'devnet' ? 'devnet' : 'mainnet';
const asset = typeof body.asset === 'string' && body.asset.trim() ? body.asset.trim() : 'SOL';
const simulate = body.simulate === true;
// Set once the owner has already seen the blocking sweeper-bot confirm for
// this exact destination (surfaced on the simulate response below) and chose
// to send anyway.
const sweepRiskAck = body.sweep_risk_ack === true;
// A wallet balance promised to marketplace bidders cannot be withdrawn out
// from under them: once a listing that includes the balance has an escrowed
// bid (or is settling), the balance belongs to the sale.
if (!simulate) {
const [promised] = await sql`
SELECT l.id FROM agent_listings l
WHERE l.agent_id = ${id} AND l.include_balance
AND (l.status = 'settling' OR (l.status = 'active' AND EXISTS (
SELECT 1 FROM agent_listing_bids b WHERE b.listing_id = l.id AND b.status = 'open')))
LIMIT 1
`;
if (promised) {
return error(res, 409, 'balance_listed',
'this wallet\'s balance is part of a marketplace listing with open bids; delist it at /marketplace/agents/dashboard before withdrawing');
}
}
// CSRF: sweeping a custodial wallet is the single highest-stakes action on the
// platform — it must be at least as protected as message-signing. Bearer/API-key
// callers are exempt inside requireCsrf (the token is itself proof of intent). A
// `simulate` request moves no funds and never touches the key (it returns a live
// preview, like the trade endpoint's preview), so it is CSRF-exempt — otherwise a
// read-back/quote would burn the owner's single-use token before they confirm.
// Real funds leave a custodial wallet only for an account that has signed
// the real-funds agreements. Checked before CSRF so a refusal does not burn
// the owner's single-use token.
if (!simulate) assertBearerMaySpend(auth.bearer, req);
if (!simulate && !(await requireRealFundsAgreement(req, res, { userId: auth.userId, network, context: 'withdraw' }))) return;
if (!simulate && !(await requireCsrf(req, res, auth.userId))) return;
const idempotencyKey =
typeof body.idempotency_key === 'string' && body.idempotency_key.trim()
? body.idempotency_key.trim().slice(0, 128)
: randomUUID();
// 1. Validate destination — base58, on-curve, not the wallet itself.
const dest = validateSolanaAddress(body.destination);
if (!dest.valid) {
return error(res, 400, 'invalid_destination', `destination is not a valid Solana address (${dest.reason})`);
}
if (!dest.onCurve) {
return error(res, 400, 'invalid_destination', 'destination is a program address (off-curve) — funds sent there may be unrecoverable');
}
if (dest.base58 === fromAddress) {
return error(res, 400, 'invalid_destination', 'destination is the agent wallet itself');
}
const isMax = body.amount === 'max' || body.amount === 'MAX';
const amountNum = isMax ? null : Number(body.amount);
if (!isMax && (!Number.isFinite(amountNum) || amountNum <= 0)) {
return error(res, 400, 'invalid_amount', 'amount must be a positive number or "max"');
}
// 2. Fast-path idempotency check — a retry of a finished/in-flight withdraw.
{
const [existing] = await sql`
SELECT id, status, signature FROM agent_custody_events
WHERE agent_id = ${id} AND idempotency_key = ${idempotencyKey}
`;
if (existing) {
if (existing.status === 'confirmed') {
return json(res, 200, { data: { replayed: true, signature: existing.signature, explorer: explorerTxUrl(existing.signature, network), network } });
}
if (existing.status === 'pending') {
return error(res, 409, 'withdrawal_in_progress', 'a withdrawal with this id is already in flight — check the audit log before retrying', { signature: existing.signature || null });
}
return error(res, 409, 'withdrawal_failed', 'this withdrawal id already failed — retry with a fresh idempotency key', { signature: existing.signature || null });
}
}
const conn = solanaConnection(network);
const fromPk = new PublicKey(fromAddress);
let lamports = null; // SOL amount being sent (lamports) — null for SPL
let amountRaw = null; // SPL token base units — null for SOL
let decimals = 9;
let humanAmount = null;
let usdValue = null;
let priceNote = null;
let tokenProgramId = null;
let mintPk = null;
let sourceAta = null;
let destAta = null;
let destAtaExists = true;
let balanceLamports;
try {
balanceLamports = BigInt(await conn.getBalance(fromPk, 'confirmed'));
} catch (e) {
return error(res, 502, 'rpc_error', 'could not read the wallet balance — try again');
}
if (asset === 'SOL') {
let rentReserve;
try {
rentReserve = BigInt(await conn.getMinimumBalanceForRentExemption(0));
} catch {
rentReserve = RENT_EXEMPT_FALLBACK_LAMPORTS;
}
if (isMax) {
const spendable = balanceLamports - rentReserve - SOL_FEE_RESERVE_LAMPORTS;
if (spendable <= 0n) {
return error(res, 400, 'insufficient_balance', 'not enough SOL to withdraw after reserving rent and network fees');
}
lamports = spendable;
} else {
lamports = BigInt(Math.round(amountNum * 1e9));
if (lamports <= 0n) return error(res, 400, 'invalid_amount', 'amount rounds to zero lamports');
if (balanceLamports - lamports < rentReserve + SOL_FEE_RESERVE_LAMPORTS) {
return error(res, 400, 'insufficient_balance', 'amount leaves too little SOL to cover rent and network fees — lower it or use "max"');
}
}
humanAmount = Number(lamports) / 1e9;
try {
usdValue = await lamportsToUsd(lamports);
} catch {
usdValue = null;
priceNote = 'sol_price_unavailable';
}
} else {
// SPL token — resolve the mint, its token program, decimals, and balances.
const mintCheck = validateSolanaAddress(asset);
if (!mintCheck.valid) return error(res, 400, 'invalid_asset', 'asset must be "SOL" or a valid SPL mint address');
mintPk = mintCheck.pubkey;
let mintAcc;
try {
mintAcc = await conn.getAccountInfo(mintPk);
} catch {
mintAcc = null;
}
if (!mintAcc) return error(res, 400, 'invalid_asset', 'token mint not found on this network');
tokenProgramId = mintAcc.owner.equals(TOKEN_2022_PROGRAM_ID) ? TOKEN_2022_PROGRAM_ID : TOKEN_PROGRAM_ID;
let mintInfo;
try {
mintInfo = await getMint(conn, mintPk, 'confirmed', tokenProgramId);
} catch {
return error(res, 400, 'invalid_asset', 'could not read the token mint');
}
decimals = mintInfo.decimals;
sourceAta = getAssociatedTokenAddressSync(mintPk, fromPk, false, tokenProgramId, ASSOCIATED_TOKEN_PROGRAM_ID);
let tokenBalRaw;
try {
const bal = await conn.getTokenAccountBalance(sourceAta);
tokenBalRaw = BigInt(bal.value.amount);
} catch {
return error(res, 400, 'insufficient_balance', 'the agent holds none of this token');
}
if (tokenBalRaw <= 0n) return error(res, 400, 'insufficient_balance', 'the agent holds none of this token');
amountRaw = isMax ? tokenBalRaw : BigInt(Math.round(amountNum * 10 ** decimals));
if (amountRaw <= 0n) return error(res, 400, 'invalid_amount', 'amount rounds to zero token units');
if (amountRaw > tokenBalRaw) return error(res, 400, 'insufficient_balance', 'amount exceeds the agent token balance');
humanAmount = Number(amountRaw) / 10 ** decimals;
// The agent pays the network fee and (if needed) rent to open the
// recipient's token account. Make sure it holds enough SOL.
destAta = getAssociatedTokenAddressSync(mintPk, dest.pubkey, false, tokenProgramId, ASSOCIATED_TOKEN_PROGRAM_ID);
let destInfo;
try {
destInfo = await conn.getAccountInfo(destAta);
} catch {
destInfo = null;
}
destAtaExists = !!destInfo;
let ataRent = 0n;
if (!destAtaExists) {
try {
ataRent = BigInt(await conn.getMinimumBalanceForRentExemption(165));
} catch {
ataRent = TOKEN_ACCOUNT_RENT_FALLBACK_LAMPORTS;
}
}
if (balanceLamports < SOL_FEE_RESERVE_LAMPORTS + ataRent) {
return error(res, 400, 'insufficient_sol_for_fees', 'the agent needs a little SOL to pay the network fee' + (destAtaExists ? '' : ' and open the recipient token account'));
}
// Only USDC is priced 1:1 for the USD ceiling; other SPL tokens are
// governed by the withdraw allowlist (see agent-trade-guards.js header).
if (mintPk.toBase58() === USDC_MINT_BY_CLUSTER[network]) {
usdValue = humanAmount;
} else {
usdValue = null;
priceNote = 'spl_unpriced_allowlist_only';
}
}
// 3. Enforce the shared spend policy (allowlist + per-tx + daily ceiling).
try {
await enforceSpendLimit({ agentId: id, meta, category: 'withdraw', usdValue, destination: dest.base58, network, sweepRiskAck });
} catch (e) {
if (e instanceof SpendLimitError) {
return error(res, e.status, e.code, e.message, { detail: e.detail });
}
console.error('[withdraw] spend-limit check failed', e?.message);
return error(res, 502, 'limit_check_failed', 'could not verify the agent spend limits — try again');
}
// 4. Build the (unsigned) transaction.
let blockhashCtx;
try {
blockhashCtx = await conn.getLatestBlockhash('confirmed');
} catch {
return error(res, 502, 'rpc_error', 'could not fetch a recent blockhash — try again');
}
const ixs = [];
if (asset === 'SOL') {
ixs.push(SystemProgram.transfer({ fromPubkey: fromPk, toPubkey: dest.pubkey, lamports: lamports }));
} else {
if (!destAtaExists) {
ixs.push(createAssociatedTokenAccountIdempotentInstruction(
fromPk, destAta, dest.pubkey, mintPk, tokenProgramId, ASSOCIATED_TOKEN_PROGRAM_ID,
));
}
ixs.push(createTransferCheckedInstruction(
sourceAta, mintPk, destAta, fromPk, amountRaw, decimals, [], tokenProgramId,
));
}
const message = new TransactionMessage({
payerKey: fromPk,
recentBlockhash: blockhashCtx.blockhash,
instructions: ixs,
}).compileToV0Message();
const vtx = new VersionedTransaction(message);
// 5. Simulate-only path — never touches the key, never sends, never records.
if (simulate) {
let sim;
try {
sim = await conn.simulateTransaction(vtx, { sigVerify: false, replaceRecentBlockhash: true });
} catch (e) {
console.error('[agents/solana-wallet] simulation failed', e?.message);
return serverError(res, 502, 'simulation_failed', e);
}
const [allowlist, sweepRisk] = await Promise.all([
allowlistRow({ agentId: id, destination: dest.base58, category: 'withdraw', ownAddress: meta.solana_address }),
checkDestinationSweepRisk({ destination: dest.base58, network }),
]);
return json(res, 200, {
data: {
allowlist, sweepRisk, simulated: true, asset, network, destination: dest.base58,
amount: humanAmount, lamports: lamports != null ? String(lamports) : null,
amount_raw: amountRaw != null ? String(amountRaw) : null,
usd: usdValue, note: priceNote,
err: sim.value?.err ?? null, units_consumed: sim.value?.unitsConsumed ?? null,
logs: sim.value?.logs ?? null,
},
});
}
// 6. Claim the idempotency slot — this row is also the spend-ledger entry.
const claim = await sql`
INSERT INTO agent_custody_events
(agent_id, user_id, event_type, category, network, asset,
amount_lamports, amount_raw, usd, destination, status, idempotency_key, meta)
VALUES (
${id}, ${auth.userId}, 'spend', 'withdraw', ${network}, ${asset},
${lamports != null ? String(lamports) : null},
${amountRaw != null ? String(amountRaw) : null},
${usdValue ?? null}, ${dest.base58}, 'pending', ${idempotencyKey},
${JSON.stringify({ human_amount: humanAmount, note: priceNote })}::jsonb
)
ON CONFLICT (agent_id, idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
RETURNING id
`;
if (!claim.length) {
// Lost the race to a concurrent identical request — defer to it.
return error(res, 409, 'withdrawal_in_progress', 'a withdrawal with this id is already in flight — check the audit log before retrying');
}
const claimId = claim[0].id;
// 7. Recover the key (audit-logged) and sign.
let keypair;
try {
keypair = await recoverSolanaAgentKeypair(encryptedSecret, {
agentId: id, userId: auth.userId, reason: 'withdraw',
meta: { asset, destination: dest.base58, network, custody_event_id: claimId },
});
} catch (e) {
// A definitive decrypt failure is permanent, not transient: this wallet's
// secret was sealed under an encryption key the platform no longer holds, and
// every retry will fail identically. Saying "500" invites the owner to retry
// forever, so it answers 409 with the one thing that is actually true.
const retired = isUnrecoverableSecret(e);
await updateCustodyEvent(claimId, {
status: 'failed',
meta: { error: retired ? 'wallet_key_retired' : 'key_recover_failed' },
}).catch(() => {});
console.error('[withdraw] key recovery failed', { agentId: id, retired, error: e?.message });
if (retired) {
return error(res, 409, 'wallet_key_retired',
'this wallet was created under an earlier encryption key that no longer exists, so it can no longer be signed for. ' +
'No funds were moved and retrying will not help. Contact support with this agent id before creating a new wallet: ' +
'provisioning a replacement abandons the balance at this address.');
}
return error(res, 500, 'key_recover_failed', 'could not access the agent wallet key, no funds were moved');
}
vtx.sign([keypair]);
// 8. Submit + confirm. On an ambiguous confirm (timeout) re-check the chain
// before deciding — never mark failed if the tx may have landed.
let signature;
try {
signature = await conn.sendRawTransaction(vtx.serialize(), { skipPreflight: false, maxRetries: 3 });
} catch (e) {
await updateCustodyEvent(claimId, { status: 'failed', meta: { error: 'send_failed', message: e?.message?.slice(0, 200) } }).catch(() => {});
logAudit({ userId: auth.userId, action: 'custody.withdraw_failed', resourceId: id, meta: { asset, destination: dest.base58, reason: 'send_failed' }, req });
return error(res, 502, 'send_failed', 'the withdrawal could not be submitted and no funds were transferred — try again');
}
let confirmed = true;
try {
const r = await pollConfirmation(
conn,
{ signature, blockhash: blockhashCtx.blockhash, lastValidBlockHeight: blockhashCtx.lastValidBlockHeight },
'confirmed',
);
if (r?.value?.err) confirmed = false;
} catch {
// Confirmation timed out — re-check the signature status directly.
try {
const st = await conn.getSignatureStatus(signature, { searchTransactionHistory: true });
const s = st?.value?.confirmationStatus;
confirmed = !st?.value?.err && (s === 'confirmed' || s === 'finalized');
} catch {
confirmed = false;
}
}
if (!confirmed) {
// Submitted but not provably confirmed. Leave the row 'pending' (NOT
// failed) so a same-key retry returns in_progress instead of double-
// sending; hand the user the signature to verify on-chain.
await updateCustodyEvent(claimId, { signature, meta: { confirm: 'unconfirmed' } }).catch(() => {});
logAudit({ userId: auth.userId, action: 'custody.withdraw_unconfirmed', resourceId: id, meta: { asset, destination: dest.base58, signature }, req });
return error(res, 202, 'withdrawal_unconfirmed', 'the withdrawal was submitted but not yet confirmed — check the explorer link before retrying', { signature, explorer: explorerTxUrl(signature, network) });
}
await updateCustodyEvent(claimId, { status: 'confirmed', signature }).catch(() => {});
logAudit({ userId: auth.userId, action: 'custody.withdraw', resourceId: id, meta: { asset, destination: dest.base58, amount: humanAmount, usd: usdValue, signature, network }, req });
// Invalidate the cached balance so the wallet card reflects the sweep at once.
await cacheSet(`sol:bal:${fromAddress}:${network}`, null, 1).catch(() => {});
// 9. Re-read balances for the response.
let newSol = null;
try {
newSol = (await conn.getBalance(fromPk, 'confirmed')) / 1e9;
} catch { /* best-effort */ }
let newTokenBalance = null;
if (asset !== 'SOL' && sourceAta) {
try {
const b = await conn.getTokenAccountBalance(sourceAta);
newTokenBalance = b?.value?.uiAmount ?? null;
} catch { /* ATA may now be empty/closed */ }
}
return json(res, 200, {
data: {
replayed: false,
signature,
explorer: explorerTxUrl(signature, network),
asset, network, destination: dest.base58,
amount: humanAmount,
lamports: lamports != null ? String(lamports) : null,
amount_raw: amountRaw != null ? String(amountRaw) : null,
usd: usdValue,
note: priceNote,
new_balance_sol: newSol,
new_token_balance: newTokenBalance,
},
});
}
// ── holdings ────────────────────────────────────────────────────────────────
// GET /api/agents/:id/solana/holdings — owner-only list of withdrawable assets
// (SOL + every SPL token the wallet holds with a non-zero balance). Powers the
// Withdraw tab's asset picker so it only ever offers real holdings.
async function handleHoldings(req, res, id) {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET'])) return;
// Token balances are public on-chain data, so the holdings list is readable by
// owner and visitor alike (the wallet hub's Trade tab shows a read-only holdings
// view to visitors). Only the owner ever gets management actions, which live on
// other endpoints. The owner path is unchanged; visitors get an IP-keyed read.
const auth = await resolveAuth(req);
const [row] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
const isOwner = !!(auth && row.user_id === auth.userId);
const address = row.meta?.solana_address || null;
const rl = await limits.walletRead(isOwner ? auth.userId : clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const url = new URL(req.url, 'http://x');
if (!address) {
// `?miss=empty` is for display surfaces that render a wallet-less agent as
// a dormant baseline (the wallet aura, which re-reads on a timer). There an
// unprovisioned wallet is an expected answer, so it gets a 204 instead of a
// 404 the browser prints to the console on every poll.
if (url.searchParams.get('miss') === 'empty') {
res.statusCode = 204;
return res.end();
}
return error(res, 404, 'not_found', 'agent has no solana wallet');
}
const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
const conn = solanaConnection(network);
const owner = new PublicKey(address);
// Last-good tier: the most recent holdings a fully successful read produced.
// During an RPC outage the asset picker shows the real (older) list marked
// stale instead of a 502; only a wallet never read successfully gets the 503.
const lkgKey = `sol:holdings:lkg:${network}:${address}`;
const serveLastGood = async (balanceError) => {
const lkg = await cacheGet(lkgKey);
if (lkg && lkg.data && typeof lkg.at === 'number') {
res.setHeader('cache-control', 'no-store');
return json(res, 200, {
data: staleEnvelope({ ...lkg.data, is_owner: isOwner, balance_error: balanceError }, lkg.at),
});
}
res.setHeader('Retry-After', '15');
return error(res, 503, 'rpc_unavailable', 'could not read the wallet balance right now, retry shortly', { retry_after: 15 });
};
let sol = null;
const balResult = await _solRpcWithBackoffFallback(
conn,
solanaPublicConnection(network),
(c) => c.getBalance(owner, 'confirmed'),
'holdings.getBalance',
);
if (!balResult.ok) return serveLastGood(classifyBalanceError(balResult.error));
sol = balResult.value / 1e9;
const tokens = [];
const usdcMint = USDC_MINT_BY_CLUSTER[network];
let programsRead = 0;
for (const programId of [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID]) {
let resp;
try {
resp = await conn.getParsedTokenAccountsByOwner(owner, { programId });
programsRead += 1;
} catch {
continue; // one token program failing shouldn't blank the whole list
}
for (const { account } of resp.value) {
const info = account.data?.parsed?.info;
const amt = info?.tokenAmount;
if (!info || !amt || !(Number(amt.uiAmount) > 0)) continue;
tokens.push({
mint: info.mint,
ui_amount: amt.uiAmount,
amount_raw: amt.amount,
decimals: amt.decimals,
token_program: programId.toBase58(),
is_usdc: info.mint === usdcMint,
});
}
}
tokens.sort((a, b) => Number(b.ui_amount) - Number(a.ui_amount));
// Only a FULL read (balance + both token programs) is worth remembering: a
// half-read list would later be served as if it were the whole wallet.
if (programsRead === 2) {
cacheSet(lkgKey, { data: { address, network, sol, tokens }, at: Date.now() }, 24 * 3600).catch(() => {});
}
return json(res, 200, { data: { address, network, sol, tokens, is_owner: isOwner, ...(programsRead < 2 ? { partial: true } : {}) } });
}
// ── custody audit trail ───────────────────────────────────────────────────────
// GET /api/agents/:id/solana/custody — owner-only feed of sensitive custody
// events (key recovery, withdraws, spends, limit changes) for this agent wallet.
async function handleCustody(req, res, id) {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET'])) return;
const owned = await loadOwnedWallet(req, res, id);
if (owned.error) return;
const { auth } = owned;
const rl = await limits.auditLogRead(auth.userId);
if (!rl.success) return rateLimited(res, rl);
const url = new URL(req.url, 'http://x');
const limit = Math.min(200, Math.max(1, parseInt(url.searchParams.get('limit') || '50', 10) || 50));
const beforeRaw = url.searchParams.get('before');
const beforeId = beforeRaw && /^\d+$/.test(beforeRaw) ? beforeRaw : null;
const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : url.searchParams.get('network') === 'mainnet' ? 'mainnet' : null;
// Optional category filter (e.g. 'x402') so a caller can read just the spends
// of one kind — the Pay tab reads its own x402 payment activity this way.
const categoryRaw = url.searchParams.get('category');
const category = categoryRaw && /^[a-z0-9_]{1,32}$/i.test(categoryRaw) ? categoryRaw : null;
const events = await listCustodyEvents(id, { limit, beforeId, network, category });
const items = events.map((e) => ({
id: String(e.id),
event_type: e.event_type,
category: e.category,
network: e.network,
asset: e.asset,
amount_lamports: e.amount_lamports != null ? String(e.amount_lamports) : null,
amount_raw: e.amount_raw != null ? String(e.amount_raw) : null,
usd: e.usd != null ? Number(e.usd) : null,
destination: e.destination,
signature: e.signature,
explorer: e.signature ? explorerTxUrl(e.signature, e.network) : null,
reason: e.reason,
status: e.status,
created_at: e.created_at,
// meta carries the x402 service/url + resource for the payment activity
// row; this endpoint is ownership-gated so it's owner-only data already.
meta: e.meta && typeof e.meta === 'object' ? e.meta : null,
}));
const nextCursor = items.length === limit ? items[items.length - 1].id : null;
return json(res, 200, { data: { items, next_cursor: nextCursor } });
}
// ── proof of custody ──────────────────────────────────────────────────────────
// GET /api/agents/:id/solana/proof — owner-only inclusion proof for this wallet's
// custody attestation. Returns the leaf's public fields, the Merkle path to the
// anchored root, the on-chain anchor reference, and a movement reconciliation
// against the custody ledger. The browser verifier (src/proof-of-custody) then
// recomputes the leaf, walks the path, fetches the on-chain root, and confirms it
// matches — never trusting this server's word for the verification.
async function handleCustodyProof(req, res, id) {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET'])) return;
const owned = await loadOwnedWallet(req, res, id);
if (owned.error) return;
const { auth } = owned;
const rl = await limits.auditLogRead(auth.userId);
if (!rl.success) return rateLimited(res, rl);
const { getInclusionProof } = await import('../_lib/custody-proof.js');
const proof = await getInclusionProof(id);
return json(res, 200, { data: proof });
}
// ── spend limits ────────────────────────────────────────────────────────────
// GET/PUT /api/agents/:id/solana/limits — owner-only read + edit of the shared
// per-agent spend policy. Includes today's spend so the hub can show headroom.
async function handleLimits(req, res, id) {
if (cors(req, res, { methods: 'GET,PUT,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'PUT'])) return;
const owned = await loadOwnedWallet(req, res, id);
if (owned.error) return;
const { auth, meta } = owned;
const rl = await limits.walletRead(auth.userId);
if (!rl.success) return rateLimited(res, rl);
const url = new URL(req.url, 'http://x');
const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
if (req.method === 'PUT') {
// Spend ceilings, the freeze switch, and the withdraw allowlist are the
// wallet's safety gates — a forged change could disarm them, so require CSRF.
if (!(await requireCsrf(req, res, auth.userId))) return;
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
// Validate allowlist entries up-front so the user gets a clear rejection
// instead of silent dropping inside normalizeSpendLimits.
if (Array.isArray(body.withdraw_allowlist)) {
const bad = body.withdraw_allowlist.find((a) => !validateSolanaAddress(a).valid);
if (bad !== undefined) return error(res, 400, 'invalid_address', `withdraw_allowlist contains an invalid Solana address: ${String(bad).slice(0, 60)}`);
}
// The USD spend policy and the lamports-denominated trade policy share this
// owner surface. A PUT may patch either or both: a `trade_limits` object
// updates the discretionary-trade caps (per-trade SOL, daily budget, breaker,
// kill switch); the top-level USD/allowlist keys update the spend policy.
const wantsSpend = ['daily_usd', 'per_tx_usd', 'per_counterparty_daily_usd', 'approval_threshold_usd', 'frozen'].some((k) => k in body);
let limitsOut = getSpendLimits(meta);
let tradeLimitsOut = getTradeLimits(meta);
let burnerOut = getBurnerPolicy(meta);
let whitelistOut = null;
try {
// The legacy whole-list write follows the destination whitelist rules: new
// addresses serve the cooldown and need a step-up grant, removals are instant.
if (Array.isArray(body.withdraw_allowlist)) {
whitelistOut = await replaceSolanaList({
agentId: id,
actor: { kind: auth.sessionId ? 'owner' : 'api_key', userId: auth.userId, sessionId: auth.sessionId || null },
list: body.withdraw_allowlist,
grantId: typeof body.grant === 'string' ? body.grant : null,
req,
});
}
if (wantsSpend) limitsOut = await setSpendLimits(id, auth.userId, body, { req });
if (body.trade_limits && typeof body.trade_limits === 'object') {
tradeLimitsOut = await setTradeLimits(id, auth.userId, body.trade_limits, { req });
}
if (body.burner_policy && typeof body.burner_policy === 'object') {
burnerOut = await setBurnerPolicy(id, auth.userId, body.burner_policy, { req });
}
} catch (e) {
if (e?.status) return error(res, e.status, e.code || 'error', e.message, e.extra);
throw e;
}
limitsOut = { ...limitsOut, withdraw_allowlist: await activeAddresses(id) };
const spentUsd = await getDailySpendUsd(id, network).catch(() => 0);
const spentLamports = await getDailySpendLamports(id, network).catch(() => 0n);
const autoSpentUsd = await getAutoSpendUsd(id, network).catch(() => 0);
return json(res, 200, { data: { whitelist: whitelistOut, limits: limitsOut, trade_limits: tradeLimitsOut, burner_policy: burnerOut, spend_policy: resolveSpendPolicy(meta), spent_today_usd: spentUsd, auto_spent_today_usd: autoSpentUsd, spent_today_sol: Number(spentLamports) / 1e9 } });
}
const limitsOut = { ...getSpendLimits(meta), withdraw_allowlist: await activeAddresses(id) };
const whitelistView = await getWhitelist(id, auth.userId).catch(() => null);
const spentUsd = await getDailySpendUsd(id, network).catch(() => 0);
const spentLamports = await getDailySpendLamports(id, network).catch(() => 0n);
const autoSpentUsd = await getAutoSpendUsd(id, network).catch(() => 0);
return json(res, 200, { data: { whitelist: whitelistView, limits: limitsOut, trade_limits: getTradeLimits(meta), burner_policy: getBurnerPolicy(meta), spend_policy: resolveSpendPolicy(meta), spent_today_usd: spentUsd, auto_spent_today_usd: autoSpentUsd, spent_today_sol: Number(spentLamports) / 1e9 } });
}
// ── natural-language spend policy ─────────────────────────────────────────────
// Owner-only. The owner writes safety rules in plain English; a real Claude call
// COMPILES them to a deterministic rule document (api/_lib/spend-policy-rules.js)
// that the shared guards enforce on every spend. The LLM only authors + explains —
// it never decides a spend. All endpoints are ownership-gated via loadOwnedWallet.
//
// GET /policy current compiled policy + numbered plain-English readback
// POST /policy {op:compile, text} compile English → rules + readback + live backtest
// POST /policy {op:backtest, rules} replay a rule set against real custody history
// PUT /policy {rules, english} save a validated policy (CSRF-gated, audited)
async function handlePolicy(req, res, id) {
if (cors(req, res, { methods: 'GET,POST,PUT,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'POST', 'PUT'])) return;
const owned = await loadOwnedWallet(req, res, id);
if (owned.error) return;
const { auth, meta } = owned;
const rl = await limits.walletRead(auth.userId);
if (!rl.success) return rateLimited(res, rl);
const url = new URL(req.url, 'http://x');
const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
const spendLimits = getSpendLimits(meta);
const allowlist = Array.isArray(spendLimits.withdraw_allowlist) ? spendLimits.withdraw_allowlist : [];
// Real spend history for the backtest — the last 60 days of spend rows, capped.
// The same deterministic evaluator that runs in production scores these, so the
// preview is honest, not an approximation.
async function loadHistory() {
return sql`
SELECT id, event_type, category, network, asset, usd, destination, created_at, meta
FROM agent_custody_events
WHERE agent_id = ${id} AND network = ${network} AND event_type = 'spend'
AND status IN ('ok', 'pending', 'confirmed')
AND created_at > now() - interval '60 days'
ORDER BY created_at DESC
LIMIT 1000
`;
}
if (req.method === 'GET') {
const policy = getPolicyRules(meta);
return json(res, 200, {
data: { policy, readback: describePolicyRules(policy), source_text: policy.source_text, numeric_limits: spendLimits },
});
}
if (req.method === 'POST') {
// compile + backtest are read-only previews (no mutation) — owner-gated above.
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
const op = body?.op === 'backtest' ? 'backtest' : 'compile';
if (op === 'compile') {
const text = typeof body?.text === 'string' ? body.text : '';
const result = await compilePolicyFromText(text, { allowlist, track: { userId: auth.userId, agentId: id } });
if (!result.ok) {
return json(res, 200, { data: { ok: false, error: result.error, refusal: result.refusal || null, message: result.message, via: result.via || null } });
}
let backtest = null;
try {
backtest = backtestPolicy(result.policy, await loadHistory(), { allowlist });
} catch (e) {
console.warn('[policy] backtest failed', e?.message);
}
return json(res, 200, {
data: {
ok: true, via: result.via, policy: result.policy, readback: result.readback,
assumptions: result.assumptions, source_text: result.source_text,
backtest, synthetic: syntheticProbes(result.policy),
},
});
}
// backtest a supplied (or current) rule set against real history.
const policy = normalizePolicyRules({ rules: body?.rules, source_text: body?.english });
let backtest = null;
try {
backtest = backtestPolicy(policy, await loadHistory(), { allowlist });
} catch (e) {
console.warn('[policy] backtest failed', e?.message);
}
return json(res, 200, { data: { ok: true, policy, readback: describePolicyRules(policy), backtest, synthetic: syntheticProbes(policy) } });
}
// PUT — save a validated policy. Changing the wallet's safety rules requires CSRF.
if (!(await requireCsrf(req, res, auth.userId))) return;
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
const rules = Array.isArray(body?.rules) ? body.rules : Array.isArray(body?.policy?.rules) ? body.policy.rules : [];
if (rules.length > MAX_RULES) {
return error(res, 422, 'too_many_rules', `A policy can have at most ${MAX_RULES} rules. Simplify it and try again.`);
}
const english = typeof body?.english === 'string' ? body.english : typeof body?.source_text === 'string' ? body.source_text : null;
let saved;
try {
saved = await setPolicyRules(id, auth.userId, rules, { english, req });
} catch (e) {
if (e?.status) return error(res, e.status, e.code || 'error', e.message);
throw e;
}
// The caller sent rules but none survived validation — refuse loudly rather than
// silently saving an empty (unprotective) policy.
if (!saved.rules.length && rules.length) {
return error(res, 422, 'invalid_policy', 'None of those rules could be validated as enforceable, so nothing was saved.');
}
let backtest = null;
try {
backtest = backtestPolicy(saved, await loadHistory(), { allowlist });
} catch (e) {
console.warn('[policy] post-save backtest failed', e?.message);
}
return json(res, 200, { data: { policy: saved, readback: describePolicyRules(saved), backtest } });
}
// ── signed spend delegation ────────────────────────────────────────────────────
// Owner-only. The owner's cap here is a SIGNATURE, not a session write: the
// browser prompts the owner's own wallet (Wallet Standard `solana:signMessage`,
// never a transaction) for the exact bytes `delegationMessage` builds, and this
// endpoint stores the result after re-verifying it (api/_lib/agent-spend-delegation.js).
// The owner session gate below is a convenience for this surface, not the real
// security boundary: that is the Ed25519 check, so the exact same delegation
// can also be registered through the anonymous POST /api/agent/guard.
//
// GET /delegation the active delegation on file (or null)
// POST /delegation { delegation, delegationSignature } verify + store a newly signed one
const DELEGATION_ERROR_STATUS = {
invalid_delegation: 400,
expired_delegation: 400,
agent_not_found: 404,
wrong_signer: 403,
replayed_nonce: 409,
};
async function handleDelegation(req, res, id) {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'POST'])) return;
const owned = await loadOwnedWallet(req, res, id);
if (owned.error) return;
const { auth } = owned;
const rl = await limits.walletRead(auth.userId);
if (!rl.success) return rateLimited(res, rl);
if (req.method === 'GET') {
const active = await getActiveDelegation(id);
return json(res, 200, { data: { delegation: active } });
}
// POST: the owner already signed in their wallet; this just verifies + stores.
if (!(await requireCsrf(req, res, auth.userId))) return;
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
try {
const row = await registerDelegation({ agentId: id, delegation: body?.delegation, signature: body?.delegationSignature });
return json(res, 200, { data: { delegation: row } });
} catch (e) {
if (e instanceof DelegationError) {
return error(res, DELEGATION_ERROR_STATUS[e.code] || 400, e.code, e.message);
}
throw e;
}
}
// ── vanity grind + custodial swap ──────────────────────────────────────────────
// GET /api/agents/:id/solana/vanity — owner-only current vanity status.
// POST /api/agents/:id/solana/vanity — owner-only: grind a vanity keypair
// server-side (the secret never leaves the server) and make it the agent's
// custodial Solana wallet. If the existing wallet holds funds, every asset is
// swept to the new address FIRST, signed by the old key; the stored key is only
// swapped after the sweep confirms, so funds can never be stranded. This is an
// internal custody migration between two wallets the same owner controls — not a
// third-party withdrawal — so it is exempt from the withdraw allowlist but fully
// audited as a `vanity_swap` custody event.
// Server-side grind is bounded so a serverless invocation can't hang. Patterns
// harder than this are ground in the browser (a WASM worker pool across the
// user's CPU cores, up to 8 chars) and assigned with the resulting secret_key.
const VANITY_MAX_CHARS = 3; // combined prefix+suffix length for server grind
const VANITY_MAX_ITERATIONS = 4_000_000;
// Wall-clock grind budget. Kept under the function's 45s maxDuration (vercel.json)
// with ~15s of headroom for the post-grind wallet sweep and response.
const VANITY_GRIND_BUDGET_MS = 30_000;
// Move every asset (all SPL tokens + remaining SOL) from a custodial keypair to a
// destination address, reclaiming token-account rent. Two-phase so the final SOL
// figure is exact: (A) transfer + close each token account, (B) sweep all SOL.
// Returns { signatures, sol, tokens }. Throws if any leg fails to confirm — the
// caller must NOT discard the source key unless this resolves.
async function sweepWalletToAddress({ conn, fromKeypair, toPubkey, network }) {
const fromPk = fromKeypair.publicKey;
const signatures = [];
const movedTokens = [];
// Phase A — collect every non-empty token account across both token programs.
const tokenLegs = [];
for (const programId of [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID]) {
let resp;
try {
resp = await conn.getParsedTokenAccountsByOwner(fromPk, { programId });
} catch {
continue;
}
for (const { account } of resp.value) {
const info = account.data?.parsed?.info;
const amt = info?.tokenAmount;
if (!info || !amt) continue;
const raw = BigInt(amt.amount || '0');
if (raw <= 0n) continue;
const mintPk = new PublicKey(info.mint);
const sourceAta = getAssociatedTokenAddressSync(mintPk, fromPk, false, programId, ASSOCIATED_TOKEN_PROGRAM_ID);
const destAta = getAssociatedTokenAddressSync(mintPk, toPubkey, false, programId, ASSOCIATED_TOKEN_PROGRAM_ID);
tokenLegs.push({ mintPk, programId, sourceAta, destAta, raw, decimals: amt.decimals });
movedTokens.push({ mint: info.mint, ui_amount: amt.uiAmount, amount_raw: amt.amount });
}
}
// Send token transfers + closes in chunks so each transaction stays under the
// size limit. Closing the source ATA returns its rent lamports to `fromPk`,
// which are then swept out in phase B.
const CHUNK = 4;
for (let i = 0; i < tokenLegs.length; i += CHUNK) {
const chunk = tokenLegs.slice(i, i + CHUNK);
const ixs = [];
for (const leg of chunk) {
ixs.push(createAssociatedTokenAccountIdempotentInstruction(
fromPk, leg.destAta, toPubkey, leg.mintPk, leg.programId, ASSOCIATED_TOKEN_PROGRAM_ID,
));
ixs.push(createTransferCheckedInstruction(
leg.sourceAta, leg.mintPk, leg.destAta, fromPk, leg.raw, leg.decimals, [], leg.programId,
));
ixs.push(createCloseAccountInstruction(leg.sourceAta, fromPk, fromPk, [], leg.programId));
}
const sig = await sendV0({ conn, payer: fromKeypair, ixs });
signatures.push(sig);
}
// Phase B — sweep all remaining SOL, leaving only the network fee. The old
// account is intentionally abandoned (drained to ~0), so no rent is reserved.
let lamports = 0n;
try {
lamports = BigInt(await conn.getBalance(fromPk, 'confirmed'));
} catch {
lamports = 0n;
}
const spendable = lamports - SOL_FEE_RESERVE_LAMPORTS;
let solMoved = 0;
if (spendable > 0n) {
const sig = await sendV0({
conn,
payer: fromKeypair,
ixs: [SystemProgram.transfer({ fromPubkey: fromPk, toPubkey, lamports: spendable })],
});
signatures.push(sig);
solMoved = Number(spendable) / 1e9;
}
return { signatures, sol: solMoved, tokens: movedTokens };
}
// Build, sign, send and confirm a single v0 transaction. Throws on any failure or
// an unconfirmed/erroring result so callers treat the leg as not-yet-final.
async function sendV0({ conn, payer, ixs }) {
let bh;
try {
bh = await conn.getLatestBlockhash('confirmed');
} catch (err) {
// Same typed 502 the unsigned-withdraw builder answers, so the caller sees
// "RPC blip, retry" rather than a sanitized 500 with no code to act on.
const e = new Error('could not fetch a recent blockhash, try again');
e.status = 502; e.code = 'rpc_error'; e.cause = err;
throw e;
}
const msg = new TransactionMessage({
payerKey: payer.publicKey,
recentBlockhash: bh.blockhash,
instructions: ixs,
}).compileToV0Message();
const vtx = new VersionedTransaction(msg);
vtx.sign([payer]);
const sig = await conn.sendRawTransaction(vtx.serialize(), { skipPreflight: false, maxRetries: 3 });
// HTTP-polling confirm (no WebSocket) — throws on a landed-but-reverted tx.
await confirmOrThrow(conn, { signature: sig, blockhash: bh.blockhash, lastValidBlockHeight: bh.lastValidBlockHeight }, 'confirmed');
return sig;
}
function validateVanityPattern(raw, label) {
if (raw == null || raw === '') return null;
const s = String(raw);
if (s.length > 6) return { error: `${label} is too long (max 6 base58 chars)` };
for (const c of s) {
if (!BASE58_ALPHABET.includes(c)) return { error: `${label} has a non-base58 char '${c}' (0/O/I/l are not allowed)` };
}
return { value: s };
}
async function handleVanity(req, res, id) {
if (cors(req, res, { methods: 'GET,POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'POST'])) return;
const owned = await loadOwnedWallet(req, res, id);
if (owned.error) return;
const { auth, meta, address: currentAddress, encryptedSecret } = owned;
if (req.method === 'GET') {
const rl = await limits.walletRead(auth.userId);
if (!rl.success) return rateLimited(res, rl);
return json(res, 200, {
data: {
address: currentAddress,
vanity_prefix: meta.solana_vanity_prefix || null,
vanity_suffix: meta.solana_vanity_suffix || null,
source: meta.solana_wallet_source || (encryptedSecret ? 'generated' : null),
is_vanity: !!(meta.solana_vanity_prefix || meta.solana_vanity_suffix),
max_chars: VANITY_MAX_CHARS,
},
});
}
// POST — sensitive: it grinds a new keypair and sweeps every holding to it,
// so it moves funds. Require a signed real-funds agreement and CSRF, then
// gate behind the withdrawal per-user cap + per-IP burst.
if (!(await requireRealFundsAgreement(req, res, { userId: auth.userId, context: 'vanity' }))) return;
if (!(await requireCsrf(req, res, auth.userId))) return;
const rlUser = await limits.withdrawalPerUser(auth.userId);
if (!rlUser.success) return rateLimited(res, rlUser);
const rlIp = await limits.authIp(clientIp(req));
if (!rlIp.success) return rateLimited(res, rlIp);
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
const network = body.network === 'devnet' ? 'devnet' : 'mainnet';
const ignoreCase = body.ignoreCase === true || body.ignore_case === true;
const pfx = validateVanityPattern(body.prefix, 'prefix');
const sfx = validateVanityPattern(body.suffix, 'suffix');
if (pfx?.error) return error(res, 400, 'validation_error', pfx.error);
if (sfx?.error) return error(res, 400, 'validation_error', sfx.error);
const prefix = pfx?.value || null;
const suffix = sfx?.value || null;
if (!prefix && !suffix) return error(res, 400, 'validation_error', 'provide a prefix and/or suffix');
const combinedLen = (prefix?.length || 0) + (suffix?.length || 0);
// Two ways to supply the new keypair, both ending in the identical sweep-then-
// swap below so funds are equally safe either way:
// (A) `secret_key` — a 64-byte Ed25519 key the owner ground in their browser
// at full speed (worker pool, longer patterns, case-insensitive). We
// re-derive the address and prove it matches the requested pattern before
// adopting it — the client's "this is vanity" claim is never trusted.
// (B) no key — a bounded server-side grind for short patterns only.
let ground = null;
let newKp;
if (body.secret_key != null) {
const sk = body.secret_key;
if (!Array.isArray(sk) || sk.length !== 64 || !sk.every((n) => Number.isInteger(n) && n >= 0 && n <= 255)) {
return error(res, 400, 'validation_error', 'secret_key must be a 64-byte number array');
}
try {
newKp = Keypair.fromSecretKey(Uint8Array.from(sk));
} catch {
return error(res, 400, 'validation_error', 'secret_key did not parse as a valid Solana keypair');
}
// Verify the supplied address genuinely satisfies the pattern — the
// client's "this is vanity" claim is never trusted.
const claimed = newKp.publicKey.toBase58();
if (!addressMatchesPattern(claimed, { prefix, suffix, ignoreCase })) {
return error(res, 400, 'validation_error', 'the supplied address does not match the requested prefix/suffix');
}
} else {
if (combinedLen > VANITY_MAX_CHARS) {
return error(res, 400, 'pattern_too_hard',
`server-side grinding supports up to ${VANITY_MAX_CHARS} combined characters. ` +
`Grind longer patterns in your browser (this tab grinds with your CPU cores) — they assign automatically.`);
}
// Grind the vanity keypair. The secret stays in process memory only.
try {
const est = estimateAttempts({ prefix, suffix, ignoreCase });
const maxIterations = Math.min(VANITY_MAX_ITERATIONS, Math.max(200_000, Math.ceil(est * 25)));
// Bail before the function's maxDuration (45s, see vercel.json) so the grind
// returns a clean `vanity_timeout` 504 instead of a hard runtime kill, and
// still leaves headroom to sweep the wallet to the new address afterward.
ground = await grindMintKeypair({ prefix, suffix, ignoreCase, maxIterations, maxMs: VANITY_GRIND_BUDGET_MS });
} catch (e) {
if (e?.code === 'vanity_timeout') {
return error(res, 504, 'vanity_timeout', 'could not find a matching address in time — try a shorter pattern or grind it in the browser');
}
if (e?.code === 'invalid_vanity') return error(res, 400, 'validation_error', e.message);
console.error('[agents/solana/vanity] grind failed', e?.message);
return error(res, 502, 'grind_failed', 'vanity grind failed — try again');
}
newKp = ground.keypair;
}
const newAddress = newKp.publicKey.toBase58();
// If the agent already holds a funded custodial wallet, migrate the balance to
// the new address before swapping the stored key. This is the money-safe gate:
// a failed sweep throws and we keep the old wallet intact.
let swept = null;
if (currentAddress && encryptedSecret && currentAddress !== newAddress) {
const conn = solanaConnection(network);
let needsSweep = false;
try {
const lamports = BigInt(await conn.getBalance(new PublicKey(currentAddress), 'confirmed'));
needsSweep = lamports > SOL_FEE_RESERVE_LAMPORTS;
if (!needsSweep) {
// Any non-empty token account also requires a sweep.
for (const programId of [TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID]) {
const resp = await conn.getParsedTokenAccountsByOwner(new PublicKey(currentAddress), { programId }).catch(() => ({ value: [] }));
if (resp.value.some((t) => Number(t.account.data?.parsed?.info?.tokenAmount?.uiAmount) > 0)) {
needsSweep = true;
break;
}
}
}
} catch (e) {
return error(res, 502, 'rpc_error', 'could not read the current wallet balance — try again before migrating funds');
}
if (needsSweep) {
let oldKp;
try {
oldKp = await recoverSolanaAgentKeypair(encryptedSecret, {
agentId: id, userId: auth.userId, reason: 'vanity_swap',
meta: { from: currentAddress, to: newAddress, network },
});
} catch (e) {
console.error('[agents/solana/vanity] key recovery failed', e?.message);
return error(res, 500, 'key_recover_failed', 'could not access the current wallet key — no funds were moved and the wallet is unchanged');
}
try {
swept = await sweepWalletToAddress({ conn, fromKeypair: oldKp, toPubkey: newKp.publicKey, network });
} catch (e) {
console.error('[agents/solana/vanity] sweep failed', e?.message);
return error(res, 502, 'sweep_failed',
'funds could not be fully migrated to the new address — your existing wallet is unchanged and still holds the funds. Try again.');
}
await recordCustodyEvent({
agentId: id, userId: auth.userId, eventType: 'spend', category: 'vanity_swap',
network, asset: 'ALL', status: 'confirmed',
signature: swept.signatures[swept.signatures.length - 1] || null,
destination: newAddress,
meta: { from: currentAddress, to: newAddress, sol: swept.sol, tokens: swept.tokens, signatures: swept.signatures },
}).catch(() => {});
}
}
// Persist the new keypair as the agent's custodial wallet.
const walletSource = ground ? 'vanity_grind' : 'imported_vanity';
const encrypted_secret = await _encryptSecret(Buffer.from(newKp.secretKey).toString('base64'));
const history = Array.isArray(meta.solana_wallet_history) ? meta.solana_wallet_history : [];
const nextMeta = {
...meta,
solana_address: newAddress,
encrypted_solana_secret: encrypted_secret,
solana_wallet_source: walletSource,
solana_vanity_prefix: prefix || null,
solana_vanity_suffix: suffix || null,
};
if (!prefix) delete nextMeta.solana_vanity_prefix;
if (!suffix) delete nextMeta.solana_vanity_suffix;
if (currentAddress && currentAddress !== newAddress) {
nextMeta.solana_wallet_history = [
...history,
{ address: currentAddress, replaced_at: new Date().toISOString(), reason: 'vanity_upgrade', swept: !!swept },
].slice(-10);
}
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(nextMeta)}::jsonb WHERE id = ${id}`;
if (currentAddress) await cacheSet(`sol:bal:${currentAddress}:${network}`, null, 1).catch(() => {});
await cacheSet(`sol:bal:${newAddress}:${network}`, null, 1).catch(() => {});
const iterations = ground ? ground.iterations : (Number.isFinite(Number(body.iterations)) ? Number(body.iterations) : null);
const durationMs = ground ? ground.durationMs : (Number.isFinite(Number(body.duration_ms)) ? Number(body.duration_ms) : null);
recordEvent({
userId: auth.userId, agentId: id, kind: 'solana_vanity_grind', tool: ground ? 'server' : 'browser', status: 'ok',
meta: { address: newAddress, prefix, suffix, ignoreCase, iterations, swept: swept ? { sol: swept.sol, tokens: swept.tokens.length } : null },
});
logAudit({ userId: auth.userId, action: 'custody.vanity_grind', resourceId: id, meta: { address: newAddress, prefix, suffix, replaced: currentAddress || null, swept: !!swept }, req });
return json(res, 201, {
data: {
address: newAddress,
vanity_prefix: prefix,
vanity_suffix: suffix,
network,
iterations,
duration_ms: durationMs,
replaced: currentAddress && currentAddress !== newAddress ? currentAddress : null,
swept,
source: walletSource,
},
});
}
// ── net-worth (the agent wears its wallet) ──────────────────────────────────────
// Count agents forked from this one (real lineage rows). Lineage is stored at
// fork time in agent_identities.meta.forked_from.agent_id (api/avatars/fork.js).
async function forkCountFor(id) {
try {
const [r] = await sql`
SELECT count(*)::int AS n FROM agent_identities
WHERE deleted_at IS NULL AND meta->'forked_from'->>'agent_id' = ${id}
`;
return r?.n || 0;
} catch {
return 0;
}
}
// Lifetime tips received by this agent — confirmed on-chain tip rows only, so the
// count can never be fabricated. Powers the "Tipped Nx / $X" reputation mark.
async function lifetimeTipsFor(id) {
try {
const [r] = await sql`
SELECT count(*)::int AS n, COALESCE(sum(usd), 0)::float8 AS usd
FROM agent_custody_events
WHERE agent_id = ${id} AND event_type = 'tip' AND status IN ('ok', 'confirmed')
`;
return { count: r?.n || 0, usd: Number(r?.usd) || 0 };
} catch {
return { count: 0, usd: 0 };
}
}
// Realized trading P&L from CLOSED sniper positions (a real on-chain settlement).
// Net SOL and the count of profitable closes; defensive when the table is absent.
async function realizedPnlFor(id) {
try {
const [r] = await sql`
SELECT
COALESCE(sum(realized_pnl_lamports), 0)::float8 AS lamports,
count(*) FILTER (WHERE realized_pnl_lamports > 0)::int AS wins
FROM agent_sniper_positions
WHERE agent_id = ${id} AND status = 'closed' AND realized_pnl_lamports IS NOT NULL
`;
return { sol: (Number(r?.lamports) || 0) / 1e9, wins: r?.wins || 0 };
} catch {
// Table may not exist on this deployment — P&L mark simply doesn't appear.
return { sol: 0, wins: 0 };
}
}
// Embodied-finance "flow" signals — the live DYNAMICS that ride on top of the
// static net-worth tier so an agent that is *currently* earning reads warmer and a
// bleeding one reads cooler, honestly. Every value traces to a real custody row:
//
// - momentum_usd_24h : realized net flow over the trailing 24h. Inflows are
// confirmed tips (and, once Money Streams lands, stream credits); outflows are
// spends (trades/snipes/x402/withdraw) and owner withdraws. A positive number
// means the wallet took in more than it paid out today.
// - streaming_now : count of OPEN, still-running money streams crediting this
// agent right now. There is no stream event type until task 01 ships, so this
// query is written generically (category/event_type='stream', meta.end_at in
// the future) and returns 0 today — never a fabricated "earning" glow.
// - last_tip_at : ISO time of the most recent confirmed tip, for the
// recency pulse. null when never tipped.
//
// All windowed by `created_at`; defensive so a missing column/table degrades to a
// neutral (flat) signal rather than throwing.
async function flowSignalsFor(id) {
const flat = { momentumUsd24h: 0, inflowUsd24h: 0, outflowUsd24h: 0, streamingNow: 0, lastTipAt: null };
try {
const [flow] = await sql`
SELECT
COALESCE(sum(usd) FILTER (
WHERE event_type IN ('tip', 'stream') AND created_at > now() - interval '24 hours'
), 0)::float8 AS inflow,
COALESCE(sum(usd) FILTER (
WHERE event_type IN ('spend', 'withdraw') AND created_at > now() - interval '24 hours'
), 0)::float8 AS outflow,
max(created_at) FILTER (WHERE event_type = 'tip') AS last_tip_at
FROM agent_custody_events
WHERE agent_id = ${id} AND status IN ('ok', 'confirmed', 'pending')
`;
const inflow = Number(flow?.inflow) || 0;
const outflow = Number(flow?.outflow) || 0;
let streamingNow = 0;
try {
// Streams crediting this agent RIGHT NOW. A Money Streams session (task 01)
// settles on-chain every ~45s (SETTLE_INTERVAL_MS), each settlement a
// 'stream' custody row tagged with its stream_id — so a stream is "live"
// iff it settled within the last cadence-and-a-bit. Count the distinct
// still-settling sessions; a stream that stopped naturally drops to 0.
const [s] = await sql`
SELECT count(DISTINCT meta->>'stream_id')::int AS n FROM agent_custody_events
WHERE agent_id = ${id}
AND category = 'stream'
AND status IN ('ok', 'confirmed', 'pending')
AND created_at > now() - interval '100 seconds'
`;
streamingNow = s?.n || 0;
} catch { streamingNow = 0; }
return {
momentumUsd24h: inflow - outflow,
inflowUsd24h: inflow,
outflowUsd24h: outflow,
streamingNow,
lastTipAt: flow?.last_tip_at ? new Date(flow.last_tip_at).toISOString() : null,
};
} catch {
return flat;
}
}
// Map a real signed 24h net flow (USD) onto a bounded momentum scalar in [-1, 1]
// for the embodiment. Log-scaled so a $5 day and a $5,000 day both read as
// "earning" without the larger one eye-searing — symmetric for inflow/outflow.
// 0 → 0, ±$10 → ±0.5, ±$1,000 → ±1.0. Pure + documented; never random.
function momentumScalar(usd) {
const v = Number(usd) || 0;
if (v === 0) return 0;
const mag = Math.min(1, Math.log10(1 + Math.abs(v)) / 3);
return v > 0 ? mag : -mag;
}
// One real read of every reputation signal the look + regalia use.
async function reputationFor(id) {
const [forkCount, tips, pnl] = await Promise.all([
forkCountFor(id),
lifetimeTipsFor(id),
realizedPnlFor(id),
]);
return { forkCount, tips, pnl };
}
// Throttle the networth chain-read warning. The networth endpoint is polled
// (avatar presence "look" refresh), so one agent whose wallet read keeps failing
// — a stale/exhausted RPC, a wallet the upstream 404s — would otherwise emit one
// identical warning per poll (18+ for a single agent in one log window). Collapse
// repeats per agent to one line per minute; a persistent failure stays visible
// without flooding. The 502 hold-last-state response to the client is unchanged.
const _networthWarnedAt = new Map();
const NETWORTH_WARN_COOLDOWN_MS = 60_000;
function warnNetworthThrottled(agentId, msg) {
const now = Date.now();
if (now - (_networthWarnedAt.get(agentId) || 0) < NETWORTH_WARN_COOLDOWN_MS) return;
if (_networthWarnedAt.size > 1000) _networthWarnedAt.clear(); // bound key cardinality
_networthWarnedAt.set(agentId, now);
console.warn(msg);
}
// GET /api/agents/:id/solana/networth — public read: the agent's net-worth "look"
// (presence tier, aura, confidence, regalia marks) derived entirely from real
// chain reads + real DB counts, plus the owner's reactivity preferences.
// PUT /api/agents/:id/solana/networth — owner-only: persist the reactivity prefs
// (CSRF-gated). Visitors render the agent exactly as the owner configured it.
const NETWORTH_BALANCE_DEADLINE_MS = 6_000;
async function handleNetWorth(req, res, id) {
if (cors(req, res, { methods: 'GET,PUT,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'PUT'])) return;
const [row] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
const auth = await resolveAuth(req);
const isOwner = !!(auth && row.user_id === auth.userId);
const address = row.meta?.solana_address || null;
const hubUrl = `/agent/${id}/wallet`;
if (req.method === 'PUT') {
// Only the owner shapes how their agent presents itself; a forged change
// could force a flex the owner opted out of, so require CSRF.
if (!isOwner) return error(res, auth ? 403 : 401, auth ? 'forbidden' : 'unauthorized', auth ? 'not your agent' : 'sign in required');
if (!(await requireCsrf(req, res, auth.userId))) return;
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
const prev = normalizePrefs(row.meta?.networth_look);
const next = normalizePrefs({
reactivity: 'reactivity' in body ? body.reactivity : prev.reactivity,
signals: { ...prev.signals, ...(body.signals && typeof body.signals === 'object' ? body.signals : {}) },
nameplate: { ...prev.nameplate, ...(body.nameplate && typeof body.nameplate === 'object' ? body.nameplate : {}) },
});
next.updated_at = new Date().toISOString();
const meta = { ...(row.meta || {}), networth_look: next };
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(meta)}::jsonb WHERE id = ${id}`;
logAudit({ userId: auth.userId, action: 'networth.prefs_update', resourceId: id, meta: { prev, next }, req });
return json(res, 200, { data: { prefs: next, is_owner: true } });
}
const rl = await limits.walletRead(isOwner ? auth.userId : clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const prefs = normalizePrefs(row.meta?.networth_look);
const [{ forkCount, tips, pnl }, flowRaw] = await Promise.all([reputationFor(id), flowSignalsFor(id)]);
const repState = {
forkCount,
tipCount: tips.count, tipUsd: tips.usd,
realizedPnlSol: pnl.sol, realizedWins: pnl.wins,
};
const reputation = {
fork_count: forkCount,
tips: { count: tips.count, usd: tips.usd },
realized_pnl_sol: pnl.sol, realized_wins: pnl.wins,
};
// No wallet yet (provisioning): calm baseline look, honest about state. The
// agent still reads as itself — never poor-shamed, never faked. Reputation it
// has already earned (forks, tips) still shows.
if (!address) {
const look = computeLook({ usd: 0, ...repState });
return json(res, 200, {
data: {
agent_id: id, address: null, network: 'mainnet', provisioning: true,
portfolio: { usd: 0, sol: 0, three: null, usdc: 0, token_count: 0, top: [] },
reputation,
flow: buildFlowPayload({ balanceSol: 0, balanceUsd: 0, tier: look.tier.key, flowRaw }),
tier: look.tier, look, marks: computeMarks({ usd: 0, ...repState }, { hubUrl }),
prefs, is_owner: isOwner, hub_url: hubUrl,
},
});
}
let balances = null;
try {
// Hard deadline: getBalances walks the RPC chain lane by lane, and a lane
// that stalls (instead of failing) would hold this request past the gateway
// timeout. Failing fast here lands in the same typed 503 path below.
balances = await withDeadline(getBalances({ chain: 'solana', address }), NETWORTH_BALANCE_DEADLINE_MS, 'networth balances');
} catch (e) {
// Hold-last-state contract: getBalances already serves a stale last-known-good
// snapshot when the live read fails, so reaching here means we have never read
// this wallet successfully AND every RPC path is down right now — genuinely
// transient and rare. Return 503 + Retry-After (not 502): the correct
// "temporarily unavailable, come back" signal, and the typed error still lets
// the client keep its last real look rather than snapping to a fake baseline.
warnNetworthThrottled(id, `[agents/networth] balance read failed agentId=${id} ${e?.message}`);
res.setHeader('Retry-After', '15');
return error(res, 503, 'rpc_unavailable', 'could not read the wallet right now — holding last state');
}
const usd = walletUsdTotal(balances);
const sol = balances?.native?.amount || 0;
const tokens = balances?.tokens || [];
const threeTok = tokens.find((t) => t.mint === THREE_MINT) || null;
const usdcTok = tokens.find((t) => t.symbol === 'USDC');
const top = tokens.slice(0, 5).map((t) => ({ symbol: t.symbol, mint: t.mint, usd: t.usd || 0, amount: t.amount || 0 }));
const state = {
usd,
threeUsd: threeTok?.usd || 0,
threeAmount: threeTok?.amount || 0,
...repState,
};
const look = computeLook(state);
const marks = computeMarks(state, { hubUrl });
return json(res, 200, {
data: {
agent_id: id,
address,
network: 'mainnet',
portfolio: {
usd,
sol,
sol_usd: balances?.native?.usd || 0,
three: threeTok ? { amount: threeTok.amount, usd: threeTok.usd || 0, price: threeTok.price || 0 } : null,
usdc: usdcTok?.usd || 0,
token_count: tokens.length,
top,
},
reputation,
flow: buildFlowPayload({ balanceSol: sol, balanceUsd: usd, tier: look.tier.key, flowRaw }),
tier: look.tier,
look,
marks,
prefs,
is_owner: isOwner,
hub_url: hubUrl,
// True when balances are a last-known-good snapshot served because the
// live chain read was briefly unavailable. The figures are real (the
// wallet's last successful read), just not freshly confirmed.
stale: balances?.stale === true,
updated_at: new Date().toISOString(),
},
});
}
// Shape the embodiment flow block the same way in every branch: the static
// balance/tier the aura already uses, plus the live momentum/streaming/recency
// dynamics. `momentum` is the bounded scalar the client maps to a warm/cool
// shift; the raw USD figures are kept for the owner's "why" breakdown.
function buildFlowPayload({ balanceSol, balanceUsd, tier, flowRaw }) {
return {
balance_sol: Number(balanceSol) || 0,
balance_usd: Number(balanceUsd) || 0,
tier,
momentum: momentumScalar(flowRaw.momentumUsd24h),
momentum_usd_24h: flowRaw.momentumUsd24h,
inflow_usd_24h: flowRaw.inflowUsd24h,
outflow_usd_24h: flowRaw.outflowUsd24h,
streaming_now: flowRaw.streamingNow,
last_tip_at: flowRaw.lastTipAt,
};
}
// ── tip recording (on-chain verified) ──────────────────────────────────────────
// POST /api/agents/:id/solana/tip — record a P2P tip that a visitor already sent
// on-chain from their OWN wallet (api/../src/shared/agent-tip.js builds + signs it
// client-side; three.ws never custodies it). The client hands us the confirmed
// signature; we INDEPENDENTLY verify on-chain that the transaction really credited
// the agent's public wallet before writing a row — so a caller can never fabricate
// a tip. The recorded tip is a PUBLIC custody event (event_type='tip') that powers
// the Money Pulse feed and the per-agent wallet story. Idempotent per signature.
// Parsed-tx account-key → base58 string (handles PublicKey or string pubkeys).
function _acctKeyStr(k) {
const p = k?.pubkey ?? k;
return typeof p === 'string' ? p : p?.toString?.() ?? '';
}
// Net lamports credited to `owner` from a parsed tx's pre/post native balances.
function _lamportsCreditedTo(tx, owner) {
const keys = tx.transaction?.message?.accountKeys || [];
const idx = keys.findIndex((k) => _acctKeyStr(k) === owner);
if (idx < 0) return 0n;
return BigInt(tx.meta?.postBalances?.[idx] ?? 0) - BigInt(tx.meta?.preBalances?.[idx] ?? 0);
}
// Net SPL atomics of `mint` credited to `owner`, from pre/post token balances.
function _tokenCreditedTo(tx, mint, owner) {
const pre = tx.meta?.preTokenBalances || [];
const post = tx.meta?.postTokenBalances || [];
let delta = 0n;
for (const p of post) {
if (p.mint !== mint || p.owner !== owner) continue;
const before = pre.find((x) => x.accountIndex === p.accountIndex);
delta += BigInt(p.uiTokenAmount?.amount ?? '0') - BigInt(before?.uiTokenAmount?.amount ?? '0');
}
return delta;
}
// First signer of the tx that isn't the recipient — the tipper.
function _firstSigner(tx, exclude) {
const keys = tx.transaction?.message?.accountKeys || [];
for (const k of keys) {
if (k?.signer && _acctKeyStr(k) !== exclude) return _acctKeyStr(k);
}
return null;
}
async function handleTip(req, res, id) {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true, origins: '*' })) return;
if (!method(req, res, ['POST'])) return;
// Tipping is open to anyone (signed-in or not); throttle per-IP to keep the
// on-chain verification (one getParsedTransaction) from being abused.
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const [row] = await sql`SELECT id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
const address = row.meta?.solana_address || null;
if (!address) return error(res, 404, 'not_found', 'agent has no solana wallet');
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
const signature = typeof body.signature === 'string' ? body.signature.trim() : '';
if (!signature || signature.length < 32 || signature.length > 128 || !BASE58_RE.test(signature)) {
return error(res, 400, 'validation_error', 'a valid base58 tx signature is required');
}
const network = body.network === 'devnet' ? 'devnet' : 'mainnet';
const assetRaw = typeof body.asset === 'string' && body.asset.trim() ? body.asset.trim().toUpperCase() : 'SOL';
// Fast idempotency: the same signature is recorded once per agent.
const idempotencyKey = `tip:${signature}`;
{
const [existing] = await sql`
SELECT id, asset, amount_lamports, amount_raw, usd FROM agent_custody_events
WHERE agent_id = ${id} AND idempotency_key = ${idempotencyKey}
`;
if (existing) {
return json(res, 200, {
data: {
recorded: false, replayed: true, signature,
explorer: explorerTxUrl(signature, network), network,
},
});
}
}
// Verify on-chain. The client already waited for confirmation, so 'confirmed'
// is sufficient for a record of an already-public transfer.
const conn = solanaConnection(network);
let tx;
try {
tx = await conn.getParsedTransaction(signature, { maxSupportedTransactionVersion: 1, commitment: 'confirmed' });
} catch {
tx = null;
}
if (!tx) {
// Maybe still finalizing — tell the client to retry rather than failing hard.
return error(res, 202, 'tx_pending', 'transaction not visible yet — it may still be confirming, retry shortly');
}
if (tx.meta?.err) return error(res, 422, 'tx_failed', 'that transaction failed on-chain — nothing was tipped');
// Resolve the credited amount + price.
let amountLamports = null, amountRaw = null, usd = null, assetOut = 'SOL', decimals = 9;
const usdcMint = USDC_MINT_BY_CLUSTER[network];
if (assetRaw === 'SOL') {
const lamports = _lamportsCreditedTo(tx, address);
if (lamports <= 0n) return error(res, 422, 'no_funds_received', 'no SOL was received at this agent wallet in that transaction');
amountLamports = lamports;
assetOut = 'SOL';
try { usd = await lamportsToUsd(lamports); } catch { usd = null; }
} else {
// SPL tip. Resolve the mint (USDC by name, or an explicit mint address).
const mint = assetRaw === 'USDC' ? usdcMint : (validateSolanaAddress(body.asset).valid ? validateSolanaAddress(body.asset).base58 : null);
if (!mint) return error(res, 400, 'invalid_asset', 'asset must be "SOL", "USDC", or a valid SPL mint');
const atomics = _tokenCreditedTo(tx, mint, address);
if (atomics <= 0n) return error(res, 422, 'no_funds_received', 'none of that token was received at this agent wallet in that transaction');
amountRaw = atomics;
assetOut = mint;
if (mint === usdcMint) { decimals = 6; usd = Number(atomics) / 1e6; }
}
const from = _firstSigner(tx, address);
const blockTime = tx.blockTime ? new Date(tx.blockTime * 1000).toISOString() : null;
// Record the public tip event. ON CONFLICT guards the rare race where two
// requests verify the same signature concurrently.
const inserted = await sql`
INSERT INTO agent_custody_events
(agent_id, user_id, event_type, category, network, asset,
amount_lamports, amount_raw, usd, destination, signature, status, idempotency_key, meta)
VALUES (
${id}, NULL, 'tip', 'tip', ${network}, ${assetOut},
${amountLamports != null ? String(amountLamports) : null},
${amountRaw != null ? String(amountRaw) : null},
${usd ?? null}, ${address}, ${signature}, 'confirmed', ${idempotencyKey},
${JSON.stringify({ source: 'p2p_tip', from: from || null, block_time: blockTime, decimals })}::jsonb
)
ON CONFLICT (agent_id, idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
RETURNING id
`;
if (!inserted.length) {
return json(res, 200, { data: { recorded: false, replayed: true, signature, explorer: explorerTxUrl(signature, network), network } });
}
// Reflect the inbound funds in the cached balance immediately.
await cacheSet(`sol:bal:${address}:${network}`, null, 1).catch(() => {});
// Patronage: a tip is real support — if it just pushed this patron into a new
// level, write a relationship memory the agent's chat will greet them with.
// Best-effort; never blocks or fails the (already-final) tip record.
if (from) maybeWritePatronMemory({ agentId: id, wallet: from, network }).catch(() => {});
const human = amountLamports != null ? Number(amountLamports) / 1e9 : Number(amountRaw) / 10 ** decimals;
// Wallet Intents: a real, freshly-recorded tip is a trigger. Fire the owner's
// on_tip_received / on_income rules (tip-back, split-income, notify) through the
// same spend-policy-gated, audited signing path. Fire-and-forget, idempotent per
// (intent, tip signature) — never blocks or fails the already-final tip record.
import('../_lib/wallet-intents.js')
.then(({ onTipRecorded }) => onTipRecorded(id, { signature, amount_sol: amountLamports != null ? Number(amountLamports) / 1e9 : null, usd: usd ?? null, from: from || null, network }))
.catch((e) => console.warn('[tip] intent eval failed', e?.message));
// Fork Royalty Streams: if this agent is a fork whose lineage carries a royalty,
// a SOL tip is eligible income — stream the creator-set, capped, decaying split
// upstream to its ancestors' real wallets. Idempotent per (tip event, ancestor),
// audited on both sides. Fire-and-forget; never blocks the already-final tip.
if (assetOut === 'SOL' && amountLamports != null) {
import('../_lib/fork-royalties.js')
.then(({ applyForkRoyalties }) => applyForkRoyalties(id, {
eventId: inserted[0].id, kind: 'tip', amountLamports, asset: 'SOL', network, fromWallet: from || null,
}))
.catch((e) => console.warn('[tip] fork royalty failed', e?.message));
}
return json(res, 201, {
data: {
recorded: true, replayed: false, id: String(inserted[0].id),
signature, explorer: explorerTxUrl(signature, network), network,
asset: assetOut, amount: human, usd: usd ?? null, from: from || null,
},
});
}
// ── public-pulse visibility toggle ──────────────────────────────────────────────
// GET/PUT /api/agents/:id/solana/pulse-visibility — owner-only control over whether
// this agent's already-public events appear in the GLOBAL Money Pulse discovery
// feed (/pulse). Default is included (opt_out = false) for public agents; an owner
// can suppress their wallet from the aggregated feed without going fully private.
// The agent's own profile/HUD pulse always shows its public history regardless —
// this toggle governs only the platform-wide discovery stream. Enforced server-side
// in api/pulse.js via meta.pulse_opt_out.
async function handlePulseVisibility(req, res, id) {
if (cors(req, res, { methods: 'GET,PUT,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'PUT'])) return;
const owned = await loadOwnedWallet(req, res, id);
if (owned.error) return;
const { auth, meta } = owned;
const rl = await limits.walletRead(auth.userId);
if (!rl.success) return rateLimited(res, rl);
const [agentRow] = await sql`SELECT is_public FROM agent_identities WHERE id = ${id}`;
const isPublic = agentRow?.is_public !== false;
if (req.method === 'PUT') {
// Flipping pulse visibility changes what the public can discover about this
// wallet — gate it behind CSRF like the other wallet settings.
if (!(await requireCsrf(req, res, auth.userId))) return;
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
if (typeof body.opt_out !== 'boolean') return error(res, 400, 'validation_error', 'opt_out must be a boolean');
const nextMeta = { ...meta, pulse_opt_out: body.opt_out };
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(nextMeta)}::jsonb WHERE id = ${id}`;
logAudit({ userId: auth.userId, action: 'wallet.pulse_visibility', resourceId: id, meta: { opt_out: body.opt_out }, req });
return json(res, 200, { data: { opt_out: body.opt_out, is_public: isPublic, in_public_pulse: isPublic && !body.opt_out } });
}
const optOut = meta.pulse_opt_out === true;
return json(res, 200, { data: { opt_out: optOut, is_public: isPublic, in_public_pulse: isPublic && !optOut } });
}
// ── money streams ───────────────────────────────────────────────────────────────
// A Money Stream is pay-per-second income: a visitor authorizes a rate + a signed
// max-total ceiling, then their browser micro-settles the accrued amount on a fixed
// cadence with a REAL on-chain transfer from their own wallet to the agent's public
// wallet (src/shared/agent-money-stream.js). Each settlement is one already-final
// transfer — three.ws never custodies the funds. The client hands us the confirmed
// signature; we INDEPENDENTLY verify on-chain that it credited the agent before
// recording it, and we refuse any settlement that would push a stream session over
// the ceiling it was opened with. Settlements are PUBLIC custody events
// (event_type='stream', category='stream') grouped by a client stream_id, so they
// power the agent's earnings view and the Money Pulse the same way tips do.
//
// POST /api/agents/:id/solana/stream — record + verify one settlement.
// GET /api/agents/:id/solana/stream — earnings (lifetime + earning-now + daily).
const STREAM_ID_RE = /^[0-9a-fA-F-]{8,64}$/;
// A stream is "earning now" while its last settlement is fresher than the longest
// settle cadence (60s) plus a grace window — anything older is a finished session.
const STREAM_LIVE_WINDOW_S = 150;
// Cumulative settlements may overshoot the signed ceiling only by floating-point
// dust; anything beyond this is a real over-ceiling attempt and is rejected.
const STREAM_CEILING_EPSILON = 1e-9;
// Human (whole-asset) amount a stream row settled, from its stored raw fields.
function _streamRowHuman(row, usdcMint) {
if (row.amount_lamports != null) return Number(row.amount_lamports) / 1e9;
if (row.amount_raw != null) return Number(row.amount_raw) / (row.asset === usdcMint ? 1e6 : 1e9);
return 0;
}
async function handleStreamRecord(req, res, id) {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true, origins: '*' })) return;
if (!method(req, res, ['POST'])) return;
// Streaming is open to anyone with a wallet (signed-in or not); throttle per-IP
// so the on-chain verification can't be abused. A settle fires every ~45–60s per
// active stream, well under this budget.
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const [row] = await sql`SELECT id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
const address = row.meta?.solana_address || null;
if (!address) return error(res, 404, 'not_found', 'agent has no solana wallet');
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
const signature = typeof body.signature === 'string' ? body.signature.trim() : '';
if (!signature || signature.length < 32 || signature.length > 128 || !BASE58_RE.test(signature)) {
return error(res, 400, 'validation_error', 'a valid base58 tx signature is required');
}
const streamId = typeof body.stream_id === 'string' ? body.stream_id.trim() : '';
if (!streamId || !STREAM_ID_RE.test(streamId)) {
return error(res, 400, 'validation_error', 'a valid stream_id (uuid) is required');
}
const network = body.network === 'devnet' ? 'devnet' : 'mainnet';
const assetRaw = typeof body.asset === 'string' && body.asset.trim() ? body.asset.trim().toUpperCase() : 'SOL';
const ratePerMinute = Number(body.rate_per_minute);
if (!Number.isFinite(ratePerMinute) || ratePerMinute <= 0) {
return error(res, 400, 'validation_error', 'rate_per_minute must be a positive number');
}
const maxTotal = Number(body.max_total);
if (!Number.isFinite(maxTotal) || maxTotal <= 0) {
return error(res, 400, 'validation_error', 'max_total must be a positive number');
}
const usdcMint = USDC_MINT_BY_CLUSTER[network];
// Idempotency: one row per settlement signature per agent.
const idempotencyKey = `stream:${signature}`;
{
const [existing] = await sql`
SELECT id FROM agent_custody_events
WHERE agent_id = ${id} AND idempotency_key = ${idempotencyKey}
`;
if (existing) {
return json(res, 200, { data: { recorded: false, replayed: true, signature, explorer: explorerTxUrl(signature, network), network } });
}
}
// Ceiling enforcement — the streamer signed a max_total when they opened this
// session; the sum of all confirmed settlements for the stream_id (plus this one)
// can never exceed it. We use the ceiling from the FIRST recorded settlement of
// the session as authoritative so a later request can't silently raise its own cap.
const priorRows = await sql`
SELECT amount_lamports, amount_raw, asset, meta
FROM agent_custody_events
WHERE agent_id = ${id} AND category = 'stream' AND meta->>'stream_id' = ${streamId}
`;
let priorSum = 0;
let sessionCeiling = maxTotal;
let sessionAsset = null;
for (const r of priorRows) {
priorSum += _streamRowHuman(r, usdcMint);
const c = Number(r.meta?.max_total);
if (Number.isFinite(c) && c > 0) sessionCeiling = c; // first/any prior ceiling wins
if (sessionAsset == null && r.asset) sessionAsset = r.asset;
}
// Verify on-chain before trusting the client's claimed amount.
const conn = solanaConnection(network);
let tx;
try {
tx = await conn.getParsedTransaction(signature, { maxSupportedTransactionVersion: 1, commitment: 'confirmed' });
} catch {
tx = null;
}
if (!tx) return error(res, 202, 'tx_pending', 'transaction not visible yet — it may still be confirming, retry shortly');
if (tx.meta?.err) return error(res, 422, 'tx_failed', 'that settlement failed on-chain — nothing was streamed');
// Resolve the credited amount + asset straight from the chain.
let amountLamports = null, amountRaw = null, usd = null, assetOut = 'SOL', decimals = 9;
if (assetRaw === 'SOL') {
const lamports = _lamportsCreditedTo(tx, address);
if (lamports <= 0n) return error(res, 422, 'no_funds_received', 'no SOL was received at this agent wallet in that settlement');
amountLamports = lamports;
assetOut = 'SOL';
try { usd = await lamportsToUsd(lamports); } catch { usd = null; }
} else {
const mint = assetRaw === 'USDC' ? usdcMint : (validateSolanaAddress(body.asset).valid ? validateSolanaAddress(body.asset).base58 : null);
if (!mint) return error(res, 400, 'invalid_asset', 'asset must be "SOL", "USDC", or a valid SPL mint');
const atomics = _tokenCreditedTo(tx, mint, address);
if (atomics <= 0n) return error(res, 422, 'no_funds_received', 'none of that token was received at this agent wallet in that settlement');
amountRaw = atomics;
assetOut = mint;
if (mint === usdcMint) { decimals = 6; usd = Number(atomics) / 1e6; }
}
// A stream session is single-asset. Reject a settlement that switches asset
// mid-stream — it would corrupt the ceiling accounting.
if (sessionAsset && sessionAsset !== assetOut) {
return error(res, 409, 'asset_mismatch', 'this settlement uses a different asset than the rest of the stream session');
}
const thisHuman = amountLamports != null ? Number(amountLamports) / 1e9 : Number(amountRaw) / 10 ** decimals;
if (priorSum + thisHuman > sessionCeiling + STREAM_CEILING_EPSILON) {
return error(res, 409, 'ceiling_exceeded', 'this settlement would exceed the stream ceiling you authorized — it was not recorded', {
ceiling: sessionCeiling, settled_so_far: priorSum, attempted: thisHuman,
});
}
const from = _firstSigner(tx, address);
const blockTime = tx.blockTime ? new Date(tx.blockTime * 1000).toISOString() : null;
const inserted = await sql`
INSERT INTO agent_custody_events
(agent_id, user_id, event_type, category, network, asset,
amount_lamports, amount_raw, usd, destination, signature, status, idempotency_key, meta)
VALUES (
${id}, NULL, 'stream', 'stream', ${network}, ${assetOut},
${amountLamports != null ? String(amountLamports) : null},
${amountRaw != null ? String(amountRaw) : null},
${usd ?? null}, ${address}, ${signature}, 'confirmed', ${idempotencyKey},
${JSON.stringify({
source: 'money_stream', stream_id: streamId, rate_per_minute: ratePerMinute,
max_total: sessionCeiling, asset: assetOut, from: from || null,
block_time: blockTime, decimals,
})}::jsonb
)
ON CONFLICT (agent_id, idempotency_key) WHERE idempotency_key IS NOT NULL DO NOTHING
RETURNING id
`;
if (!inserted.length) {
return json(res, 200, { data: { recorded: false, replayed: true, signature, explorer: explorerTxUrl(signature, network), network } });
}
// Reflect the inbound funds in the cached balance immediately.
await cacheSet(`sol:bal:${address}:${network}`, null, 1).catch(() => {});
// Patronage: streamed support accrues like tips — promote the patron's level
// and write a relationship memory on a crossing. Best-effort, non-blocking.
if (from) maybeWritePatronMemory({ agentId: id, wallet: from, network }).catch(() => {});
// Wallet Intents: a stream's first settlement is its "start"; every settlement is
// income. Fire the owner's on_stream_started / on_income rules through the same
// spend-policy-gated, audited signing path. Fire-and-forget, idempotent per
// (intent, stream/signature) — never blocks or fails the already-final record.
import('../_lib/wallet-intents.js')
.then(({ onStreamSettled }) => onStreamSettled(id, {
stream_id: streamId, signature,
amount_sol: amountLamports != null ? Number(amountLamports) / 1e9 : null,
usd: usd ?? null, from: from || null, network, first: priorRows.length === 0,
}))
.catch((e) => console.warn('[stream] intent eval failed', e?.message));
// Fork Royalty Streams: a SOL money-stream settlement is eligible income — split
// the creator-set, capped, decaying royalty upstream to ancestors. Idempotent per
// (settlement event, ancestor), audited both sides. Never blocks the settlement.
if (assetOut === 'SOL' && amountLamports != null) {
import('../_lib/fork-royalties.js')
.then(({ applyForkRoyalties }) => applyForkRoyalties(id, {
eventId: inserted[0].id, kind: 'stream', amountLamports, asset: 'SOL', network, fromWallet: from || null,
}))
.catch((e) => console.warn('[stream] fork royalty failed', e?.message));
}
return json(res, 201, {
data: {
recorded: true, replayed: false, id: String(inserted[0].id),
signature, explorer: explorerTxUrl(signature, network), network,
asset: assetOut, amount: thisHuman, usd: usd ?? null, from: from || null,
stream_id: streamId, settled_so_far: priorSum + thisHuman, ceiling: sessionCeiling,
},
});
}
async function handleStreamEarnings(req, res, id) {
if (cors(req, res, { methods: 'GET,OPTIONS', credentials: true, origins: '*' })) return;
if (!method(req, res, ['GET'])) return;
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const [row] = await sql`SELECT id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
const address = row.meta?.solana_address || null;
const url = new URL(req.url, 'http://x');
const network = url.searchParams.get('network') === 'devnet' ? 'devnet' : 'mainnet';
const fromRaw = url.searchParams.get('from');
const from = fromRaw && BASE58_RE.test(fromRaw) && fromRaw.length >= 32 && fromRaw.length <= 44 ? fromRaw : null;
const limit = Math.min(100, Math.max(1, parseInt(url.searchParams.get('limit') || '20', 10) || 20));
const beforeRaw = url.searchParams.get('before');
const beforeId = beforeRaw && /^\d+$/.test(beforeRaw) ? beforeRaw : null;
const usdcMint = USDC_MINT_BY_CLUSTER[network];
if (!address) {
return json(res, 200, {
data: {
agentId: id, network, has_wallet: false,
lifetime: { settlements: 0, sessions: 0, streamers: 0, sol: 0, usdc: 0, usd: 0 },
earning_now: { active_streams: 0, last_settle_at: null, usd_per_min: 0 },
daily: [], recent: [], next_cursor: null,
},
});
}
// Lifetime aggregates over every confirmed stream settlement.
const [life] = await sql`
SELECT
count(*)::int AS settlements,
count(DISTINCT meta->>'stream_id')::int AS sessions,
count(DISTINCT meta->>'from')::int AS streamers,
COALESCE(sum(amount_lamports), 0)::float8 AS lamports,
COALESCE(sum(amount_raw) FILTER (WHERE asset = ${usdcMint}), 0)::float8 AS usdc_raw,
COALESCE(sum(usd), 0)::float8 AS usd
FROM agent_custody_events
WHERE agent_id = ${id} AND category = 'stream' AND network = ${network}
`;
// Earning-now: stream sessions whose last settlement is still inside the live
// window. Their summed rate is the agent's current per-minute income.
const [live] = await sql`
SELECT
count(*)::int AS active_streams,
COALESCE(sum(rate), 0)::float8 AS usd_per_min,
max(last_at) AS last_settle_at
FROM (
SELECT meta->>'stream_id' AS sid,
max(created_at) AS last_at,
(array_agg((meta->>'rate_per_minute')::float8 ORDER BY created_at DESC))[1] AS rate
FROM agent_custody_events
WHERE agent_id = ${id} AND category = 'stream' AND network = ${network}
GROUP BY meta->>'stream_id'
HAVING max(created_at) > now() - (interval '1 second' * ${STREAM_LIVE_WINDOW_S})
) live_sessions
`;
// Daily USD + SOL income for the last 30 days (the owner earnings chart).
const daily = await sql`
SELECT to_char(date_trunc('day', created_at), 'YYYY-MM-DD') AS day,
COALESCE(sum(usd), 0)::float8 AS usd,
COALESCE(sum(amount_lamports), 0)::float8 / 1e9 AS sol
FROM agent_custody_events
WHERE agent_id = ${id} AND category = 'stream' AND network = ${network}
AND created_at > now() - interval '30 days'
GROUP BY 1 ORDER BY 1 ASC
`;
// Recent settlements (optionally scoped to one streamer's view).
const recentRows = await sql`
SELECT id, asset, amount_lamports, amount_raw, usd, signature, network, created_at, meta
FROM agent_custody_events
WHERE agent_id = ${id} AND category = 'stream' AND network = ${network}
AND (${from}::text IS NULL OR meta->>'from' = ${from})
AND (${beforeId}::bigint IS NULL OR id < ${beforeId})
ORDER BY id DESC
LIMIT ${limit}
`;
const recent = recentRows.map((e) => ({
id: String(e.id),
asset: e.asset === usdcMint ? 'USDC' : e.asset,
amount: _streamRowHuman(e, usdcMint),
usd: e.usd != null ? Number(e.usd) : null,
from: e.meta?.from || null,
stream_id: e.meta?.stream_id || null,
rate_per_minute: e.meta?.rate_per_minute != null ? Number(e.meta.rate_per_minute) : null,
signature: e.signature,
explorer: e.signature ? explorerTxUrl(e.signature, e.network) : null,
created_at: e.created_at,
}));
const nextCursor = recent.length === limit ? recent[recent.length - 1].id : null;
// A single streamer's own history with this agent (their "you've streamed" line).
let you = null;
if (from) {
const [y] = await sql`
SELECT count(*)::int AS settlements,
count(DISTINCT meta->>'stream_id')::int AS sessions,
COALESCE(sum(amount_lamports), 0)::float8 AS lamports,
COALESCE(sum(amount_raw) FILTER (WHERE asset = ${usdcMint}), 0)::float8 AS usdc_raw,
COALESCE(sum(usd), 0)::float8 AS usd
FROM agent_custody_events
WHERE agent_id = ${id} AND category = 'stream' AND network = ${network} AND meta->>'from' = ${from}
`;
you = {
settlements: y?.settlements || 0,
sessions: y?.sessions || 0,
sol: (Number(y?.lamports) || 0) / 1e9,
usdc: (Number(y?.usdc_raw) || 0) / 1e6,
usd: Number(y?.usd) || 0,
};
}
return json(res, 200, {
data: {
agentId: id, network, has_wallet: true, address,
lifetime: {
settlements: life?.settlements || 0,
sessions: life?.sessions || 0,
streamers: life?.streamers || 0,
sol: (Number(life?.lamports) || 0) / 1e9,
usdc: (Number(life?.usdc_raw) || 0) / 1e6,
usd: Number(life?.usd) || 0,
},
earning_now: {
active_streams: live?.active_streams || 0,
usd_per_min: Number(live?.usd_per_min) || 0,
last_settle_at: live?.last_settle_at || null,
},
daily: daily.map((d) => ({ day: d.day, usd: Number(d.usd) || 0, sol: Number(d.sol) || 0 })),
recent,
next_cursor: nextCursor,
...(you ? { you } : {}),
},
});
}
async function handleStream(req, res, id) {
if (req.method === 'GET') return handleStreamEarnings(req, res, id);
return handleStreamRecord(req, res, id);
}
// ── fork royalties ──────────────────────────────────────────────────────────────
// GET /api/agents/:id/solana/royalty — PUBLIC. The full, transparent split view
// both sides see: this agent's royalty RATE config + caps, what it earns from
// descendants' forks (ancestor view), and what it shares upstream as a fork
// itself (descendant view), every confirmed payout linking to a real tx.
// PUT /api/agents/:id/solana/royalty — OWNER-only (CSRF). Set the fork royalty
// rate (clamped to the platform per-creator cap) + which income types it applies
// to. Applies to FUTURE forks only — existing forks keep their frozen terms.
async function handleRoyalty(req, res, id) {
if (cors(req, res, { methods: 'GET,PUT,OPTIONS', credentials: true })) return;
if (!method(req, res, ['GET', 'PUT'])) return;
const [row] = await sql`SELECT id, user_id, meta FROM agent_identities WHERE id = ${id} AND deleted_at IS NULL`;
if (!row) return error(res, 404, 'not_found', 'agent not found');
if (req.method === 'PUT') {
const auth = await resolveAuth(req);
if (!auth) return error(res, 401, 'unauthorized', 'sign in required');
if (row.user_id !== auth.userId) return error(res, 403, 'forbidden', 'not your agent');
if (!(await requireCsrf(req, res, auth.userId))) return;
let body;
try {
body = await readJson(req);
} catch (e) {
return error(res, e?.status === 415 ? 415 : 400, 'bad_request', e?.message || 'invalid request body');
}
if (body.bps == null && body.pct == null) {
return error(res, 400, 'validation_error', 'bps (or pct) is required');
}
const requested = body.bps != null ? Number(body.bps) : Math.round(Number(body.pct) * 100);
if (!Number.isFinite(requested) || requested < 0) {
return error(res, 400, 'validation_error', 'royalty must be a non-negative number');
}
const bps = clampCreatorBps(requested);
const eligible = {
tips: body.eligible?.tips !== false,
stream: body.eligible?.stream !== false,
};
const prev = getRoyaltyConfig(row.meta);
const fork_royalty = bps > 0
? { bps, eligible, set_at: new Date().toISOString(), set_by: auth.userId }
: null; // 0 clears the royalty — forks of this become free again
const nextMeta = { ...(row.meta || {}), fork_royalty };
await sql`UPDATE agent_identities SET meta = ${JSON.stringify(nextMeta)}::jsonb WHERE id = ${id}`;
logAudit({ userId: auth.userId, action: 'wallet.fork_royalty', resourceId: id, meta: { prev_bps: prev.bps, bps, eligible }, req });
return json(res, 200, { data: royaltyConfigView(getRoyaltyConfig(nextMeta), { clamped: requested !== bps }) });
}
// GET — public, read-only. Resolve viewer for the is_owner flag only.
const auth = await resolveAuth(req).catch(() => null);
const isOwner = !!(auth && auth.userId === row.user_id);
const rl = await limits.publicIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const [config, descendant, ancestor] = await Promise.all([
Promise.resolve(royaltyConfigView(getRoyaltyConfig(row.meta), { is_owner: isOwner })),
getDescendantLedger(id).catch(() => null),
getAncestorLedger(id).catch(() => null),
]);
return json(res, 200, {
data: {
is_owner: isOwner,
config,
ancestor, // "earns royalties from N forks" + income by descendant
descendant, // "shares N% upstream" + schedule + what it has paid
},
});
}
function royaltyConfigView(cfg, extra = {}) {
return {
bps: cfg.bps,
pct: cfg.bps / 100,
eligible: cfg.eligible,
set_at: cfg.set_at,
has_royalty: cfg.bps > 0,
per_creator_cap_bps: ROYALTY_PER_CREATOR_CAP_BPS,
per_creator_cap_pct: ROYALTY_PER_CREATOR_CAP_BPS / 100,
total_cap_bps: ROYALTY_TOTAL_CAP_BPS,
total_cap_pct: ROYALTY_TOTAL_CAP_BPS / 100,
eligible_asset: ROYALTY_ELIGIBLE_ASSET,
...extra,
};
}
// ── dispatcher ────────────────────────────────────────────────────────────────
export default async function handler(req, res, id, action) {
if (action === 'activity') return handleActivity(req, res, id);
if (action === 'airdrop') return handleAirdrop(req, res, id);
if (action === 'withdraw') return handleWithdraw(req, res, id);
if (action === 'vanity') return handleVanity(req, res, id);
if (action === 'holdings') return handleHoldings(req, res, id);
if (action === 'reserves') {
const mod = await import('./_id/reserves.js');
return mod.handleReserves(req, res, id);
}
if (action === 'networth') return handleNetWorth(req, res, id);
if (action === 'custody') return handleCustody(req, res, id);
if (action === 'proof') return handleCustodyProof(req, res, id);
if (action === 'limits') return handleLimits(req, res, id);
if (action === 'guard') {
const mod = await import('./solana-guard.js');
return mod.handleGuard(req, res, id);
}
if (action === 'policy') return handlePolicy(req, res, id);
if (action === 'delegation') return handleDelegation(req, res, id);
if (action === 'allowance') {
const mod = await import('./solana-allowance.js');
return mod.handleAllowance(req, res, id);
}
if (action === 'tip') return handleTip(req, res, id);
if (action === 'royalty') return handleRoyalty(req, res, id);
if (action === 'stream') return handleStream(req, res, id);
if (action === 'pulse-visibility') return handlePulseVisibility(req, res, id);
if (action === 'patronage') {
const mod = await import('./patronage.js');
return mod.default(req, res, id);
}
if (action === 'intent') {
const mod = await import('./solana-intent.js');
return mod.handleIntent(req, res, id);
}
if (action === 'trade') {
const mod = await import('./solana-trade.js');
return mod.handleTrade(req, res, id);
}
if (action === 'trade-history') {
const mod = await import('./solana-trade.js');
return mod.handleTradeHistory(req, res, id);
}
return handleWallet(req, res, id);
}
export { handleWithdraw };