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
// Keyless on-chain OHLCV source for the Granite Oracle, backed by the public
// GeckoTerminal API (https://www.geckoterminal.com/dex-api). No API key, real
// candles, deep history (up to 1000 points): enough to fill the >=512-point
// context window the Granite TimeSeries forecaster requires.
//
// GeckoTerminal is the first rung, never the only one. Every exported read has
// a second source and a last-good tier behind it:
// - fetchOhlcv: GeckoTerminal -> Birdeye pair OHLCV (keyed, same pool
// address) -> CEX klines for majors (close-only, flagged)
// - topPoolForToken: GeckoTerminal -> DexScreener deepest pair -> Birdeye markets
// - trendingPools: GeckoTerminal, then the last good board
// A value that was served live once is remembered in the shared cache
// (cacheWrapLastGood) so a GeckoTerminal outage answers with the previous
// candles rather than a 502. Nothing here fabricates a candle: when every rung
// fails and nothing is cached, the real upstream status is thrown.
import { createCache } from '../mem-cache.js';
import { cacheWrapLastGood } from '../cache.js';
import { fetchUpstream } from '../upstream-fetch.js';
import { fetchFirstOrNull } from '../../../src/shared/failover-fetch.js';
import { cexCandleProviders } from '../cex-public.js';
const BASE = 'https://api.geckoterminal.com/api/v2';
const BIRDEYE_BASE = 'https://public-api.birdeye.so';
const DEXSCREENER_TOKENS = 'https://api.dexscreener.com/latest/dex/tokens';
const DEXSCREENER_PAIRS = 'https://api.dexscreener.com/latest/dex/pairs';
const UA = 'three.ws-granite-oracle/1.0';
// Small in-memory cache: GeckoTerminal's free tier is ~30 req/min and candle
// data only changes once per bar, so a short TTL keeps us well under the cap.
const cache = createCache({ max: 256 }); // url -> { value, expiresAt }
const TTL_MS = 20_000;
// Shared-cache windows for the last-good tier. The fresh TTL mirrors the
// in-memory one; the stale window is how long an outage can be ridden out.
const LKG_FRESH_S = 20;
const LKG_STALE_S = 24 * 3600;
const POOL_FRESH_S = 300;
const TRENDING_FRESH_S = 60;
// Bounded retries for transient upstream throttling. GeckoTerminal's free tier
// bursts into 429s and occasional 5xx; the shared upstream fetch applies
// jittered backoff and honours Retry-After. 404 and other client errors are
// NOT retried.
const MAX_ATTEMPTS = 3;
// DexScreener chain slug for a GeckoTerminal network id. The two disagree on
// four of the eight networks served here, and an identity fallback quietly
// asked DexScreener for chain "polygon_pos" (which it has never heard of), so
// every rung-2 lookup on those chains missed rather than failing loudly.
const DEX_CHAIN_BY_NETWORK = {
solana: 'solana',
eth: 'ethereum',
base: 'base',
bsc: 'bsc',
polygon_pos: 'polygon',
arbitrum: 'arbitrum',
optimism: 'optimism',
avax: 'avalanche',
};
const num = (v) => {
const n = Number(v);
return Number.isFinite(n) ? n : null;
};
// Normalise an upstream failure to the status ladder callers branch on: 404
// (unknown token/pool) and 429 (throttled) pass through, everything else is a
// 502 so the route answers "upstream trouble", never a generic 500.
function tagged(message, status) {
const s = status === 404 ? 404 : status === 429 ? 429 : status === 400 ? 400 : 502;
return Object.assign(new Error(message), { status: s });
}
async function gecko(path) {
const url = `${BASE}${path}`;
const now = Date.now();
const hit = cache.get(url);
if (hit && hit.expiresAt > now) return hit.value;
let res;
try {
res = await fetchUpstream(
url,
{ headers: { accept: 'application/json', 'user-agent': UA } },
{ timeoutMs: 12_000, attempts: MAX_ATTEMPTS, label: 'GeckoTerminal' },
);
} catch (e) {
const status = e?.status;
if (typeof status === 'number' && status !== 503) {
throw tagged(`GeckoTerminal ${status}: ${String(e.body || e.message || '').slice(0, 160)}`, status);
}
throw tagged(`GeckoTerminal unreachable: ${e?.message || e}`, 502);
}
const text = await res.text();
let json;
try {
json = JSON.parse(text);
} catch {
throw tagged('GeckoTerminal returned non-JSON', 502);
}
cache.set(url, { value: json, expiresAt: now + TTL_MS });
return json;
}
// Strip GeckoTerminal's "network_" id prefix (e.g. "solana_<addr>" -> "<addr>").
function bareId(id) {
if (typeof id !== 'string') return '';
const i = id.indexOf('_');
return i >= 0 ? id.slice(i + 1) : id;
}
// pandas-style cadence string the forecast API expects, from a GeckoTerminal
// timeframe + aggregate (e.g. hour/1 -> "1h", minute/15 -> "15min", day/1 -> "1D").
export function freqFor(timeframe, aggregate = 1) {
const n = Math.max(1, Number(aggregate) || 1);
if (timeframe === 'minute') return `${n}min`;
if (timeframe === 'day') return `${n}D`;
return `${n}h`; // hour
}
// Seconds per bar for a timeframe + aggregate.
export function barSeconds(timeframe, aggregate = 1) {
const n = Math.max(1, Number(aggregate) || 1);
if (timeframe === 'minute') return 60 * n;
if (timeframe === 'day') return 86_400 * n;
return 3_600 * n;
}
// Birdeye OHLCV `type` for a timeframe + aggregate, or null when Birdeye has no
// matching bar (the rung is skipped rather than answering with the wrong cadence).
export function birdeyeTypeFor(timeframe, aggregate = 1) {
const n = Math.max(1, Number(aggregate) || 1);
const table = {
minute: { 1: '1m', 3: '3m', 5: '5m', 15: '15m', 30: '30m' },
hour: { 1: '1H', 2: '2H', 4: '4H', 6: '6H', 8: '8H', 12: '12H' },
day: { 1: '1D', 3: '3D', 7: '1W' },
};
return table[timeframe]?.[n] ?? null;
}
// Chart window (days) a CEX kline request must cover to hold `limit` bars of
// this cadence, snapped to the windows cex-public.js can serve in one call.
function cexDaysFor(timeframe, aggregate, limit) {
const spanDays = (barSeconds(timeframe, aggregate) * Math.max(1, limit)) / 86_400;
for (const d of [1, 7, 30, 90, 365]) if (spanDays <= d) return d;
return 365;
}
// Rung 2 for topPoolForToken: DexScreener's deepest pair for the token. Pair
// addresses are the on-chain AMM pool accounts, the same ids GeckoTerminal uses.
function dexscreenerPoolProvider(mint, network) {
const chain = DEX_CHAIN_BY_NETWORK[network] || network;
return {
name: 'dexscreener-pool',
url: `${DEXSCREENER_TOKENS}/${encodeURIComponent(mint)}`,
parse: async (r) => {
const data = await r.json();
const pairs = (Array.isArray(data?.pairs) ? data.pairs : []).filter(
(p) => p?.pairAddress && (p.chainId === chain || !p.chainId),
);
if (!pairs.length) return null;
pairs.sort((a, b) => (b.liquidity?.usd ?? 0) - (a.liquidity?.usd ?? 0));
return pairs[0].pairAddress;
},
};
}
// Rung 3 for topPoolForToken: Birdeye's market list for the token (keyed).
function birdeyePoolProvider(mint, network) {
const key = process.env.BIRDEYE_API_KEY;
if (!key || network !== 'solana') return null;
return {
name: 'birdeye-markets',
url: `${BIRDEYE_BASE}/defi/v2/markets?address=${encodeURIComponent(mint)}&sort_by=liquidity&sort_type=desc&offset=0&limit=1`,
init: { headers: { 'X-API-KEY': key, 'x-chain': 'solana', accept: 'application/json' } },
parse: async (r) => {
const data = await r.json();
const item = data?.data?.items?.[0];
return item?.address || null;
},
};
}
async function topPoolLive(mint, network) {
let geckoErr = null;
try {
const json = await gecko(`/networks/${network}/tokens/${mint}/pools?page=1`);
const pool = json?.data?.[0];
if (pool) return pool.attributes?.address || bareId(pool.id);
geckoErr = tagged(`no pools found for token ${mint}`, 404);
} catch (e) {
geckoErr = e;
}
// GeckoTerminal does not know the token, or is down: ask the keyless
// DexScreener index, then Birdeye. A miss everywhere keeps GeckoTerminal's
// verdict (404 = genuinely no market) so the route's empty state still fires.
const providers = [dexscreenerPoolProvider(mint, network), birdeyePoolProvider(mint, network)].filter(Boolean);
const pool = await fetchFirstOrNull(providers, { timeoutMs: 6000, label: `top-pool:${mint}` });
if (pool) return pool;
throw geckoErr;
}
// Top (most-liquid) pool for a token mint. Returns the pool address.
export async function topPoolForToken(mint, network = 'solana') {
return cacheWrapLastGood(
`ohlcv:toppool:v1:${network}:${mint}`,
POOL_FRESH_S,
() => topPoolLive(mint, network),
{ staleTtlSeconds: LKG_STALE_S },
);
}
// ── The inverse lookup: pool address -> the token that pool trades ───────────
//
// Every rung above answers "where does this token trade". This one answers the
// question a partner surface asks instead: a chart terminal names a market by
// its PAIR address, not by a mint, so a link or an embed arriving from one
// carries the pool and nothing else. Resolving it here means an embed can be
// keyed by whatever identifier the host page already has.
const tokenRef = (address, meta = {}) =>
address ? { address, name: meta.name || null, symbol: meta.symbol || null } : null;
// Rung 2: DexScreener's own record for the pair. It carries base and quote
// token metadata inline, so it answers the whole shape in one call.
function dexscreenerPairProvider(pool, network) {
const chain = DEX_CHAIN_BY_NETWORK[network];
if (!chain) return null;
return {
name: 'dexscreener-pair',
url: `${DEXSCREENER_PAIRS}/${chain}/${encodeURIComponent(pool)}`,
parse: async (r) => {
const data = await r.json();
const pair = (Array.isArray(data?.pairs) ? data.pairs : [])[0] || data?.pair || null;
if (!pair?.baseToken?.address) return null;
return {
pool: pair.pairAddress || pool,
token: tokenRef(pair.baseToken.address, pair.baseToken),
quote: tokenRef(pair.quoteToken?.address, pair.quoteToken || {}),
dex: pair.dexId || null,
pairName:
pair.baseToken.symbol && pair.quoteToken?.symbol
? `${pair.baseToken.symbol} / ${pair.quoteToken.symbol}`
: null,
};
},
};
}
async function tokenForPoolLive(pool, network) {
let geckoErr = null;
try {
// include= is what carries the token names and symbols; without it the
// relationships hold ids only and the caller would have to re-fetch both.
const json = await gecko(`/networks/${network}/pools/${pool}?include=base_token,quote_token`);
const d = json?.data;
const baseId = d?.relationships?.base_token?.data?.id;
const address = bareId(baseId);
if (address) {
const included = new Map((json.included || []).map((i) => [i.id, i.attributes || {}]));
const quoteId = d.relationships?.quote_token?.data?.id;
return {
pool: d.attributes?.address || bareId(d.id),
token: tokenRef(address, included.get(baseId) || {}),
quote: tokenRef(bareId(quoteId), included.get(quoteId) || {}),
// The dex id is NOT network-prefixed ("raydium", "pumpswap"), so it
// must not go through bareId(): that would cut "pump_fun" to "fun".
dex: d.relationships?.dex?.data?.id || null,
pairName: d.attributes?.name || null,
};
}
geckoErr = tagged(`no base token for pool ${pool}`, 404);
} catch (e) {
geckoErr = e;
}
// GeckoTerminal has not indexed the pool, or is down. A young pump.fun pair
// is exactly this case, and it is the case a partner embed hits most.
const provider = dexscreenerPairProvider(pool, network);
const hit = provider
? await fetchFirstOrNull([provider], { timeoutMs: 6000, label: `pool-token:${pool}` })
: null;
if (hit) return hit;
throw geckoErr;
}
/**
* The token a pool trades, from its pool (pair) address.
*
* @param {string} pool On-chain pool/pair account address.
* @param {string} network GeckoTerminal network id.
* @returns {Promise<{ pool: string, token: {address,name,symbol}, quote: object|null, dex: string|null, pairName: string|null }>}
* @throws {Error & { status: number }} 404 when no source knows the pool.
*/
export async function tokenForPool(pool, network = 'solana') {
return cacheWrapLastGood(
`ohlcv:pooltoken:v1:${network}:${pool}`,
POOL_FRESH_S,
() => tokenForPoolLive(pool, network),
{ staleTtlSeconds: LKG_STALE_S },
);
}
function normalizeTrending(json, limit) {
return (json?.data || []).slice(0, limit).map((p) => {
const a = p.attributes || {};
return {
pool: a.address || bareId(p.id),
name: a.name || 'Unknown',
baseMint: bareId(p.relationships?.base_token?.data?.id),
priceUsd: a.base_token_price_usd != null ? Number(a.base_token_price_usd) : null,
change24h:
a.price_change_percentage?.h24 != null
? Number(a.price_change_percentage.h24)
: null,
};
});
}
// Trending pools, normalised for the on-screen picker. The board turns over
// slowly, so the last good one is served through a GeckoTerminal outage.
export async function trendingPools(network = 'solana', limit = 8) {
return cacheWrapLastGood(
`ohlcv:trending:v1:${network}:${limit}`,
TRENDING_FRESH_S,
async () => normalizeTrending(await gecko(`/networks/${network}/trending_pools?page=1`), limit),
{ staleTtlSeconds: LKG_STALE_S },
);
}
const tokenOf = (m) => (m ? { name: m.name, symbol: m.symbol, address: m.address } : null);
function sortCandles(rows) {
return rows
.filter((d) => Number.isFinite(d.t) && Number.isFinite(d.c) && d.c > 0)
.sort((a, b) => a.t - b.t);
}
async function geckoCandles({ pool, network, timeframe, aggregate, limit, beforeTimestamp }) {
const before = beforeTimestamp ? `&before_timestamp=${Math.floor(beforeTimestamp)}` : '';
const json = await gecko(
`/networks/${network}/pools/${pool}/ohlcv/${timeframe}?aggregate=${aggregate}&limit=${limit}¤cy=usd${before}`,
);
const list = json?.data?.attributes?.ohlcv_list;
if (!Array.isArray(list)) throw tagged('GeckoTerminal returned no candles', 502);
// Upstream is newest-first; reverse to chronological and coerce to numbers.
const candles = sortCandles(
list.map((row) => ({
t: Number(row[0]),
o: Number(row[1]),
h: Number(row[2]),
l: Number(row[3]),
c: Number(row[4]),
v: Number(row[5] ?? 0),
})),
);
const meta = json?.meta || {};
return { candles, base: tokenOf(meta.base), quote: tokenOf(meta.quote), source: 'geckoterminal' };
}
// Birdeye's pair OHLCV takes the same pool address GeckoTerminal does, so it
// is a like-for-like second source for any Solana pool once the key is set.
async function birdeyePairCandles({ pool, network, timeframe, aggregate, limit }) {
const key = process.env.BIRDEYE_API_KEY;
const type = birdeyeTypeFor(timeframe, aggregate);
if (!key || network !== 'solana' || !type) return null;
const to = Math.floor(Date.now() / 1000);
const from = to - barSeconds(timeframe, aggregate) * limit;
const url =
`${BIRDEYE_BASE}/defi/ohlcv/pair?address=${encodeURIComponent(pool)}` +
`&type=${type}&time_from=${from}&time_to=${to}`;
const res = await fetchUpstream(
url,
{ headers: { 'X-API-KEY': key, 'x-chain': 'solana', accept: 'application/json' } },
{ timeoutMs: 10_000, attempts: 2, name: 'birdeye:ohlcv-pair', label: 'Birdeye pair OHLCV' },
);
const payload = await res.json().catch(() => null);
const items = payload?.data?.items;
if (!Array.isArray(items) || !items.length) return null;
const candles = sortCandles(
items.map((it) => ({
t: Number(it.unixTime),
o: Number(it.o),
h: Number(it.h),
l: Number(it.l),
c: Number(it.c),
v: Number(it.v ?? 0),
})),
);
return candles.length ? { candles, base: null, quote: null, source: 'birdeye' } : null;
}
// Last rung, majors only: exchange klines for the pool's base asset. The
// shared CEX layer yields a close series, so each bar is flagged close-only
// (open/high/low equal the close) rather than passing invented wicks off as
// real ones. Forecasters that consume `c` are unaffected; renderers can hide
// the wick.
async function cexCandles({ baseSymbol, timeframe, aggregate, limit }) {
if (!baseSymbol) return null;
const days = cexDaysFor(timeframe, aggregate, limit);
const providers = cexCandleProviders(String(baseSymbol).toUpperCase(), days);
if (!providers.length) return null;
const rows = await fetchFirstOrNull(providers, { timeoutMs: 6000, label: `cex-klines:${baseSymbol}` });
if (!Array.isArray(rows) || !rows.length) return null;
const candles = sortCandles(
rows.map(([tsMs, close]) => ({ t: Math.floor(tsMs / 1000), o: close, h: close, l: close, c: close, v: 0 })),
);
return candles.length ? { candles, base: { symbol: String(baseSymbol).toUpperCase() }, quote: { symbol: 'USD' }, source: 'cex', closeOnly: true } : null;
}
async function fetchOhlcvLive(args) {
let firstErr = null;
try {
return await geckoCandles(args);
} catch (e) {
firstErr = e;
}
// The other rungs cannot page back, and their newest bars would be passed off
// as the older window that was asked for.
if (args.beforeTimestamp) throw firstErr;
for (const rung of [birdeyePairCandles, cexCandles]) {
try {
const out = await rung(args);
if (out) return out;
} catch (e) {
if (!firstErr) firstErr = e;
}
}
throw firstErr || tagged('no OHLCV source answered', 502);
}
// Fetch OHLCV candles for a pool, returned oldest -> newest (chronological), plus
// the base/quote token metadata GeckoTerminal includes in the same response.
// timeframe: 'minute' | 'hour' | 'day' aggregate: bars per candle limit: <=1000
// baseSymbol: optional base-asset ticker (e.g. 'SOL') that unlocks the CEX rung
// beforeTimestamp: epoch seconds; GeckoTerminal returns the candles before it,
// which is how a caller pages back past the newest 1000 bars
// Result carries `source` ('geckoterminal' | 'birdeye' | 'cex') and, for the
// CEX rung, `closeOnly: true`.
export async function fetchOhlcv({
pool,
network = 'solana',
timeframe = 'hour',
aggregate = 1,
limit = 1000,
baseSymbol = null,
beforeTimestamp = null,
}) {
if (!pool) throw tagged('pool is required', 400);
const args = { pool, network, timeframe, aggregate, limit, baseSymbol, beforeTimestamp };
const key = `ohlcv:candles:v1:${network}:${pool}:${timeframe}:${aggregate}:${limit}${beforeTimestamp ? `:b${Math.floor(beforeTimestamp)}` : ''}`;
const out = await cacheWrapLastGood(key, LKG_FRESH_S, () => fetchOhlcvLive(args), {
staleTtlSeconds: LKG_STALE_S,
});
return {
...out,
freq: freqFor(timeframe, aggregate),
timeframe,
aggregate,
};
}