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
/**
* Pump.fun composition skills — agent-level loops over read (MCP) + trade (signed).
* Composes pumpfun-buy / pumpfun-sell / pumpfun-status in-process.
*
* Args supported by every loop:
* - sessionId:"..." → seen/mirrored/spent/exited persisted in agent memory,
* survives crashes within the spend cap.
* - signal → AbortSignal; loops, sleeps, and inner iterations all
* bail out promptly when aborted.
* - onProgress(evt) → called on every state change (vet/skip/buy/sell/sleep).
* Used by the UI for live counters.
* - dryRun:true → identical control flow; trade-skill calls are replaced
* with `{ signature: null, dryRun: true }`. Spend cap
* and seen/mirrored sets still tick so a dry-run
* terminates the same way a live run would.
*/
import { WalletMonitor } from './pump/wallet-monitor.js';
const MCP_ENDPOINT = 'https://pump-fun-sdk.modelcontextprotocol.name/mcp';
const _sessions = new Map();
let _rpcId = 0;
const DEFAULTS = {
sessionSpendCapSol: 1.0,
perTradeSol: 0.05,
minHoldersForBuy: 30,
maxTopHolderPct: 25,
rejectIfCreatorRugCount: 1,
exitOnConcentrationPct: 40,
exitOnDevSellPct: 25,
pollMs: 5000,
};
function cfg(ctx, key) {
return ctx?.skillConfig?.[key] ?? DEFAULTS[key];
}
async function mcp(toolName, args) {
const res = await fetch(MCP_ENDPOINT, {
method: 'POST',
signal: AbortSignal.timeout(30_000),
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
jsonrpc: '2.0',
id: ++_rpcId,
method: 'tools/call',
params: { name: toolName, arguments: args ?? {} },
}),
});
if (!res.ok) throw new Error(`pump-fun MCP HTTP ${res.status}`);
const body = await res.json();
if (body.error) throw new Error(body.error.message ?? 'pump-fun MCP error');
const text = body.result?.content?.find?.((c) => c.type === 'text')?.text;
if (text) {
try { return JSON.parse(text); } catch { return text; }
}
return body.result;
}
async function loadState(memory, sessionId, init) {
if (!sessionId) return { ...init };
if (_sessions.has(sessionId)) return _sessions.get(sessionId);
try {
const entries = memory?.query?.({ tags: [`compose:${sessionId}`], limit: 1 }) || [];
const prior = entries[0]?.content;
if (prior && typeof prior === 'object') {
const restored = {
...init,
...prior,
seen: new Set(prior.seen || []),
mirrored: new Set(prior.mirrored || []),
exited: new Set(prior.exited || []),
};
_sessions.set(sessionId, restored);
return restored;
}
} catch {}
const fresh = { ...init };
_sessions.set(sessionId, fresh);
return fresh;
}
function saveState(memory, sessionId, state) {
if (!sessionId) return;
_sessions.set(sessionId, state);
const serializable = {
...state,
seen: state.seen ? [...state.seen] : undefined,
mirrored: state.mirrored ? [...state.mirrored] : undefined,
exited: state.exited ? [...state.exited] : undefined,
};
try {
memory?.add?.({
type: 'project',
content: serializable,
tags: [`compose:${sessionId}`],
important: true,
});
} catch {}
}
function abortableSleep(ms, signal) {
return new Promise((resolve) => {
if (signal?.aborted) return resolve();
const t = setTimeout(resolve, ms);
const onAbort = () => { clearTimeout(t); resolve(); };
signal?.addEventListener?.('abort', onAbort, { once: true });
});
}
async function doBuy(skills, ctx, dryRun, mint, solAmount) {
if (dryRun) return { signature: null, dryRun: true };
const r = await skills.perform('pumpfun-buy', { mint, solAmount }, ctx);
if (!r?.success) throw new Error(r?.output || 'pumpfun-buy failed');
return r.data;
}
async function doSell(skills, ctx, dryRun, mint) {
const status = await skills.perform('pumpfun-status', { mint }, ctx);
const tokenAmount = status?.data?.userBalance ?? '0';
if (tokenAmount === '0') return { signature: null, skipped: 'no-balance', tokenAmount };
if (dryRun) return { signature: null, dryRun: true, tokenAmount };
const r = await skills.perform('pumpfun-sell', { mint, tokenAmount }, ctx);
if (!r?.success) throw new Error(r?.output || 'pumpfun-sell failed');
return { ...r.data, tokenAmount };
}
function emit(progress, evt) {
try { progress?.(evt); } catch {}
}
function passesFilters(ctx, { creator, holders }) {
const rugCount = creator?.rugCount ?? creator?.rugFlags?.length ?? 0;
if (rugCount >= cfg(ctx, 'rejectIfCreatorRugCount')) {
return { ok: false, reason: `creator has ${rugCount} prior rug(s)` };
}
const holderCount = holders?.total ?? holders?.holders?.length ?? 0;
if (holderCount < cfg(ctx, 'minHoldersForBuy')) {
return { ok: false, reason: `only ${holderCount} holders` };
}
const top = holders?.topHolderPct ?? holders?.holders?.[0]?.pct ?? 0;
if (top > cfg(ctx, 'maxTopHolderPct')) {
return { ok: false, reason: `top holder owns ${top}%` };
}
return { ok: true };
}
async function vetMint(mint) {
const [details, holders] = await Promise.all([
mcp('getTokenDetails', { mint }),
mcp('getTokenHolders', { mint, limit: 20 }),
]);
const creatorAddr = details?.creator ?? details?.token?.creator;
const creator = creatorAddr ? await mcp('getCreatorProfile', { creator: creatorAddr }) : { rugCount: 0 };
return { details, holders, creator };
}
/**
* @param {import('./agent-skills.js').AgentSkills} skills
*/
export function registerPumpFunComposeSkills(skills) {
skills.register({
name: 'pumpfun-research-and-buy',
description: 'Research a pump.fun token, then buy if it passes rug/holder filters.',
instruction: 'search → vet (curve, holders, creator rug flags) → buy via pumpfun-buy.',
animationHint: 'inspect',
voicePattern: 'Researching {{query}}…',
mcpExposed: true,
inputSchema: {
type: 'object',
properties: {
query: { type: 'string' },
amountSol: { type: 'number' },
dryRun: { type: 'boolean', description: 'Vet/quote but skip the actual buy.' },
},
required: ['query'],
},
handler: async (args, ctx) => {
const dryRun = !!args.dryRun;
const onProgress = args.onProgress;
emit(onProgress, { type: 'search', query: args.query });
const search = await mcp('searchTokens', { query: args.query, limit: 1 });
const mint = search?.results?.[0]?.mint ?? search?.[0]?.mint ?? args.query;
emit(onProgress, { type: 'vet', mint });
const v = await vetMint(mint);
const verdict = passesFilters(ctx, v);
if (!verdict.ok) {
emit(onProgress, { type: 'skip', mint, reason: verdict.reason });
return {
success: true,
output: `Skipping ${mint.slice(0, 8)}…: ${verdict.reason}`,
sentiment: -0.1,
data: { mint, decision: 'skip', reason: verdict.reason, dryRun },
};
}
const amountSol = args.amountSol ?? cfg(ctx, 'perTradeSol');
emit(onProgress, { type: dryRun ? 'dry-buy' : 'buy', mint, amountSol });
const buy = await doBuy(skills, ctx, dryRun, mint, amountSol);
return {
success: true,
output: dryRun
? `Dry-run buy ${amountSol} SOL of ${mint.slice(0, 8)}….`
: `Bought ${amountSol} SOL of ${mint.slice(0, 8)}….`,
sentiment: 0.6,
data: { mint, decision: 'buy', amountSol, sig: buy.signature, dryRun },
};
},
});
skills.register({
name: 'pumpfun-auto-snipe',
description: 'Poll new tokens, vet, and auto-buy each pass with perTradeSol until sessionSpendCapSol. Persists seen/spent under sessionId.',
instruction: 'autoSnipe loop. Use simulate:true to validate filters without spending.',
animationHint: 'gesture',
voicePattern: 'Sniping for {{durationSec}}s…',
mcpExposed: true,
inputSchema: {
type: 'object',
properties: {
durationSec: { type: 'integer', minimum: 10, maximum: 3600 },
perTradeSol: { type: 'number' },
sessionId: { type: 'string' },
dryRun: { type: 'boolean' },
},
required: ['durationSec'],
},
handler: async (args, ctx) => {
const dryRun = !!args.dryRun;
const onProgress = args.onProgress;
const signal = args.signal;
const sessionId = args.sessionId;
const deadline = Date.now() + args.durationSec * 1000;
const perTrade = args.perTradeSol ?? cfg(ctx, 'perTradeSol');
const cap = cfg(ctx, 'sessionSpendCapSol');
const state = await loadState(ctx?.memory, sessionId, { seen: new Set(), spent: 0, log: [] });
emit(onProgress, { type: 'start', mode: 'auto-snipe', spent: state.spent, cap });
while (!signal?.aborted && Date.now() < deadline && state.spent + perTrade <= cap) {
const fresh = await mcp('getNewTokens', { limit: 20 }).catch(() => null);
const items = fresh?.tokens ?? fresh ?? [];
for (const t of items) {
if (signal?.aborted) break;
const mint = t.mint ?? t.address;
if (!mint || state.seen.has(mint)) continue;
state.seen.add(mint);
emit(onProgress, { type: 'vet', mint });
const v = await vetMint(mint).catch((e) => ({ verdict: { ok: false, reason: e.message } }));
const verdict = v.verdict || passesFilters(ctx, v);
if (!verdict.ok) {
state.log.push({ mint, action: 'skip', reason: verdict.reason });
emit(onProgress, { type: 'skip', mint, reason: verdict.reason, spent: state.spent });
continue;
}
try {
const buy = await doBuy(skills, ctx, dryRun, mint, perTrade);
state.spent += perTrade;
state.log.push({ mint, action: dryRun ? 'dry-buy' : 'buy', sig: buy.signature, spent: state.spent });
saveState(ctx?.memory, sessionId, state);
emit(onProgress, { type: dryRun ? 'dry-buy' : 'buy', mint, sig: buy.signature, spent: state.spent });
if (state.spent + perTrade > cap) break;
} catch (e) {
state.log.push({ mint, action: 'error', reason: e.message });
emit(onProgress, { type: 'error', mint, reason: e.message });
}
}
saveState(ctx?.memory, sessionId, state);
if (signal?.aborted || Date.now() >= deadline || state.spent + perTrade > cap) break;
emit(onProgress, { type: 'poll-sleep', ms: cfg(ctx, 'pollMs') });
await abortableSleep(cfg(ctx, 'pollMs'), signal);
}
const reason = signal?.aborted ? 'aborted' : Date.now() >= deadline ? 'duration' : 'cap';
return {
success: true,
output: `${dryRun ? 'Dry-run' : 'Snipe'} done (${reason}). Spent ${state.spent} SOL across ${state.log.length} events.`,
sentiment: 0.4,
data: { spent: state.spent, trades: state.log, dryRun, sessionId, reason },
};
},
});
skills.register({
name: 'pumpfun-copy-trade',
description: 'Mirror a wallet\'s recent pump.fun buys with size scaling. Persists mirrored sigs under sessionId.',
instruction: 'copyTrade loop.',
animationHint: 'gesture',
voicePattern: 'Copy-trading {{wallet}}…',
mcpExposed: true,
inputSchema: {
type: 'object',
properties: {
wallet: { type: 'string' },
sizeMultiplier: { type: 'number', minimum: 0.001, maximum: 10 },
durationSec: { type: 'integer', minimum: 10, maximum: 7200 },
sessionId: { type: 'string' },
dryRun: { type: 'boolean' },
},
required: ['wallet', 'durationSec'],
},
handler: async (args, ctx) => {
const dryRun = !!args.dryRun;
const onProgress = args.onProgress;
const signal = args.signal;
const sessionId = args.sessionId;
const deadline = Date.now() + args.durationSec * 1000;
const mult = args.sizeMultiplier ?? 1;
const cap = cfg(ctx, 'sessionSpendCapSol');
const state = await loadState(ctx?.memory, sessionId, { mirrored: new Set(), spent: 0, log: [] });
emit(onProgress, { type: 'start', mode: 'copy-trade', wallet: args.wallet, spent: state.spent, cap });
while (!signal?.aborted && Date.now() < deadline && state.spent < cap) {
const profile = await mcp('getCreatorProfile', { creator: args.wallet }).catch(() => null);
const recentMints = (profile?.tokens ?? []).map((t) => t.mint).filter(Boolean);
for (const mint of recentMints) {
if (signal?.aborted) break;
const trades = await mcp('getTokenTrades', { mint, limit: 20 }).catch(() => null);
const buys = (trades?.trades ?? trades ?? []).filter(
(t) => t.side === 'buy' && t.wallet === args.wallet && !state.mirrored.has(t.sig),
);
for (const b of buys) {
if (signal?.aborted) break;
state.mirrored.add(b.sig);
const amountSol = Math.min((b.solAmount ?? 0) * mult, cap - state.spent);
if (amountSol <= 0) break;
try {
const r = await doBuy(skills, ctx, dryRun, mint, amountSol);
state.spent += amountSol;
state.log.push({ mint, mirroredFrom: b.sig, sig: r.signature, amountSol, dryRun });
saveState(ctx?.memory, sessionId, state);
emit(onProgress, { type: dryRun ? 'dry-buy' : 'buy', mint, sig: r.signature, amountSol, spent: state.spent });
} catch (e) {
state.log.push({ mint, error: e.message });
emit(onProgress, { type: 'error', mint, reason: e.message });
}
}
}
saveState(ctx?.memory, sessionId, state);
if (signal?.aborted || Date.now() >= deadline || state.spent >= cap) break;
emit(onProgress, { type: 'poll-sleep', ms: cfg(ctx, 'pollMs') });
await abortableSleep(cfg(ctx, 'pollMs'), signal);
}
const reason = signal?.aborted ? 'aborted' : Date.now() >= deadline ? 'duration' : 'cap';
return {
success: true,
output: `${dryRun ? 'Dry-run' : 'Copy-trade'} done (${reason}). Mirrored ${state.log.length} buys, spent ${state.spent} SOL.`,
sentiment: 0.4,
data: { spent: state.spent, mirrors: state.log, dryRun, sessionId, reason },
};
},
});
skills.register({
name: 'pumpfun-rug-exit-watch',
description: 'Watch held mints; auto-sell on top-holder concentration or dev-wallet sell triggers. Persists exited mints under sessionId.',
instruction: 'rugExitWatch loop.',
animationHint: 'concern',
voicePattern: 'Watching {{mints.length}} positions…',
mcpExposed: true,
inputSchema: {
type: 'object',
properties: {
mints: { type: 'array', items: { type: 'string' } },
durationSec: { type: 'integer', minimum: 10, maximum: 86400 },
sessionId: { type: 'string' },
dryRun: { type: 'boolean' },
},
required: ['mints', 'durationSec'],
},
handler: async (args, ctx) => {
const dryRun = !!args.dryRun;
const onProgress = args.onProgress;
const signal = args.signal;
const sessionId = args.sessionId;
const deadline = Date.now() + args.durationSec * 1000;
const concentrationLimit = cfg(ctx, 'exitOnConcentrationPct');
const devSellLimit = cfg(ctx, 'exitOnDevSellPct');
const state = await loadState(ctx?.memory, sessionId, { exited: new Set(), log: [] });
emit(onProgress, { type: 'start', mode: 'rug-exit-watch', mints: args.mints });
while (!signal?.aborted && Date.now() < deadline && state.exited.size < args.mints.length) {
for (const mint of args.mints) {
if (signal?.aborted) break;
if (state.exited.has(mint)) continue;
const [holders, trades, details] = await Promise.all([
mcp('getTokenHolders', { mint, limit: 10 }).catch(() => null),
mcp('getTokenTrades', { mint, limit: 50 }).catch(() => null),
mcp('getTokenDetails', { mint }).catch(() => null),
]);
const top = holders?.topHolderPct ?? holders?.holders?.[0]?.pct ?? 0;
const dev = details?.creator ?? details?.token?.creator;
const devSells = (trades?.trades ?? trades ?? []).filter((t) => t.side === 'sell' && t.wallet === dev);
const devSellPct = devSells.reduce((s, t) => s + (t.pctOfSupply ?? 0), 0);
let trigger = null;
if (top >= concentrationLimit) trigger = `top holder ${top}%`;
else if (devSellPct >= devSellLimit) trigger = `dev sold ${devSellPct}%`;
if (!trigger) {
emit(onProgress, { type: 'tick', mint, top, devSellPct });
continue;
}
try {
const sell = await doSell(skills, ctx, dryRun, mint);
if (sell.skipped === 'no-balance') {
state.log.push({ mint, trigger, action: 'skipped-no-balance' });
emit(onProgress, { type: 'skip', mint, reason: 'no-balance' });
} else {
state.exited.add(mint);
state.log.push({ mint, trigger, sig: sell.signature, tokenAmount: sell.tokenAmount, dryRun });
emit(onProgress, { type: dryRun ? 'dry-sell' : 'sell', mint, sig: sell.signature, trigger });
}
saveState(ctx?.memory, sessionId, state);
} catch (e) {
state.log.push({ mint, trigger, error: e.message });
emit(onProgress, { type: 'error', mint, reason: e.message });
}
}
saveState(ctx?.memory, sessionId, state);
if (signal?.aborted || Date.now() >= deadline || state.exited.size >= args.mints.length) break;
emit(onProgress, { type: 'poll-sleep', ms: cfg(ctx, 'pollMs') });
await abortableSleep(cfg(ctx, 'pollMs'), signal);
}
const reason = signal?.aborted ? 'aborted' : Date.now() >= deadline ? 'duration' : 'all-exited';
return {
success: true,
output: `Exit watch done (${reason}). Exited ${state.exited.size}/${args.mints.length} positions.`,
sentiment: state.exited.size > 0 ? -0.2 : 0.2,
data: { exited: [...state.exited], events: state.log, dryRun, sessionId, reason },
};
},
});
skills.register({
name: 'pumpfun-copy-trade-live',
description:
"Mirror a wallet's pump.fun trades in real-time via WebSocket (~100ms latency). Mirrors both buys AND sells. Use instead of pumpfun-copy-trade when speed matters.",
instruction:
'WebSocket logsSubscribe on the target wallet. Fires doBuy on buy events, doSell on sell events (if we hold the mint). Stops at durationSec, spendCap, or abort.',
animationHint: 'gesture',
voicePattern: 'Live copy-trading {{wallet}}…',
mcpExposed: true,
inputSchema: {
type: 'object',
properties: {
wallet: { type: 'string', description: 'Base58 Solana address to mirror.' },
sizeMultiplier: { type: 'number', minimum: 0.001, maximum: 10, description: 'Scale factor applied to the target\'s trade size.' },
durationSec: { type: 'integer', minimum: 10, maximum: 7200 },
network: { type: 'string', enum: ['mainnet', 'devnet'] },
sessionId: { type: 'string' },
dryRun: { type: 'boolean' },
},
required: ['wallet', 'durationSec'],
},
handler: async (args, ctx) => {
const dryRun = !!args.dryRun;
const onProgress = args.onProgress;
const signal = args.signal;
const sessionId = args.sessionId;
const mult = args.sizeMultiplier ?? 1;
const cap = cfg(ctx, 'sessionSpendCapSol');
const state = await loadState(ctx?.memory, sessionId, { mirrored: new Set(), spent: 0, log: [] });
const monitor = new WalletMonitor(args.wallet, { network: args.network ?? 'mainnet' });
emit(onProgress, { type: 'start', mode: 'copy-trade-live', wallet: args.wallet, spent: state.spent, cap });
await new Promise((resolve) => {
if (signal?.aborted) { resolve(); return; }
const timer = setTimeout(resolve, args.durationSec * 1000);
signal?.addEventListener?.('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
monitor.addEventListener('trade', async (evt) => {
if (signal?.aborted || state.spent >= cap) { clearTimeout(timer); resolve(); return; }
const { side, mint, solAmount, signature } = evt;
// Skip if we already acted on this tx
if (state.mirrored.has(signature)) return;
state.mirrored.add(signature);
try {
if (side === 'buy') {
const amount = Math.min(solAmount * mult, cap - state.spent);
if (amount <= 0) return;
emit(onProgress, { type: dryRun ? 'dry-buy' : 'buy', mint, solAmount: amount, spent: state.spent });
const r = await doBuy(skills, ctx, dryRun, mint, amount);
state.spent += amount;
state.log.push({ side: 'buy', mint, mirroredSig: signature, sig: r.signature, solAmount: amount, dryRun });
} else {
// Sell — only if we hold the mint
emit(onProgress, { type: dryRun ? 'dry-sell' : 'sell', mint });
const r = await doSell(skills, ctx, dryRun, mint);
if (r.skipped !== 'no-balance') {
state.log.push({ side: 'sell', mint, mirroredSig: signature, sig: r.signature, dryRun });
}
}
saveState(ctx?.memory, sessionId, state);
} catch (e) {
state.log.push({ side, mint, error: e.message });
emit(onProgress, { type: 'error', mint, reason: e.message });
}
});
monitor.start();
});
monitor.stop();
const reason = signal?.aborted ? 'aborted' : state.spent >= cap ? 'cap' : 'duration';
return {
success: true,
output: `${dryRun ? 'Dry-run' : 'Live copy-trade'} done (${reason}). Mirrored ${state.log.length} trades, spent ${state.spent.toFixed(4)} SOL.`,
sentiment: 0.4,
data: { spent: state.spent, mirrors: state.log, dryRun, sessionId, reason },
};
},
});
}