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
/**
* Shared plumbing for autonomous purchases paid from an agent's own custodial
* Solana wallet.
*
* Two marketplace surfaces sell things an agent can buy for itself: individual
* skills (`skill_purchases`, via /api/marketplace/purchase-as-agent) and whole
* assets (avatars, agents, plugins; `asset_purchases`, via
* /api/marketplace/buy-asset with an `agent_id`). Both spend real USDC out of the
* same wallet under the same owner-configured ceiling, so the cap accounting,
* keypair recovery and transfer construction live here rather than being forked
* per endpoint.
*
* The daily ceiling is `agent_identities.meta.auto_purchase_daily_limit_usdc`
* (a number, e.g. 10 = $10/day; absent or <= 0 means no cap). It spans BOTH
* tables: an agent that spent its budget on skills cannot then spend it again on
* assets. Enforcement is two-phase at every call site, and the second phase is
* the authoritative one:
*
* 1. Pre-check before doing expensive work: a cheap early rejection, and a
* TOCTOU on its own (concurrent buys all read the same pre-spend SUM).
* 2. Re-check AFTER the pending row is inserted. The row is now counted by the
* same SUM, so every concurrent in-flight purchase is visible and the total
* cannot be collectively overshot. Fails safe: contending requests abort
* rather than risk exceeding the owner's limit.
*
* Nothing here decides WHETHER a purchase is allowed beyond the cap. Ownership,
* rate limits, self-dealing and already-owned checks stay with the endpoints,
* which have the surface-specific context to answer them.
*/
import { PublicKey } from '@solana/web3.js';
import {
getAssociatedTokenAddressSync,
createTransferCheckedInstruction,
createAssociatedTokenAccountIdempotentInstruction,
} from '@solana/spl-token';
import { sql } from './db.js';
import { mintDecimals } from './solana/read-guards.js';
import { submitProtected } from './execution-engine.js';
import { ensureAgentWallet, recoverSolanaAgentKeypair } from './agent-wallet.js';
export const USDC_DECIMALS = 6;
/** Start of the current UTC day, as an ISO string: the cap window boundary. */
export function dayStartIso() {
const d = new Date();
d.setUTCHours(0, 0, 0, 0);
return d.toISOString();
}
/**
* Read the owner-configured autonomous purchase ceiling off an agent's meta.
* @param {object|null} meta - agent_identities.meta
* @returns {{ enabled: boolean, limitUsdc: number|null, limitAtomics: bigint }}
*/
export function readPurchaseCap(meta) {
const limitUsdc = meta?.auto_purchase_daily_limit_usdc;
const enabled = typeof limitUsdc === 'number' && Number.isFinite(limitUsdc) && limitUsdc > 0;
return {
enabled,
limitUsdc: enabled ? limitUsdc : null,
limitAtomics: enabled ? BigInt(Math.round(limitUsdc * 10 ** USDC_DECIMALS)) : 0n,
};
}
/**
* Total atomics this user's agents have committed to autonomous purchases today,
* in one currency, across BOTH purchase tables. Rows in a terminal-failure state
* ('failed', 'expired') never count; 'pending' rows do, so an in-flight purchase
* holds its share of the budget until it resolves.
*
* @param {{ userId: string, currencyMint: string }} args
* @returns {Promise<bigint>}
*/
export async function sumDailyPurchaseAtomics({ userId, currencyMint }) {
const since = dayStartIso();
const [row] = await sql`
SELECT (
COALESCE((
SELECT SUM(amount) FROM skill_purchases
WHERE user_id = ${userId}
AND created_at >= ${since}
AND currency_mint = ${currencyMint}
AND status NOT IN ('failed', 'expired')
), 0)
+
COALESCE((
SELECT SUM(amount) FROM asset_purchases
WHERE buyer_user_id = ${userId}
AND created_at >= ${since}
AND currency_mint = ${currencyMint}
AND status NOT IN ('failed', 'expired')
), 0)
)::bigint AS total
`;
// ::bigint (not ::numeric) is load-bearing: SUM() yields numeric, which the
// driver can hand back as "2500000.00", a string BigInt() refuses to parse.
return BigInt(row?.total ?? 0);
}
/**
* Human-readable cap-exceeded message, shared so both surfaces explain the same
* limit with the same remedy.
*/
export function capExceededMessage(limitUsdc) {
return `daily agent purchase cap of ${limitUsdc} USDC reached. Raise meta.auto_purchase_daily_limit_usdc or wait until UTC midnight`;
}
/**
* Load a buyer agent's custodial keypair, provisioning the wallet if it is
* missing or corrupt. Every decrypt is audit-logged with `reason` into
* usage_events + the owner-viewable custody trail.
*
* The caller must ALREADY have verified that `userId` owns `agentId`; this
* function does not authorize, it only loads.
*
* @param {{ agentId: string, userId: string, reason: string, meta?: object }} args
* @returns {Promise<{ keypair: import('@solana/web3.js').Keypair, address: string, agentMeta: object }>}
*/
export async function loadBuyerAgentKeypair({ agentId, userId, reason, meta = {} }) {
// Repairs an unparseable address or a missing secret rather than letting a
// downstream PublicKey()/sign call throw on it.
await ensureAgentWallet(agentId, userId, { reason });
const [row] = await sql`
SELECT meta FROM agent_identities
WHERE id = ${agentId} AND deleted_at IS NULL
`;
const agentMeta = row?.meta || {};
const encrypted = agentMeta.encrypted_solana_secret;
if (!encrypted) {
const err = new Error('agent has no Solana wallet');
err.code = 'no_buyer_wallet';
throw err;
}
const keypair = await recoverSolanaAgentKeypair(encrypted, { agentId, userId, reason, meta });
return { keypair, address: keypair.publicKey.toBase58(), agentMeta };
}
/**
* Build and broadcast the SPL payment for an autonomous purchase: an idempotent
* ATA-create for the seller (buyer pays the rent) plus a transferChecked
* carrying the Solana Pay reference key, so the same findReference /
* validateTransfer verification the browser flow uses works unchanged.
*
* Sent through submitProtected: data-driven compute-unit estimate, escalating
* priority fee, blockhash-refresh rebroadcast, and a hard throw on an on-chain
* revert (never a silently-dropped transaction).
*
* @param {{
* connection: import('@solana/web3.js').Connection,
* keypair: import('@solana/web3.js').Keypair,
* currencyMint: string,
* recipient: string,
* amountAtomics: bigint|string|number,
* referenceKey: import('@solana/web3.js').PublicKey,
* }} args
* @returns {Promise<string>} the confirmed transaction signature
*/
export async function sendAgentPurchaseTransfer({
connection,
keypair,
currencyMint,
recipient,
amountAtomics,
referenceKey,
}) {
const mintKey = new PublicKey(currencyMint);
const recipKey = new PublicKey(recipient);
const decimals = await mintDecimals(connection, mintKey);
const fromAta = getAssociatedTokenAddressSync(mintKey, keypair.publicKey);
const toAta = getAssociatedTokenAddressSync(mintKey, recipKey);
const transferIx = createTransferCheckedInstruction(
fromAta, mintKey, toAta, keypair.publicKey,
BigInt(amountAtomics), decimals,
);
// The reference key is a non-signer, non-writable account on the transfer so
// findReference() can locate this exact payment on-chain afterwards.
transferIx.keys.push({ pubkey: referenceKey, isSigner: false, isWritable: false });
const { signature } = await submitProtected({
network: 'mainnet',
connection,
payer: keypair,
instructions: [
createAssociatedTokenAccountIdempotentInstruction(keypair.publicKey, toAta, recipKey, mintKey),
transferIx,
],
});
return signature;
}