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 adapter for the four official @pump-fun/* SDKs.
// Lazy-loaded — Vercel cold starts pay only for what an endpoint touches.
//
// Public surface:
// getConnection({ network }) → @solana/web3.js Connection
// getPumpSdk({ network }) → { sdk, PUMP_SDK, BN, web3 }
// getPumpSdkV2({ network }) → { PUMP_SDK, onlineSdk, bondingCurvePda, isLegacyQuoteMint, BN, web3 }
// getPumpSwapSdk({ network }) → { sdk: PumpAmmSdk, BN, web3 }
// getPumpAgent({ network, mint }) → { agent: PumpAgent, BN, web3, agentPda }
// getPumpAgentOffline({ network, mint }) → instruction-only PumpAgentOffline
// getPumpTradeClient({ network }) → { client: PumpTradeClient, BN, web3 }
// verifySignature(network, sig) → confirmed parsed tx, throws on missing/failed
// solanaPubkey(s) → PublicKey or null
//
// Network selection: 'mainnet' | 'devnet'. Endpoint URLs come from env so
// production can pin Helius / Triton / etc. RPC providers. Setting
// SOLANA_RPC_FALLBACK_URLS (comma-separated) enables the multi-endpoint
// RpcFallback wrapper for read-side handlers that opt in via getRpcFallback().
import { PublicKey } from '@solana/web3.js';
import { solanaConnection } from './solana/connection.js';
import { rpcFallbackFromEnv } from './solana/rpc-fallback.js';
import { PUMP_PROGRAM_ID, PUMP_AGENT_PAYMENTS_PROGRAM_ID } from './solana/programs.js';
import { isRpcOutageError, rpcUnavailableError } from './rpc-degrade.js';
// @solana/web3.js calls console.error() on every 429 retry attempt. Those
// retries succeed (callers see a resolved value, not a thrown error), but
// Vercel captures console.error as level:error which pollutes the error log.
// Downgrade just those messages to console.warn so they stay visible as
// warnings without triggering alert thresholds.
{
const _err = console.error.bind(console);
console.error = (...args) => {
if (
typeof args[0] === 'string' &&
/Server responded with \d+ .*Retrying after/.test(args[0])
) {
console.warn(...args);
} else {
_err(...args);
}
};
}
const RPC_MAINNET = () => process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com';
const RPC_DEVNET = () => process.env.SOLANA_RPC_URL_DEVNET || 'https://api.devnet.solana.com';
export function getConnection({ network = 'mainnet', commitment = 'confirmed' } = {}) {
const url = network === 'devnet' ? RPC_DEVNET() : RPC_MAINNET();
return solanaConnection({ url: url, commitment: commitment });
}
// Returns an RpcFallback wrapper for read-only flows that benefit from
// multi-endpoint rotation. Always returns an instance — when no fallbacks are
// configured it just wraps the single primary URL with no behavior change.
export function getRpcFallback({ network = 'mainnet', commitment = 'confirmed' } = {}) {
return rpcFallbackFromEnv({ network, commitment });
}
export function solanaPubkey(s) {
if (!s) return null;
try {
return new PublicKey(s);
} catch {
return null;
}
}
export async function getPumpSdk({ network = 'mainnet' } = {}) {
const [{ PumpSdk, OnlinePumpSdk }, web3, BN] = await Promise.all([
import('@pump-fun/pump-sdk'),
import('@solana/web3.js'),
import('bn.js').then((m) => m.default || m),
]);
const connection = getConnection({ network });
// `OnlinePumpSdk` exposes the `fetch*` helpers; the instruction builders
// (`createInstruction`, `createV2AndBuyInstructions`, `buyInstructions`, …)
// live on the offline `PumpSdk`. Compose both so callers see one `sdk` with
// the full surface — required by the studio launch flow.
const offline = new PumpSdk();
const online = OnlinePumpSdk ? new OnlinePumpSdk(connection) : null;
// Compose offline + online so callers see a unified `sdk`. Offline owns the
// instruction builders (createV2Instruction, …); online owns the fetch*
// helpers. Prefer offline for any method that exists on it — the previous
// `prop in target` check resolved class-prototype methods on `online` to
// `undefined`, surfacing as "sdk.createInstruction is not a function" at
// runtime even though the method existed on `offline`.
const sdk = online
? new Proxy(online, {
get(target, prop, receiver) {
const offlineVal = offline[prop];
if (typeof offlineVal === 'function') return offlineVal.bind(offline);
if (offlineVal !== undefined) return offlineVal;
return Reflect.get(target, prop, receiver);
},
})
: offline;
return { sdk, connection, BN, web3, PumpSdk, OnlinePumpSdk, offline, online };
}
// v2 bonding curve helpers — buy_v2, sell_v2, create_v2, USDC quote support
export async function getPumpSdkV2({ network = 'mainnet' } = {}) {
const [pumpPkg, web3, BN] = await Promise.all([
import('@pump-fun/pump-sdk'),
import('@solana/web3.js'),
import('bn.js').then((m) => m.default || m),
]);
const {
PUMP_SDK,
OnlinePumpSdk,
bondingCurvePda,
isLegacyQuoteMint,
getBuyTokenAmountFromSolAmount,
getBuySolAmountFromTokenAmount,
getSellSolAmountFromTokenAmount,
newBondingCurve,
} = pumpPkg;
const connection = getConnection({ network });
const onlineSdk = new OnlinePumpSdk(connection);
return {
PUMP_SDK,
onlineSdk,
connection,
bondingCurvePda,
isLegacyQuoteMint,
getBuyTokenAmountFromSolAmount,
getBuySolAmountFromTokenAmount,
getSellSolAmountFromTokenAmount,
newBondingCurve,
BN,
web3,
};
}
export async function getPumpTradeClient({ network = 'mainnet' } = {}) {
const [{ PumpTradeClient }, web3, BN] = await Promise.all([
import('@three-ws/agent-payments'),
import('@solana/web3.js'),
import('bn.js').then((m) => m.default || m),
]);
const connection = getConnection({ network });
const client = new PumpTradeClient(connection);
return { client, connection, BN, web3 };
}
export async function getPumpSwapSdk({ network = 'mainnet' } = {}) {
const [{ PumpAmmSdk, PumpAmmAdminSdk }, web3, BN] = await Promise.all([
import('@pump-fun/pump-swap-sdk'),
import('@solana/web3.js'),
import('bn.js').then((m) => m.default || m),
]);
const connection = getConnection({ network });
const sdk = new PumpAmmSdk(connection);
const internalSdk = PumpAmmAdminSdk ? new PumpAmmAdminSdk(connection) : null;
return { sdk, internalSdk, connection, BN, web3 };
}
export async function getPumpAgent({ network = 'mainnet', mint } = {}) {
if (!mint) throw Object.assign(new Error('mint required'), { status: 400 });
const [{ PumpAgent, getTokenAgentPaymentsPDA }, web3, BN] = await Promise.all([
import('@three-ws/agent-payments'),
import('@solana/web3.js'),
import('bn.js').then((m) => m.default || m),
]);
const connection = getConnection({ network });
const mintPk = mint instanceof PublicKey ? mint : new PublicKey(mint);
// Constructor is (mint, environment, connection) — the environment argument
// sits BETWEEN the two. Passing the connection second leaves this.connection
// undefined and every online read throws "Connection is required".
const agent = new PumpAgent(mintPk, network === 'devnet' ? 'devnet' : 'mainnet', connection);
const [agentPda] = getTokenAgentPaymentsPDA ? getTokenAgentPaymentsPDA(mintPk) : [null];
return { agent, connection, BN, web3, agentPda };
}
export async function getPumpAgentOffline({ network = 'mainnet', mint } = {}) {
if (!mint) throw Object.assign(new Error('mint required'), { status: 400 });
const [{ PumpAgentOffline, getTokenAgentPaymentsPDA, getInvoiceIdPDA }, web3, BN] =
await Promise.all([
import('@three-ws/agent-payments'),
import('@solana/web3.js'),
import('bn.js').then((m) => m.default || m),
]);
const mintPk = mint instanceof PublicKey ? mint : new PublicKey(mint);
const offline = PumpAgentOffline.load
? PumpAgentOffline.load(mintPk, getConnection({ network }))
: new PumpAgentOffline(mintPk);
const [agentPda] = getTokenAgentPaymentsPDA ? getTokenAgentPaymentsPDA(mintPk) : [null];
return { offline, getInvoiceIdPDA, BN, web3, agentPda };
}
// Confirm a signature on-chain. Returns the parsed tx (versioned-aware).
// Throws { status: 422, code } on failure so handlers can `try/catch`.
export async function verifySignature({ network, signature }) {
const connection = getConnection({ network });
let tx;
try {
tx = await connection.getParsedTransaction(signature, {
maxSupportedTransactionVersion: 1,
commitment: 'confirmed',
});
} catch {
const e = new Error('transaction not found');
e.status = 422;
e.code = 'tx_not_found';
throw e;
}
if (!tx) {
const e = new Error('transaction not found');
e.status = 422;
e.code = 'tx_not_found';
throw e;
}
if (tx.meta?.err) {
const e = new Error('transaction failed on-chain');
e.status = 422;
e.code = 'tx_failed';
throw e;
}
return tx;
}
// Collect every program id invoked by a parsed transaction — both top-level
// instructions and the CPIs recorded in `meta.innerInstructions`. Works for the
// `getParsedTransaction` shape, where each instruction (parsed or partially
// decoded) carries a `programId` that is a PublicKey or a base58 string.
export function txProgramIds(tx) {
const ids = new Set();
const add = (ix) => {
const pid = ix?.programId;
if (!pid) return;
ids.add(typeof pid === 'string' ? pid : pid.toString());
};
for (const ix of tx?.transaction?.message?.instructions || []) add(ix);
for (const group of tx?.meta?.innerInstructions || []) {
for (const ix of group?.instructions || []) add(ix);
}
return ids;
}
// True when a confirmed tx actually invoked the pump.fun bonding-curve program.
// launch-confirm uses this so a tx that merely *references* the new mint pubkey
// (e.g. a memo/transfer touching that account) can never be recorded in
// pump_agent_mints as a real launch — the program must have run. Future-proof by
// design: it asserts the program, not a specific create-instruction
// discriminator, so a new create variant keeps confirming cleanly.
export function txInvokesPumpProgram(tx) {
return txProgramIds(tx).has(PUMP_PROGRAM_ID);
}
// True when a confirmed tx actually invoked the three.ws agent-payments program.
// withdraw-confirm uses this for the same reason launch-confirm asserts the
// bonding-curve program: a succeeded tx that merely *lists* the agent mint and
// its authority among its accounts (any transfer or memo touching them does)
// would otherwise be reported back as a confirmed payout.
export function txInvokesAgentPaymentsProgram(tx) {
return txProgramIds(tx).has(PUMP_AGENT_PAYMENTS_PROGRAM_ID);
}
// Resolve the canonical pump.fun AMM pool for `mint` (post-graduation). Pass
// `quoteMint` for USDC-paired coins — derives the PDA with the explicit quote
// mint instead of the default WSOL PDA. Omit (or pass null) for SOL-paired coins.
// return everything `buyQuoteInput` / `sellBaseInput` need to price a swap.
// Quote currency is WSOL on the canonical pool.
//
// Returns BOTH `quoteReserve` (raw vault balance) and `effectiveQuoteReserve`
// (raw + virtual). See the note at the reserve decode below for which to use.
//
// Throws { status: 404, code: 'pool_not_found' } if no pool exists yet.
export async function getAmmPoolState({ network = 'mainnet', mint, quoteMint = null } = {}) {
if (!mint) throw Object.assign(new Error('mint required'), { status: 400 });
const [{ canonicalPumpPoolPda, OnlinePumpAmmSdk, PumpAmmSdk }, web3, BN, spl] =
await Promise.all([
import('@pump-fun/pump-swap-sdk'),
import('@solana/web3.js'),
import('bn.js').then((m) => m.default || m),
import('@solana/spl-token'),
]);
const connection = getConnection({ network });
const mintPk = mint instanceof PublicKey ? mint : new PublicKey(mint);
const quoteMintPk =
quoteMint instanceof PublicKey ? quoteMint : quoteMint ? new PublicKey(quoteMint) : null;
const poolKey = quoteMintPk
? canonicalPumpPoolPda(mintPk, quoteMintPk)
: canonicalPumpPoolPda(mintPk);
const online = new OnlinePumpAmmSdk(connection);
let pool;
try {
pool = await online.fetchPool(poolKey);
} catch {
const e = new Error('pump.fun AMM pool not found for mint');
e.status = 404;
e.code = 'pool_not_found';
throw e;
}
let baseAccInfo, quoteAccInfo, baseMintInfo;
try {
[baseAccInfo, quoteAccInfo, baseMintInfo] = await Promise.all([
connection.getAccountInfo(pool.poolBaseTokenAccount),
connection.getAccountInfo(pool.poolQuoteTokenAccount),
connection.getAccountInfo(pool.baseMint),
]);
} catch (err) {
// A dead RPC lane is retryable and says nothing about the pool.
if (isRpcOutageError(err)) throw rpcUnavailableError('pool reserves could not be read: Solana RPC is temporarily unavailable', err);
throw err;
}
if (!baseAccInfo || !quoteAccInfo || !baseMintInfo) {
const e = new Error('pool token accounts unavailable');
e.status = 502;
e.code = 'pool_accounts_missing';
throw e;
}
const baseAcc = spl.AccountLayout.decode(baseAccInfo.data);
const quoteAcc = spl.AccountLayout.decode(quoteAccInfo.data);
const baseMintAccount = spl.MintLayout.decode(baseMintInfo.data);
const baseReserve = new BN(baseAcc.amount.toString());
const quoteReserve = new BN(quoteAcc.amount.toString());
// PumpSwap prices against EFFECTIVE quote reserves, not the raw vault balance:
// effective = quote_vault_balance + pool.virtual_quote_reserves
// The field shipped 2026-07-15 at 0 on every pool and went non-zero on
// 2026-07-20. Per the IDL it stays 0 on non-boost pools, where effective ==
// raw and quotes are unchanged. The base side is untouched by all of this.
//
// It is an i128, so it is SIGNED: effective can be LOWER than the raw vault
// balance. Anchor decodes it to a signed BN and BN.add handles that, so the
// arithmetic below is correct as written. Do not "fix" it by clamping to 0
// or by re-reading the bytes unsigned; an unsigned read flips a negative
// into a huge positive that reads as near-infinite depth.
//
// Two consumers, two different values — do not mix them up:
// · SDK quote fns (buyQuoteInput/sellBaseInput) take `virtualQuoteReserves`
// as its OWN argument and add it internally. Pass the raw `quoteReserve`
// alongside it; passing an already-summed reserve double-counts.
// · Our own spot-price / price-impact math takes `effectiveQuoteReserve`.
// A pool decoded by an SDK older than 1.19.0 has no field; default to 0 so
// this stays correct rather than NaN.
const virtualQuoteReserves = new BN((pool.virtualQuoteReserves ?? 0).toString());
const effectiveQuoteReserve = quoteReserve.add(virtualQuoteReserves);
const offline = new PumpAmmSdk();
let globalConfigInfo, feeConfigInfo;
try {
[globalConfigInfo, feeConfigInfo] = await Promise.all([
connection.getAccountInfo((await import('@pump-fun/pump-swap-sdk')).GLOBAL_CONFIG_PDA),
connection.getAccountInfo(
(await import('@pump-fun/pump-swap-sdk')).PUMP_AMM_FEE_CONFIG_PDA,
),
]);
} catch (err) {
if (isRpcOutageError(err)) throw rpcUnavailableError('pool fee config could not be read: Solana RPC is temporarily unavailable', err);
throw err;
}
const globalConfig = globalConfigInfo ? offline.decodeGlobalConfig(globalConfigInfo) : null;
const feeConfig = feeConfigInfo ? offline.decodeFeeConfig(feeConfigInfo) : null;
return {
connection,
poolKey,
pool,
baseReserve,
quoteReserve,
virtualQuoteReserves,
effectiveQuoteReserve,
baseMintAccount,
globalConfig,
feeConfig,
BN,
web3,
};
}
// Build a versioned tx from a list of instructions, return base64 (unsigned).
// Mirrors the pattern used in api/agents/solana-register-prep.js so frontends
// can decode via VersionedTransaction.deserialize and submit via injected wallet.
export async function buildUnsignedTxBase64({ network, payer, instructions }) {
const [{ TransactionMessage, VersionedTransaction, PublicKey: PK }] = await Promise.all([
import('@solana/web3.js'),
]);
const connection = getConnection({ network });
let blockhash;
try {
({ blockhash } = await connection.getLatestBlockhash('confirmed'));
} catch (err) {
if (isRpcOutageError(err)) throw rpcUnavailableError('could not fetch a recent blockhash: Solana RPC is temporarily unavailable', err);
throw err;
}
const payerPk = payer instanceof PK ? payer : new PK(payer);
const msg = new TransactionMessage({
payerKey: payerPk,
recentBlockhash: blockhash,
instructions,
}).compileToV0Message();
const vtx = new VersionedTransaction(msg);
return Buffer.from(vtx.serialize()).toString('base64');
}