@three-ws/avatar-agent 1.0.0

package/src/lib/atomic-launch.js

@@ -0,0 +1,184 @@
+// Atomic pump.fun token launch via a Jito bundle.
+//
+// Ported from nirholas/atomic's fire-jito.js. Two-tx bundle:
+//   Tx 1 (funder pays fee + tip): transfer rent SOL to creator + Jito tip
+//   Tx 2 (creator pays fee):     pump.fun createV2 instruction
+//
+// Both txs share the same recent blockhash and are submitted as a bundle to
+// Jito's mainnet block engine. Either both land or neither does — so no
+// MEV searcher can interleave, and the creator wallet doesn't need to hold
+// SOL before the launch.
+//
+// This is the "real launch" path: the on-chain `creator` field on the mint
+// is the creator wallet, not the funder. That matters because pump.fun's
+// creator-fee accrual follows the creator key.
+
+import {
+	Keypair,
+	PublicKey,
+	SystemProgram,
+	TransactionMessage,
+	VersionedTransaction,
+	ComputeBudgetProgram,
+	LAMPORTS_PER_SOL,
+} from '@solana/web3.js';
+import FormData from 'form-data';
+
+import { bs58encode, bs58decode, getConnection, keypairFromSecret } from './solana.js';
+import { JITO_TIP_ACCOUNTS, randomTipAccount, submitBundle, waitForSignatures } from './jito.js';
+
+const PUMP_IPFS_URL = 'https://pump.fun/api/ipfs';
+
+// Upload token metadata + image to pump.fun's IPFS endpoint. Returns the
+// metadata URI you feed into createV2. If no imageUrl is provided we use a
+// 1x1 transparent PNG placeholder so the form is valid; pass an imageUrl
+// to use a real image fetched at upload time.
+export async function uploadPumpMetadata({ name, symbol, description = '', twitter = '', telegram = '', website = '', imageUrl, showName = true }) {
+	if (!name) throw new Error('uploadPumpMetadata: name is required');
+	if (!symbol) throw new Error('uploadPumpMetadata: symbol is required');
+	const form = new FormData();
+	let imageBuf;
+	let imageName = 'placeholder.png';
+	let imageType = 'image/png';
+	if (imageUrl) {
+		const r = await fetch(imageUrl);
+		if (!r.ok) throw new Error(`Failed to fetch imageUrl: HTTP ${r.status}`);
+		imageBuf = Buffer.from(await r.arrayBuffer());
+		const ext = (imageUrl.split('?')[0].split('.').pop() || 'png').toLowerCase();
+		imageName = `image.${ext}`;
+		imageType = r.headers.get('content-type') || imageType;
+	} else {
+		imageBuf = Buffer.from(
+			'89504e470d0a1a0a0000000d49484452000000010000000108060000001f15c4890000000d49444154' +
+			'78da63fcffff3f0305000601018a0c1d990000000049454e44ae426082',
+			'hex',
+		);
+	}
+	form.append('file', imageBuf, { filename: imageName, contentType: imageType });
+	form.append('name', name);
+	form.append('symbol', symbol);
+	form.append('description', description);
+	form.append('twitter', twitter);
+	form.append('telegram', telegram);
+	form.append('website', website);
+	form.append('showName', String(showName));
+
+	const res = await fetch(PUMP_IPFS_URL, {
+		method: 'POST',
+		body: form,
+		headers: form.getHeaders(),
+	});
+	if (!res.ok) {
+		const txt = await res.text().catch(() => '');
+		throw new Error(`pump.fun IPFS upload failed (${res.status}): ${txt.slice(0, 300)}`);
+	}
+	const json = await res.json();
+	return {
+		uri: json.metadataUri || json.metadata_uri || null,
+		raw: json,
+	};
+}
+
+export async function atomicLaunch({
+	name,
+	symbol,
+	uri,
+	funderSecret,
+	creatorSecret,
+	mintSecret,
+	rentSol = 0.035,
+	jitoTipSol = 0.005,
+	priorityMicroLamports = 2_000_000,
+	mayhemMode = false,
+	cashback = false,
+}) {
+	if (!name) throw new Error('atomicLaunch: name is required');
+	if (!symbol) throw new Error('atomicLaunch: symbol is required');
+	if (!uri) throw new Error('atomicLaunch: uri is required (call uploadPumpMetadata first or pass an existing one)');
+
+	const funder = keypairFromSecret(funderSecret);
+	const creator = keypairFromSecret(creatorSecret);
+	const mint = mintSecret
+		? Keypair.fromSecretKey(bs58decode(mintSecret))
+		: Keypair.generate();
+
+	// pump-sdk is a CJS module — import dynamically so this file can stay ESM.
+	const pumpSdkPkg = await import('@nirholas/pump-sdk');
+	const PUMP_SDK = pumpSdkPkg.PUMP_SDK || pumpSdkPkg.default?.PUMP_SDK;
+	if (!PUMP_SDK || typeof PUMP_SDK.createV2Instruction !== 'function') {
+		throw new Error('@nirholas/pump-sdk: PUMP_SDK.createV2Instruction not found in installed version');
+	}
+
+	const conn = getConnection();
+	const funderBal = await conn.getBalance(funder.publicKey, 'confirmed');
+	const needed = (rentSol + jitoTipSol + 0.002) * LAMPORTS_PER_SOL;
+	if (funderBal < needed) {
+		const err = new Error(
+			`Funder needs >= ${(needed / LAMPORTS_PER_SOL).toFixed(4)} SOL; has ${(funderBal / LAMPORTS_PER_SOL).toFixed(4)} SOL.`,
+		);
+		err.code = 'insufficient_funds';
+		throw err;
+	}
+
+	const tipAccount = randomTipAccount();
+	const { blockhash } = await conn.getLatestBlockhash('confirmed');
+
+	const tx1Msg = new TransactionMessage({
+		payerKey: funder.publicKey,
+		recentBlockhash: blockhash,
+		instructions: [
+			ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityMicroLamports }),
+			ComputeBudgetProgram.setComputeUnitLimit({ units: 1000 }),
+			SystemProgram.transfer({ fromPubkey: funder.publicKey, toPubkey: creator.publicKey, lamports: Math.floor(rentSol * LAMPORTS_PER_SOL) }),
+			SystemProgram.transfer({ fromPubkey: funder.publicKey, toPubkey: tipAccount, lamports: Math.floor(jitoTipSol * LAMPORTS_PER_SOL) }),
+		],
+	}).compileToV0Message();
+	const tx1 = new VersionedTransaction(tx1Msg);
+	tx1.sign([funder]);
+
+	const createIx = await PUMP_SDK.createV2Instruction({
+		mint: mint.publicKey,
+		name,
+		symbol,
+		uri,
+		creator: creator.publicKey,
+		user: creator.publicKey,
+		mayhemMode,
+		cashback,
+	});
+	const tx2Msg = new TransactionMessage({
+		payerKey: creator.publicKey,
+		recentBlockhash: blockhash,
+		instructions: [
+			ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityMicroLamports }),
+			ComputeBudgetProgram.setComputeUnitLimit({ units: 300_000 }),
+			createIx,
+		],
+	}).compileToV0Message();
+	const tx2 = new VersionedTransaction(tx2Msg);
+	tx2.sign([creator, mint]);
+
+	const bundle = [bs58encode(tx1.serialize()), bs58encode(tx2.serialize())];
+	const { bundleId, explorer } = await submitBundle(bundle);
+
+	const sig1 = bs58encode(tx1.signatures[0]);
+	const sig2 = bs58encode(tx2.signatures[0]);
+	const wait = await waitForSignatures(conn, [sig1, sig2], { timeoutMs: 60_000, intervalMs: 2_000 });
+
+	return {
+		ok: wait.ok,
+		bundleId,
+		bundleExplorer: explorer,
+		mint: mint.publicKey.toBase58(),
+		mintSecret: bs58encode(mint.secretKey),
+		creator: creator.publicKey.toBase58(),
+		funder: funder.publicKey.toBase58(),
+		tx1Signature: sig1,
+		tx2Signature: sig2,
+		statuses: wait.statuses,
+		err: wait.err,
+		pumpUrl: `https://pump.fun/coin/${mint.publicKey.toBase58()}`,
+		fundingTxExplorer: `https://solscan.io/tx/${sig1}`,
+		createTxExplorer: `https://solscan.io/tx/${sig2}`,
+	};
+}

package/src/lib/avatars.js

@@ -0,0 +1,94 @@
+// Curated catalog of default avatars + accessories served from the
+// three.ws public CDN. All URLs are public and cacheable — no auth needed.
+//
+// The MCP keeps avatar sessions in-process: spawning an avatar returns a
+// session id that other tools (dress_avatar, viewer_url, render_clip) can
+// reference. Sessions don't persist across MCP restarts; for production
+// flows the client should re-call spawn_avatar.
+
+import { randomUUID } from 'node:crypto';
+
+import { THREE_WS_BASE, VIEWER_BASE } from '../config.js';
+
+export const DEFAULT_AVATARS = [
+	{
+		id: 'default',
+		name: 'three.ws default',
+		description: 'Stylized humanoid base mesh, rigged with the three.ws standard skeleton. Good starting point for any persona.',
+		glb: `${THREE_WS_BASE}/avatars/default.glb`,
+		thumbnail: null,
+	},
+	{
+		id: 'cz',
+		name: 'CZ',
+		description: 'Suited exchange-founder type with a clean rig. Drops well-known crypto vibes into your demo.',
+		glb: `${THREE_WS_BASE}/avatars/cz.glb`,
+		thumbnail: null,
+	},
+];
+
+export const ACCESSORIES = [
+	{ id: 'hat-baseball', slot: 'head', glb: `${THREE_WS_BASE}/accessories/hat-baseball.glb`, name: 'Baseball cap' },
+	{ id: 'hat-beanie', slot: 'head', glb: `${THREE_WS_BASE}/accessories/hat-beanie.glb`, name: 'Beanie' },
+	{ id: 'hat-cowboy', slot: 'head', glb: `${THREE_WS_BASE}/accessories/hat-cowboy.glb`, name: 'Cowboy hat' },
+	{ id: 'glasses-round', slot: 'face', glb: `${THREE_WS_BASE}/accessories/glasses-round.glb`, name: 'Round glasses' },
+	{ id: 'glasses-shades', slot: 'face', glb: `${THREE_WS_BASE}/accessories/glasses-shades.glb`, name: 'Shades' },
+	{ id: 'earrings-hoops', slot: 'ears', glb: `${THREE_WS_BASE}/accessories/earrings-hoops.glb`, name: 'Hoop earrings' },
+	{ id: 'earrings-studs', slot: 'ears', glb: `${THREE_WS_BASE}/accessories/earrings-studs.glb`, name: 'Stud earrings' },
+];
+
+export const POSE_PRESETS = [
+	'idle', 'wave', 'thumbs_up', 'dab', 't_pose', 'sit', 'point', 'salute', 'cheer',
+];
+
+export function findAvatar(id) {
+	return DEFAULT_AVATARS.find((a) => a.id === id) || null;
+}
+
+export function findAccessory(id) {
+	return ACCESSORIES.find((a) => a.id === id) || null;
+}
+
+// In-memory session store. Maps sessionId → { avatar, accessories[], pose,
+// voice, createdAt, lastUpdated }.
+const sessions = new Map();
+
+export function createSession({ glb, name, voice, persona, accessories = [], pose = 'idle' }) {
+	const id = randomUUID();
+	const session = {
+		id,
+		name: name || null,
+		persona: persona || null,
+		voice: voice || 'nova',
+		avatar: { glb, source: glb.startsWith(THREE_WS_BASE) ? 'three.ws' : 'external' },
+		accessories: accessories.slice(),
+		pose,
+		wallet: null,
+		createdAt: new Date().toISOString(),
+		lastUpdated: new Date().toISOString(),
+	};
+	sessions.set(id, session);
+	return session;
+}
+
+export function getSession(id) {
+	return sessions.get(id) || null;
+}
+
+export function updateSession(id, patch) {
+	const s = sessions.get(id);
+	if (!s) return null;
+	Object.assign(s, patch, { lastUpdated: new Date().toISOString() });
+	return s;
+}
+
+export function listSessions() {
+	return [...sessions.values()];
+}
+
+export function viewerUrlFor(session) {
+	const params = new URLSearchParams({ src: session.avatar.glb });
+	if (session.accessories.length) params.set('accessories', session.accessories.map((a) => a.id).join(','));
+	if (session.pose && session.pose !== 'idle') params.set('pose', session.pose);
+	return `${VIEWER_BASE}?${params.toString()}`;
+}

package/src/lib/ens-sns.js

@@ -0,0 +1,105 @@
+// ENS (Ethereum) + SNS (Solana) name resolution.
+//
+// ENS: ethers JsonRpcProvider against the configured ETH_RPC_URL, falling
+// back to ethers' default public provider rotation.
+// SNS: Bonfida's sns-api (the same service three.ws uses on the web side).
+
+import { ethers } from 'ethers';
+
+import { ETH_RPC_URL } from '../config.js';
+
+const ENS_RE = /^(?:[a-z0-9-]+\.)*[a-z0-9-]+\.eth$/i;
+const SOL_RE = /^[a-z0-9-]{1,63}(?:\.sol)?$/i;
+const SNS_API = 'https://sns-api.bonfida.com';
+
+async function withTimeout(promise, ms, label) {
+	const timeout = new Promise((_, rej) => setTimeout(() => rej(new Error(`${label} timed out after ${ms}ms`)), ms));
+	return Promise.race([promise, timeout]);
+}
+
+async function resolveEns(name) {
+	const provider = ETH_RPC_URL
+		? new ethers.JsonRpcProvider(ETH_RPC_URL)
+		: ethers.getDefaultProvider('mainnet');
+	const address = await withTimeout(provider.resolveName(name), 4000, 'ens');
+	if (!address) return null;
+	let reverseName = null;
+	try {
+		reverseName = await withTimeout(provider.lookupAddress(address), 3000, 'ens-reverse');
+	} catch {
+		// best effort
+	}
+	return { network: 'ethereum', name, address, reverseName, rpc: ETH_RPC_URL || 'ethers-default' };
+}
+
+async function resolveSns(name) {
+	const bare = name.toLowerCase().replace(/\.sol$/, '');
+	if (!/^[a-z0-9-]{1,63}$/.test(bare)) return null;
+	const lookup = await fetch(`${SNS_API}/v2/domain/lookup/${bare}.sol`).catch(() => null);
+	if (!lookup || !lookup.ok) return null;
+	const data = await lookup.json().catch(() => null);
+	const owner = data?.owner || data?.[bare + '.sol']?.owner || data?.data?.owner || null;
+	if (!owner) return null;
+
+	let allDomains = [];
+	try {
+		const r = await fetch(`${SNS_API}/v2/user/domains/${owner}`);
+		if (r.ok) {
+			const body = await r.json();
+			const list = body?.[owner] || body?.data?.[owner] || [];
+			if (Array.isArray(list)) {
+				allDomains = list
+					.map((d) => (typeof d === 'string' ? d : d?.domain || d?.name))
+					.filter(Boolean);
+			}
+		}
+	} catch {
+		// best effort
+	}
+
+	let favoriteDomain = null;
+	try {
+		const r = await fetch(`${SNS_API}/v2/user/fav-domains/${owner}`);
+		if (r.ok) {
+			const body = await r.json();
+			favoriteDomain = body?.[owner] || body?.data?.[owner] || null;
+		}
+	} catch {
+		// best effort
+	}
+
+	return {
+		network: 'solana',
+		name: `${bare}.sol`,
+		address: owner,
+		favoriteDomain,
+		allDomains,
+		source: `${SNS_API}/v2/domain/lookup/${bare}.sol`,
+	};
+}
+
+export async function resolveName(name) {
+	const trimmed = String(name || '').trim().toLowerCase();
+	const isEns = ENS_RE.test(trimmed);
+	const isSol = /\.sol$/.test(trimmed) || (!isEns && SOL_RE.test(trimmed));
+
+	const tasks = [];
+	if (isEns) tasks.push(['ens', resolveEns(trimmed).catch((e) => ({ error: e?.message || 'ens failed' }))]);
+	if (isSol) tasks.push(['sns', resolveSns(trimmed).catch((e) => ({ error: e?.message || 'sns failed' }))]);
+	if (!isEns && !isSol) {
+		return { ok: false, error: 'invalid_name', message: 'name does not look like a .eth, .sol, or bare label' };
+	}
+	const results = await Promise.all(tasks.map((t) => t[1]));
+	const out = { ok: false, input: trimmed, ens: null, sns: null };
+	tasks.forEach(([key], i) => {
+		out[key] = results[i] || null;
+	});
+	if (out.ens && !out.ens.error) out.ok = true;
+	if (out.sns && !out.sns.error) out.ok = true;
+	if (!out.ok) {
+		out.error = 'not_found';
+		out.message = 'name did not resolve in either ENS or SNS';
+	}
+	out.fetchedAt = new Date().toISOString();
+	return out;
+}

package/src/lib/glb-io.js

@@ -0,0 +1,59 @@
+// glTF / GLB I/O helpers — load a GLB from a URL or a base64 data URL into
+// a @gltf-transform/core Document, and serialize back to bytes when needed.
+//
+// The @gltf-transform NodeIO reader does the binary parsing (BIN chunk +
+// JSON chunk per the glTF 2.0 spec). We attach the Draco extension on
+// both reader + writer so already-Draco-compressed meshes round-trip
+// correctly.
+
+import { NodeIO } from '@gltf-transform/core';
+import { KHRDracoMeshCompression, ALL_EXTENSIONS } from '@gltf-transform/extensions';
+import draco3dgltf from 'draco3dgltf';
+
+let _io = null;
+
+async function buildIo() {
+	const [encoder, decoder] = await Promise.all([
+		draco3dgltf.createEncoderModule(),
+		draco3dgltf.createDecoderModule(),
+	]);
+	return new NodeIO()
+		.registerExtensions(ALL_EXTENSIONS)
+		.registerDependencies({
+			'draco3d.encoder': encoder,
+			'draco3d.decoder': decoder,
+		});
+}
+
+export async function getIo() {
+	if (!_io) _io = await buildIo();
+	return _io;
+}
+
+export async function fetchGlbBytes(url) {
+	if (url.startsWith('data:')) {
+		const comma = url.indexOf(',');
+		if (comma === -1) throw new Error('Invalid data URL');
+		const meta = url.slice(5, comma);
+		const data = url.slice(comma + 1);
+		if (meta.includes(';base64')) {
+			return Buffer.from(data, 'base64');
+		}
+		return Buffer.from(decodeURIComponent(data), 'utf8');
+	}
+	const r = await fetch(url);
+	if (!r.ok) throw new Error(`Failed to fetch ${url}: HTTP ${r.status}`);
+	return Buffer.from(await r.arrayBuffer());
+}
+
+export async function readDocument(url) {
+	const io = await getIo();
+	const bytes = await fetchGlbBytes(url);
+	const doc = await io.readBinary(bytes);
+	return { doc, bytes };
+}
+
+export async function writeBinary(doc) {
+	const io = await getIo();
+	return io.writeBinary(doc);
+}

package/src/lib/jito.js

@@ -0,0 +1,72 @@
+// Jito Block Engine helpers.
+//
+// We submit pre-signed transaction bundles to Jito's mainnet block engine.
+// A bundle of 1-5 transactions either all land in the same block or none
+// land — atomicity is what enables the launch-and-collect tricks in
+// nirholas/atomic (separate funder and creator wallets, leaked-key
+// rescues, sniper-resistant launches).
+//
+// Jito tip accounts rotate occasionally; if you start hitting
+// "Bundles must write lock at least one tip account" errors, fetch fresh
+// ones via the getTipAccounts JSON-RPC method against the block engine.
+
+import { PublicKey } from '@solana/web3.js';
+
+export const JITO_BUNDLE_URL = 'https://mainnet.block-engine.jito.wtf/api/v1/bundles';
+
+export const JITO_TIP_ACCOUNTS = [
+	'ADuUkR4vqLUMWXxW9gh6D6L8pMSawimctcNZ5pGwDcEt',
+	'HFqU5x63VTqvQss8hp11i4wVV8bD44PvwucfZ2bU7gRe',
+	'Cw8CFyM9FkoMi7K7Crf6HNQqf4uEMzpKw6QNghXLvLkY',
+	'ADaUMid9yfUytqMBgopwjb2DTLSokTSzL1zt6iGPaS49',
+	'DttWaMuVvTiduZRnguLF7jNxTgiMBZ1hyAumKUiL2KRL',
+	'96gYZGLnJYVFmbjzopPSU6QiEV5fGqZNyN9nmNhvrZU5',
+	'3AVi9Tg9Uo68tJfuvoKvqKNWKkC5wPdSSdeBnizKZ6jT',
+	'DfXygSm4jCyNCybVYYK6DwvWqjKee8pbDmJGcLWNDXjh',
+];
+
+export function randomTipAccount() {
+	return new PublicKey(JITO_TIP_ACCOUNTS[Math.floor(Math.random() * JITO_TIP_ACCOUNTS.length)]);
+}
+
+export async function submitBundle(bs58Txs) {
+	const res = await fetch(JITO_BUNDLE_URL, {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'sendBundle', params: [bs58Txs] }),
+	});
+	const body = await res.json().catch(() => ({}));
+	if (body.error) {
+		const err = new Error(`Jito bundle submit failed: ${JSON.stringify(body.error)}`);
+		err.code = 'jito_error';
+		err.detail = body.error;
+		throw err;
+	}
+	return {
+		bundleId: body.result,
+		explorer: `https://explorer.jito.wtf/bundle/${body.result}`,
+	};
+}
+
+// Poll signature statuses until all are confirmed/failed or the timeout
+// elapses. Used after submitting a Jito bundle so callers see a final
+// state instead of just the bundle id.
+export async function waitForSignatures(connection, signatures, { timeoutMs = 60_000, intervalMs = 2_000 } = {}) {
+	const deadline = Date.now() + timeoutMs;
+	while (Date.now() < deadline) {
+		const sigs = await connection.getSignatureStatuses(signatures);
+		const all = sigs?.value || [];
+		const allConfirmed = all.length === signatures.length
+			&& all.every((s) => s?.confirmationStatus === 'confirmed' || s?.confirmationStatus === 'finalized');
+		if (allConfirmed) {
+			const anyErr = all.find((s) => s?.err);
+			return {
+				ok: !anyErr,
+				err: anyErr?.err || null,
+				statuses: all.map((s) => s?.confirmationStatus || null),
+			};
+		}
+		await new Promise((r) => setTimeout(r, intervalMs));
+	}
+	return { ok: false, err: 'timeout', statuses: null };
+}

package/src/lib/jupiter-buy.js

@@ -0,0 +1,158 @@
+// Jupiter swap for any Solana SPL or pump.fun token.
+//
+// Two modes:
+//   - jupiterBuyDirect: the buyer wallet has SOL — single tx, no Jito.
+//   - jupiterBuyBundled: ported from nirholas/atomic's buy-jito.js. The
+//     funder transfers SOL to the buyer + Jito tip in Tx1, the buyer signs
+//     the Jupiter swap in Tx2, both submitted as a bundle. Use this when
+//     the buyer key is shared/leaked and you must beat sweeper bots.
+
+import {
+	PublicKey,
+	SystemProgram,
+	TransactionMessage,
+	VersionedTransaction,
+	ComputeBudgetProgram,
+	LAMPORTS_PER_SOL,
+} from '@solana/web3.js';
+
+import { bs58encode, getConnection, keypairFromSecret } from './solana.js';
+import { randomTipAccount, submitBundle, waitForSignatures } from './jito.js';
+
+const SOL_MINT = 'So11111111111111111111111111111111111111112';
+
+async function fetchJupiterQuote({ inputMint = SOL_MINT, outputMint, amount, slippageBps = 500 }) {
+	const url = `https://lite-api.jup.ag/swap/v1/quote?inputMint=${inputMint}&outputMint=${outputMint}&amount=${amount}&slippageBps=${slippageBps}`;
+	const r = await fetch(url);
+	if (!r.ok) {
+		const txt = await r.text().catch(() => '');
+		throw new Error(`Jupiter quote failed (${r.status}): ${txt.slice(0, 300)}`);
+	}
+	return r.json();
+}
+
+async function fetchJupiterSwapTx({ quoteResponse, userPublicKey, priorityMicroLamports = 2_000_000 }) {
+	const r = await fetch('https://lite-api.jup.ag/swap/v1/swap', {
+		method: 'POST',
+		headers: { 'content-type': 'application/json' },
+		body: JSON.stringify({
+			quoteResponse,
+			userPublicKey,
+			wrapAndUnwrapSol: true,
+			computeUnitPriceMicroLamports: priorityMicroLamports,
+		}),
+	});
+	if (!r.ok) {
+		const txt = await r.text().catch(() => '');
+		throw new Error(`Jupiter swap build failed (${r.status}): ${txt.slice(0, 300)}`);
+	}
+	return r.json();
+}
+
+export async function jupiterBuyDirect({ buyerSecret, targetMint, buySol = 0.01, slippageBps = 500, priorityMicroLamports = 2_000_000 }) {
+	const buyer = keypairFromSecret(buyerSecret);
+	const conn = getConnection();
+
+	const buyLamports = Math.floor(buySol * LAMPORTS_PER_SOL);
+	const quote = await fetchJupiterQuote({ outputMint: targetMint, amount: buyLamports, slippageBps });
+	const { swapTransaction } = await fetchJupiterSwapTx({
+		quoteResponse: quote,
+		userPublicKey: buyer.publicKey.toBase58(),
+		priorityMicroLamports,
+	});
+	const swapTx = VersionedTransaction.deserialize(Buffer.from(swapTransaction, 'base64'));
+	swapTx.sign([buyer]);
+
+	const sig = await conn.sendTransaction(swapTx, { maxRetries: 5 });
+	const wait = await waitForSignatures(conn, [sig], { timeoutMs: 60_000, intervalMs: 2_000 });
+
+	return {
+		ok: wait.ok,
+		signature: sig,
+		buyer: buyer.publicKey.toBase58(),
+		target: targetMint,
+		soldSol: buySol,
+		expectedOutAmount: quote.outAmount,
+		priceImpactPct: quote.priceImpactPct,
+		route: Array.isArray(quote.routePlan) ? quote.routePlan.map((r) => r.swapInfo?.label).filter(Boolean) : [],
+		statuses: wait.statuses,
+		err: wait.err,
+		explorer: `https://solscan.io/tx/${sig}`,
+	};
+}
+
+export async function jupiterBuyBundled({
+	funderSecret,
+	buyerSecret,
+	targetMint,
+	buySol = 0.01,
+	slippageBps = 500,
+	jitoTipSol = 0.005,
+	priorityMicroLamports = 2_000_000,
+}) {
+	const funder = keypairFromSecret(funderSecret);
+	const buyer = keypairFromSecret(buyerSecret);
+	const conn = getConnection();
+
+	const funderBal = await conn.getBalance(funder.publicKey, 'confirmed');
+	const needed = (buySol + 0.005 + jitoTipSol + 0.002) * LAMPORTS_PER_SOL;
+	if (funderBal < needed) {
+		const err = new Error(
+			`Funder needs >= ${(needed / LAMPORTS_PER_SOL).toFixed(4)} SOL; has ${(funderBal / LAMPORTS_PER_SOL).toFixed(4)} SOL.`,
+		);
+		err.code = 'insufficient_funds';
+		throw err;
+	}
+
+	const buyLamports = Math.floor(buySol * LAMPORTS_PER_SOL);
+	const quote = await fetchJupiterQuote({ outputMint: targetMint, amount: buyLamports, slippageBps });
+	const { swapTransaction } = await fetchJupiterSwapTx({
+		quoteResponse: quote,
+		userPublicKey: buyer.publicKey.toBase58(),
+		priorityMicroLamports,
+	});
+	const swapTx = VersionedTransaction.deserialize(Buffer.from(swapTransaction, 'base64'));
+	swapTx.sign([buyer]);
+
+	const transferToBuyer = Math.floor((buySol + 0.005) * LAMPORTS_PER_SOL);
+	const tipAccount = randomTipAccount();
+	const blockhash = swapTx.message.recentBlockhash;
+
+	const fundMsg = new TransactionMessage({
+		payerKey: funder.publicKey,
+		recentBlockhash: blockhash,
+		instructions: [
+			ComputeBudgetProgram.setComputeUnitPrice({ microLamports: priorityMicroLamports }),
+			ComputeBudgetProgram.setComputeUnitLimit({ units: 1000 }),
+			SystemProgram.transfer({ fromPubkey: funder.publicKey, toPubkey: buyer.publicKey, lamports: transferToBuyer }),
+			SystemProgram.transfer({ fromPubkey: funder.publicKey, toPubkey: tipAccount, lamports: Math.floor(jitoTipSol * LAMPORTS_PER_SOL) }),
+		],
+	}).compileToV0Message();
+	const fundTx = new VersionedTransaction(fundMsg);
+	fundTx.sign([funder]);
+
+	const bundle = [bs58encode(fundTx.serialize()), bs58encode(swapTx.serialize())];
+	const { bundleId, explorer } = await submitBundle(bundle);
+	const sig1 = bs58encode(fundTx.signatures[0]);
+	const sig2 = bs58encode(swapTx.signatures[0]);
+	const wait = await waitForSignatures(conn, [sig1, sig2], { timeoutMs: 60_000, intervalMs: 2_000 });
+
+	return {
+		ok: wait.ok,
+		bundleId,
+		bundleExplorer: explorer,
+		fundTxSignature: sig1,
+		swapTxSignature: sig2,
+		funder: funder.publicKey.toBase58(),
+		buyer: buyer.publicKey.toBase58(),
+		target: targetMint,
+		soldSol: buySol,
+		expectedOutAmount: quote.outAmount,
+		priceImpactPct: quote.priceImpactPct,
+		route: Array.isArray(quote.routePlan) ? quote.routePlan.map((r) => r.swapInfo?.label).filter(Boolean) : [],
+		statuses: wait.statuses,
+		err: wait.err,
+		fundTxExplorer: `https://solscan.io/tx/${sig1}`,
+		swapTxExplorer: `https://solscan.io/tx/${sig2}`,
+	};
+}