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 Jupiter (lite-api) swap client for the $THREE token lanes.
//
// The programmatic buyback (buyback.js) and the x402 micro-buy loop (microbuy.js)
// both market-buy $THREE on Jupiter. This module is the ONE place that talks to
// the Jupiter quote + swap API so the two lanes can never drift on endpoint, error
// handling, or transaction-build options. It builds nothing on-chain and holds no
// keys — callers own signing, broadcasting, and confirmation.
//
// BUY-ONLY by construction: nothing here sells $THREE. Every helper is a generic
// (inputMint → outputMint) swap primitive; the $THREE lanes only ever call it with
// outputMint = $THREE, and there is no sell path anywhere in the token/ tree.
//
// Beyond the swap lane, this module also wraps the rest of Jupiter's keyless
// lite tier (read-only token intelligence, verified live 2026-08-06):
// - /tokens/v2/search: rich per-mint info (price, mcap, liquidity, holderCount,
// audit flags, launchpad). Jupiter serves no dedicated holders endpoint
// (/ultra/v1/holders 404s); holderCount here is the keyless holder signal.
// - /tokens/v2/{toptrending|toptraded|toporganicscore}/{interval}: ranked
// discovery lists.
// - /tokens/v2/recent: latest mints seen by Jupiter (fixed 30-row page;
// upstream ignores a limit param, so trimming happens client-side).
// - /ultra/v1/shield: per-mint safety warnings.
import { fetchUpstream } from '../upstream-fetch.js';
import { withRetry } from '../resilience.js';
// Deadlines per lane. A quote is a cheap GET that Jupiter answers in well under
// a second, so 8s is generous; a swap build has to assemble a route and a
// versioned transaction and legitimately takes longer under load.
const JUP_QUOTE_TIMEOUT_MS = 8_000;
const JUP_SWAP_TIMEOUT_MS = 15_000;
const JUP_QUOTE_ATTEMPTS = 3;
const JUP_QUOTE_URL = 'https://lite-api.jup.ag/swap/v1/quote';
const JUP_SWAP_URL = 'https://lite-api.jup.ag/swap/v1/swap';
const JUP_LABELS_URL = 'https://lite-api.jup.ag/swap/v1/program-id-to-label';
const JUP_TOKENS_URL = 'https://lite-api.jup.ag/tokens/v2';
const JUP_SHIELD_URL = 'https://lite-api.jup.ag/ultra/v1/shield';
// The category lists /tokens/v2 actually serves. A wrong category is not a
// 404 upstream (it 200s with junk), so it is validated here instead.
export const JUP_TOKEN_CATEGORIES = ['toporganicscore', 'toptraded', 'toptrending'];
export const JUP_TOKEN_INTERVALS = ['5m', '1h', '6h', '24h'];
/**
* GET a Jupiter route + throw a coded error on a non-2xx / unparseable response,
* so a caller records the precise reason instead of an opaque failure.
*/
export async function fetchJson(url, opts, { timeoutMs = JUP_QUOTE_TIMEOUT_MS, attempts = 2 } = {}) {
// Bounded by default (a caller signal still composes with the timeout) and
// retried on a transient failure. Jupiter is the only provider on the
// quote/swap path, so a hang here used to hang every paid swap.
const r = await fetchUpstream(url, opts || {}, {
name: 'jupiter',
timeoutMs,
attempts,
okWhen: (res) => res.ok || (res.status < 500 && res.status !== 429),
}).catch((err) => {
throw Object.assign(new Error(`jupiter ${err?.status || 'unreachable'}: ${err?.message || 'network error'}`), {
code: 'jupiter_error',
status: err?.status || 503,
});
});
const body = await r.json().catch(() => ({}));
if (!r.ok) {
throw Object.assign(new Error(`jupiter ${r.status}: ${JSON.stringify(body).slice(0, 200)}`), {
code: 'jupiter_error',
status: r.status,
});
}
return body;
}
/**
* ExactIn quote: how much `outputMint` a given `amount` of `inputMint` buys.
* `dexes` restricts routing to one or more venue labels (the labels the
* router itself reports in a quote's routePlan), `excludeDexes` removes venues
* from routing, and `onlyDirectRoutes` forbids multi-hop routes: together they
* price a pair on one venue at a time, which is what a cross-venue comparison
* needs.
* @param {{ inputMint: string, outputMint: string, amount: bigint|number|string, slippageBps: number, dexes?: string[]|null, excludeDexes?: string[]|null, onlyDirectRoutes?: boolean }} args
* @returns {Promise<object>} the raw Jupiter quoteResponse
*/
export async function jupiterQuote({ inputMint, outputMint, amount, slippageBps, dexes = null, excludeDexes = null, onlyDirectRoutes = false }) {
const u = new URL(JUP_QUOTE_URL);
u.searchParams.set('inputMint', inputMint);
u.searchParams.set('outputMint', outputMint);
u.searchParams.set('amount', String(amount));
u.searchParams.set('slippageBps', String(slippageBps));
u.searchParams.set('swapMode', 'ExactIn');
if (Array.isArray(dexes) && dexes.length) u.searchParams.set('dexes', dexes.join(','));
if (Array.isArray(excludeDexes) && excludeDexes.length) u.searchParams.set('excludeDexes', excludeDexes.join(','));
if (onlyDirectRoutes) u.searchParams.set('onlyDirectRoutes', 'true');
// A quote is an idempotent GET: retry it through the transient statuses
// (429/5xx/network) so one rate-limited response never fails a paid swap.
return fetchJson(u.toString(), { headers: { accept: 'application/json' } }, {
timeoutMs: JUP_QUOTE_TIMEOUT_MS,
attempts: JUP_QUOTE_ATTEMPTS,
});
}
// A swap build is a POST, but it only returns an UNSIGNED transaction: nothing
// is submitted on-chain by it, so repeating it is safe. It is still retried
// exactly once and only when the failure says nothing about the request
// itself (a network error, a timeout, a 5xx). A 4xx or a 429 is an answer and
// is surfaced as-is. The signed transaction is broadcast by the caller, and
// that step is never retried here.
function isSwapBuildRetryable(err) {
return err?.code === 'jupiter_error' && Number(err.status) >= 500;
}
/**
* Build the (unsigned) swap transaction (base64) for a quote. The caller
* deserializes, signs, broadcasts, and confirms it.
* @param {{ quote: object, userPublicKey: string, wrapAndUnwrapSol?: boolean, maxPriorityLamports?: number, priorityLevel?: string }} args
* @returns {Promise<string>} base64 VersionedTransaction bytes
*/
export async function jupiterSwapTx({
quote,
userPublicKey,
wrapAndUnwrapSol = false,
maxPriorityLamports = 1_000_000,
priorityLevel = 'medium',
}) {
const body = JSON.stringify({
quoteResponse: quote,
userPublicKey,
// USDC→$THREE never touches wrapped SOL; let Jupiter manage the $THREE ATA.
wrapAndUnwrapSol,
dynamicComputeUnitLimit: true,
prioritizationFeeLamports: {
priorityLevelWithMaxLamports: { maxLamports: maxPriorityLamports, priorityLevel },
},
});
const data = await withRetry(
() => fetchJson(JUP_SWAP_URL, {
method: 'POST',
headers: { 'content-type': 'application/json', accept: 'application/json' },
body,
}, { timeoutMs: JUP_SWAP_TIMEOUT_MS, attempts: 1 }),
{ attempts: 2, shouldRetry: isSwapBuildRetryable },
);
if (!data.swapTransaction) {
throw Object.assign(new Error('jupiter returned no swapTransaction'), { code: 'no_swap_tx' });
}
return data.swapTransaction;
}
/**
* Search tokens by symbol, name, or mint address. A mint query returns that
* token's full record: usdPrice, mcap, liquidity, holderCount, launchpad,
* audit flags, and per-window stats.
* @param {string} query symbol, name, or mint address
* @param {{ limit?: number, signal?: AbortSignal }} [opts] upstream caps at 100;
* pass a signal to bound the call from a latency-sensitive path (an OG card,
* a request handler), which otherwise waits on the platform default.
* @returns {Promise<Array<object>>} raw Jupiter token records
*/
export async function jupiterTokenSearch(query, { limit, signal } = {}) {
if (!query) {
throw Object.assign(new Error('jupiterTokenSearch requires a query'), { code: 'bad_query' });
}
const u = new URL(`${JUP_TOKENS_URL}/search`);
u.searchParams.set('query', String(query));
if (limit) u.searchParams.set('limit', String(limit));
const data = await fetchJson(u.toString(), { headers: { accept: 'application/json' }, signal });
return Array.isArray(data) ? data : [];
}
/**
* Every venue the router can route through, as { programId: label }. The
* labels are what quote routePlans report and what `dexes` / `excludeDexes`
* accept, so callers resolve a venue from its program id at runtime instead of
* hardcoding names.
* @returns {Promise<Record<string, string>>}
*/
export async function jupiterVenueLabels() {
const data = await fetchJson(JUP_LABELS_URL, { headers: { accept: 'application/json' } });
return data && typeof data === 'object' && !Array.isArray(data) ? data : {};
}
/**
* Ranked token discovery list: top trending, top traded, or top organic-score
* tokens over an interval.
* @param {string} category one of JUP_TOKEN_CATEGORIES
* @param {string} [interval] one of JUP_TOKEN_INTERVALS (default '24h')
* @param {{ limit?: number }} [opts] upstream caps at 100
* @returns {Promise<Array<object>>} raw Jupiter token records
*/
export async function jupiterTokenList(category, interval = '24h', { limit } = {}) {
if (!JUP_TOKEN_CATEGORIES.includes(category)) {
throw Object.assign(
new Error(`jupiterTokenList category must be one of ${JUP_TOKEN_CATEGORIES.join(', ')}`),
{ code: 'bad_category' },
);
}
if (!JUP_TOKEN_INTERVALS.includes(interval)) {
throw Object.assign(
new Error(`jupiterTokenList interval must be one of ${JUP_TOKEN_INTERVALS.join(', ')}`),
{ code: 'bad_interval' },
);
}
const u = new URL(`${JUP_TOKENS_URL}/${category}/${interval}`);
if (limit) u.searchParams.set('limit', String(limit));
const data = await fetchJson(u.toString(), { headers: { accept: 'application/json' } });
return Array.isArray(data) ? data : [];
}
/**
* The most recent mints Jupiter has seen. Upstream ignores a limit param and
* always returns its fixed page, so the cap is applied client-side.
* @param {{ limit?: number }} [opts]
* @returns {Promise<Array<object>>} raw Jupiter token records, newest first
*/
export async function jupiterRecentTokens({ limit } = {}) {
const data = await fetchJson(`${JUP_TOKENS_URL}/recent`, {
headers: { accept: 'application/json' },
});
const rows = Array.isArray(data) ? data : [];
return limit > 0 ? rows.slice(0, limit) : rows;
}
// Shield answers at most 30 mints per request and silently drops the rest
// (verified live 2026-08-06: 60 unique mints in, warnings for exactly the
// first 30 out), so jupiterShield chunks larger lists itself.
const JUP_SHIELD_BATCH = 30;
/**
* Jupiter Shield safety warnings per mint (freeze/mint authority, unverified
* status, rug signals, ...). An empty array for a mint means Shield has
* nothing to flag. Mints are deduped and fetched in batches of 30 so callers
* never hit the upstream truncation.
* @param {Array<string>|string} mints
* @returns {Promise<Record<string, Array<object>>>} mint -> warnings
*/
export async function jupiterShield(mints) {
const list = [...new Set((Array.isArray(mints) ? mints : [mints]).filter(Boolean).map(String))];
if (!list.length) {
throw Object.assign(new Error('jupiterShield requires at least one mint'), {
code: 'bad_mints',
});
}
const batches = [];
for (let i = 0; i < list.length; i += JUP_SHIELD_BATCH) {
batches.push(list.slice(i, i + JUP_SHIELD_BATCH));
}
const results = await Promise.all(
batches.map((batch) => {
const u = new URL(JUP_SHIELD_URL);
u.searchParams.set('mints', batch.join(','));
return fetchJson(u.toString(), { headers: { accept: 'application/json' } });
}),
);
const warnings = {};
for (const data of results) {
if (data && typeof data.warnings === 'object' && data.warnings !== null) {
Object.assign(warnings, data.warnings);
}
}
return warnings;
}