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
// GET /api/x402/market-heatmap?limit=50
//
// Market Heatmap — $0.002 USDC per call on Solana or Base. Returns the top
// coins by market cap with 1 h / 24 h / 7 d momentum plus market-breadth
// statistics (advancers vs decliners, average and median move) in one
// normalized snapshot.
//
// Dual live sources with automatic failover: CoinGecko /coins/markets first
// (richest fields, read through the shared keyed client in
// api/_lib/coingecko.js so a throttle is answered with its last-good copy),
// CoinPaprika /tickers second (keyless, but only sixty requests an HOUR shared
// across every caller on this deployment, see api/_lib/coinpaprika.js), so one
// upstream rate-limit never breaks a paid call. Cached 60 s in-memory. No mock
// path: if both sources fail the handler throws BEFORE settlement so the buyer
// is never charged.
import { paidEndpoint } from '../_lib/x402-paid-endpoint.js';
import { geckoFetch } from '../_lib/coingecko.js';
import { PAPRIKA_BASE, isPaprikaBenched, notePaprikaStatus } from '../_lib/coinpaprika.js';
import { buildBazaarSchema } from '../_lib/x402-spec.js';
import { installAccessControl } from '../_lib/x402/access-control.js';
import { withService } from '../_lib/x402/bazaar-helpers.js';
import { priceFor } from '../_lib/x402-prices.js';
import listing from '../_lib/service-catalog/services/market-heatmap.js';
const ROUTE = '/api/x402/market-heatmap';
const DESCRIPTION = listing.description;
const TTL_MS = 60_000;
const MAX_LIMIT = 100;
let _cache = null; // { coins, source, expiresAt }
// A numeric field, or null when the upstream had no value for it. The raw value
// is inspected before coercion because Number(null) and Number('') are both 0,
// so coercing first turned "CoinGecko has no 7 d change for this coin" into a
// paid claim that the coin moved 0%. The output schema declares every one of
// these nullable; an absent number must stay absent.
export const finite = (raw) => {
if (raw == null || raw === '') return null;
const n = Number(raw);
return Number.isFinite(n) ? n : null;
};
// Market-cap rank, or the row's board position when the upstream has none.
// CoinGecko sends `market_cap_rank: null` for coins it has not ranked, and the
// same Number(null) trap put a nonsense rank of 0 in the paid payload instead
// of falling back. Ranks are 1-based; anything else takes the fallback.
// (The CoinPaprika branch already filters rank > 0, so both sources agree.)
export const rankOr = (raw, fallback) => {
const n = Number(raw);
return Number.isFinite(n) && n > 0 ? Math.floor(n) : fallback;
};
// Routed through the shared CoinGecko client rather than a bare fetch to the
// public host. That client sends COINGECKO_API_KEY (a far higher rate limit
// than the keyless tier this endpoint used to hit), benches a rejected key and
// retries keyless, and serves its in-memory or durable last-good copy when the
// upstream throttles. Without it a paid call answered a 429 by falling to
// CoinPaprika, whose free budget is sixty requests an HOUR shared across the
// whole deployment, so a busy minute turned a $0.002 call into a 503 while
// fresher data sat in the platform cache.
async function fetchCoinGecko() {
const raw = await geckoFetch(
'/coins/markets?vs_currency=usd&order=market_cap_desc' +
`&per_page=${MAX_LIMIT}&page=1&sparkline=false&price_change_percentage=1h%2C24h%2C7d`,
{ ttlMs: TTL_MS },
);
if (!Array.isArray(raw) || !raw.length) throw new Error('coingecko empty');
return raw.map((c, i) => ({
rank: rankOr(c.market_cap_rank, i + 1),
symbol: typeof c.symbol === 'string' ? c.symbol.toUpperCase() : null,
name: typeof c.name === 'string' ? c.name : null,
price_usd: finite(c.current_price),
change_1h: finite(c.price_change_percentage_1h_in_currency),
change_24h: finite(c.price_change_percentage_24h_in_currency ?? c.price_change_percentage_24h),
change_7d: finite(c.price_change_percentage_7d_in_currency),
market_cap_usd: finite(c.market_cap),
volume_24h_usd: finite(c.total_volume),
}));
}
// CoinPaprika's free tier is sixty requests an HOUR across every surface that
// uses it (see api/_lib/coinpaprika.js), so this paid endpoint routes through
// the shared budget guard: when a sibling caller has already been blocked,
// this one fails immediately instead of spending 8s discovering the same thing.
async function fetchCoinPaprika() {
if (isPaprikaBenched()) throw new Error('coinpaprika budget spent');
const r = await fetch(`${PAPRIKA_BASE}/tickers?quotes=USD`, {
headers: { accept: 'application/json' },
signal: AbortSignal.timeout(8000),
});
notePaprikaStatus(r.status);
if (!r.ok) throw new Error(`coinpaprika ${r.status}`);
const raw = await r.json();
if (!Array.isArray(raw) || !raw.length) throw new Error('coinpaprika empty');
return raw
.filter((c) => Number.isFinite(Number(c?.rank)) && Number(c.rank) > 0 && c?.quotes?.USD)
.sort((a, b) => Number(a.rank) - Number(b.rank))
.slice(0, MAX_LIMIT)
.map((c) => {
const q = c.quotes.USD;
return {
rank: Number(c.rank),
symbol: typeof c.symbol === 'string' ? c.symbol.toUpperCase() : null,
name: typeof c.name === 'string' ? c.name : null,
price_usd: finite(q.price),
change_1h: finite(q.percent_change_1h),
change_24h: finite(q.percent_change_24h),
change_7d: finite(q.percent_change_7d),
market_cap_usd: finite(q.market_cap),
volume_24h_usd: finite(q.volume_24h),
};
});
}
async function loadBoard() {
const now = Date.now();
if (_cache && _cache.expiresAt > now) return _cache;
let coins = null;
let source = null;
try {
coins = await fetchCoinGecko();
source = 'coingecko';
} catch {
coins = await fetchCoinPaprika(); // throws through to the caller if it also fails
source = 'coinpaprika';
}
_cache = { coins, source, expiresAt: now + TTL_MS };
return _cache;
}
// Market breadth over the board's 24h moves. A +/- 0.05% dead band keeps
// rounding noise out of the advancer/decliner split, and coins the upstream
// could not price (change_24h null) are excluded rather than counted as flat,
// so the three buckets always sum to the number of coins actually measured.
export function breadth(coins) {
const moves = coins.map((c) => c.change_24h).filter((n) => n != null);
const advancers = moves.filter((n) => n > 0.05).length;
const decliners = moves.filter((n) => n < -0.05).length;
const flat = moves.length - advancers - decliners;
const avg = moves.length ? moves.reduce((s, n) => s + n, 0) / moves.length : null;
let median = null;
if (moves.length) {
const s = [...moves].sort((a, b) => a - b);
const m = Math.floor(s.length / 2);
median = s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
}
return {
advancers,
decliners,
flat,
avg_change_24h: avg != null ? Number(avg.toFixed(2)) : null,
median_change_24h: median != null ? Number(median.toFixed(2)) : null,
};
}
export const INPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
...listing.inputSchema,
};
export const OUTPUT_SCHEMA = {
$schema: 'https://json-schema.org/draft/2020-12/schema',
type: 'object',
required: ['breadth', 'coins', 'source', 'ts'],
properties: {
breadth: {
type: 'object',
required: ['advancers', 'decliners', 'flat', 'avg_change_24h', 'median_change_24h'],
properties: {
advancers: { type: 'integer' },
decliners: { type: 'integer' },
flat: { type: 'integer' },
avg_change_24h: { type: ['number', 'null'] },
median_change_24h: { type: ['number', 'null'] },
},
},
coins: {
type: 'array',
items: {
type: 'object',
required: ['rank', 'symbol', 'price_usd', 'change_24h', 'market_cap_usd'],
properties: {
rank: { type: 'integer' },
symbol: { type: ['string', 'null'] },
name: { type: ['string', 'null'] },
price_usd: { type: ['number', 'null'] },
change_1h: { type: ['number', 'null'] },
change_24h: { type: ['number', 'null'] },
change_7d: { type: ['number', 'null'] },
market_cap_usd: { type: ['number', 'null'] },
volume_24h_usd: { type: ['number', 'null'] },
},
},
},
source: { type: 'string', enum: ['coingecko', 'coinpaprika'] },
ts: { type: 'string', format: 'date-time' },
},
};
export const BAZAAR = {
description: DESCRIPTION,
useCases: ['market overview', 'momentum screening', 'breadth analysis'],
input: {
type: 'query',
example: listing.input,
schema: INPUT_SCHEMA,
},
output: {
type: 'json',
example: listing.outputExample,
},
schema: buildBazaarSchema({
method: 'GET',
queryParamsSchema: INPUT_SCHEMA,
outputSchema: OUTPUT_SCHEMA,
}),
};
export default paidEndpoint({
route: ROUTE,
method: 'GET',
priceAtomics: priceFor('market-heatmap', '2000'), // $0.002 USDC
networks: ['solana', 'base'],
description: DESCRIPTION,
bazaar: BAZAAR,
service: withService({
serviceName: listing.serviceName,
tags: listing.tags,
}),
accessControl: installAccessControl({ requiredScope: 'x402:bypass' }),
async handler({ req }) {
const raw = Number(new URL(req.url, 'http://x').searchParams.get('limit') || '50');
const limit = Math.min(MAX_LIMIT, Math.max(1, Number.isFinite(raw) ? Math.floor(raw) : 50));
let board = null;
try { board = await loadBoard(); } catch { /* refund below */ }
if (!board || !board.coins.length) {
throw Object.assign(new Error('market data is temporarily unavailable'), {
status: 503,
code: 'data_unavailable',
});
}
const coins = board.coins.slice(0, limit);
return {
breadth: breadth(coins),
coins,
source: board.source,
ts: new Date().toISOString(),
};
},
});