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/coin/derivative?venue=<exchange-id>&symbol=<venue-symbol>
// ---------------------------------------------------------------------------
// One perpetual contract in full, powering the /derivative/:venue/:symbol
// detail page that the /derivatives table now links into. The table row is a
// summary (price, funding, open interest, volume); this endpoint answers the
// questions the row raises: is this contract trading above or below its own
// index, what does its funding cost annualized, how big is it next to the rest
// of the venue, and where does the same underlying fund cheaper somewhere
// else.
//
// Four upstream reads, all shared with pages that already ran them, so a warm
// instance usually serves this from cache:
// 1. /derivatives/exchanges/{venue}?include_tickers=unexpired
// The contract itself plus every other contract on the venue, and the
// venue profile (country, year, description, open interest).
// 2. /derivatives?include_tickers=unexpired
// Same feed /derivatives renders, reused here to price the SAME index on
// every other venue: the cross-venue funding table.
// 3. The venue directory (api/_lib/derivative-venues.js) for display-name to
// id resolution, so each peer row links to its own detail page.
// 4. /coins/markets for the underlying asset (spot price, market cap, rank),
// which links the contract back to /coin/:id.
//
// Only read 1 is load-bearing. Reads 2 to 4 fail soft to null/empty: a
// cross-venue outage must not take down the contract page.
import { cors, json, method, wrap, error, rateLimited } from '../_lib/http.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { geckoFetch, htmlToText } from '../_lib/coingecko.js';
import { fetchDerivativeVenues, venueNameKey } from '../_lib/derivative-venues.js';
import { VENUE_ID_RE, SYMBOL_RE, contractSlug } from '../_lib/derivative-slug.js';
const VENUE_TTL_MS = 120_000;
const FEED_TTL_MS = 60_000;
const ASSET_TTL_MS = 120_000;
// Most venues settle funding three times a day (every 8h). CoinGecko does not
// publish the interval, so the annualized figure is an 8h-interval estimate and
// every surface that shows it says so.
const FUNDING_PERIODS_PER_YEAR = 3 * 365;
// How many rows each secondary table carries. Both are ranked by 24h volume,
// so the cut keeps the liquid end.
const MAX_PEERS = 40;
const MAX_VENUE_CONTRACTS = 12;
const num = (v) => {
if (v == null || v === '') return null;
const n = typeof v === 'number' ? v : Number(v);
return Number.isFinite(n) ? n : null;
};
const str = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
const httpUrl = (v) => (typeof v === 'string' && /^https?:\/\//.test(v) ? v : null);
// CoinGecko funding_rate is a percentage for one funding interval (0.01 means
// 0.01%, not 1%). Annualizing assumes the 8h schedule above.
function fundingApr(rate) {
return rate == null ? null : rate * FUNDING_PERIODS_PER_YEAR;
}
// bid_ask_spread on the derivatives namespace is a ratio, not a percentage.
function spreadPct(v) {
const n = num(v);
return n == null ? null : n * 100;
}
// CoinGecko reports `index_basis_percentage` as the INDEX's premium over the
// contract ((index - last) / last). Traders read basis the other way round: a
// contract trading above the thing it settles against is a positive basis, and
// that is the sign that agrees with funding. So the value is derived straight
// from the two prices when both are present, and the upstream field is negated
// as the fallback.
function contractBasisPct(t) {
const last = num(t.last);
const index = num(t.index);
if (last != null && index != null && index !== 0) return ((last - index) / index) * 100;
const upstream = num(t.index_basis_percentage);
return upstream == null ? null : -upstream;
}
function shapeContract(t, venueId) {
const symbol = str(t.symbol);
const base = str(t.base);
const target = str(t.target);
const funding = num(t.funding_rate);
return {
symbol,
slug: symbol ? contractSlug(symbol) : null,
base,
target,
pair: base && target ? `${base}/${target}` : symbol,
venue_id: venueId,
contract_type: str(t.contract_type) || 'perpetual',
coin_id: str(t.coin_id),
price: num(t.last),
index: num(t.index),
basis_pct: contractBasisPct(t),
change_24h: num(t.h24_percentage_change),
funding_rate: funding,
funding_apr: fundingApr(funding),
open_interest_usd: num(t.open_interest_usd),
volume_24h_usd: num(t.converted_volume?.usd),
volume_24h_base: num(t.h24_volume),
spread_pct: spreadPct(t.bid_ask_spread),
last_traded_at: num(t.last_traded),
expired_at: t.expired_at ?? null,
trade_url: httpUrl(t.trade_url),
};
}
// A row from the cross-venue /derivatives feed. Thinner than shapeContract:
// that feed carries no base/target, spread or index.
function shapePeer(t, venue) {
const symbol = str(t.symbol);
const funding = num(t.funding_rate);
return {
venue_id: venue?.id ?? null,
venue_name: str(t.market) || venue?.name || 'Unknown',
image: venue?.image ?? null,
symbol,
slug: symbol ? contractSlug(symbol) : null,
price: num(t.price ?? t.last),
change_24h: num(t.price_percentage_change_24h ?? t.h24_percentage_change),
funding_rate: funding,
funding_apr: fundingApr(funding),
open_interest_usd: num(t.open_interest),
volume_24h_usd: num(t.volume_24h),
current: false,
};
}
function median(values) {
if (!values.length) return null;
const s = [...values].sort((a, b) => a - b);
const mid = s.length >> 1;
return s.length % 2 ? s[mid] : (s[mid - 1] + s[mid]) / 2;
}
// A popular index lists on well over a hundred venues, most of them thin. The
// extremes of that full set are noise: a DEX doing four figures a day sets the
// widest funding and the widest price every single time. Anything presented as
// somewhere a trader could actually act (best venue to hold a long, best venue
// to hold a short, how far quotes disagree) is drawn from venues clearing at
// least this much in 24h volume; the aggregate totals and shares still count
// every venue.
const LIQUID_VOLUME_FLOOR_USD = 1_000_000;
function pick(peer) {
return peer
? {
venue_id: peer.venue_id,
venue_name: peer.venue_name,
symbol: peer.symbol,
slug: peer.slug,
funding_rate: peer.funding_rate,
funding_apr: peer.funding_apr,
}
: null;
}
// Everything the cross-venue table needs to be an answer rather than a list:
// where this contract's funding sits against the field, how much of the
// underlying's open interest and volume it holds, and how far the venues
// disagree on price.
function summarizePeers(peers, current) {
if (!peers.length) return null;
const liquid = peers.filter((p) => (p.volume_24h_usd ?? 0) >= LIQUID_VOLUME_FLOOR_USD);
const fundings = liquid.map((p) => p.funding_rate).filter((v) => v != null);
const prices = liquid.map((p) => p.price).filter((v) => v != null && v > 0);
const totalOi = peers.reduce((s, p) => s + (p.open_interest_usd ?? 0), 0);
const totalVol = peers.reduce((s, p) => s + (p.volume_24h_usd ?? 0), 0);
const byFunding = liquid.filter((p) => p.funding_rate != null);
const cheapestLong = byFunding.length
? byFunding.reduce((a, b) => (b.funding_rate < a.funding_rate ? b : a))
: null;
const richestShort = byFunding.length
? byFunding.reduce((a, b) => (b.funding_rate > a.funding_rate ? b : a))
: null;
const priceMin = prices.length ? Math.min(...prices) : null;
const priceMax = prices.length ? Math.max(...prices) : null;
const rankBy = (key) => {
const value = current?.[key];
if (value == null) return null;
return peers.filter((p) => (p[key] ?? -Infinity) > value).length + 1;
};
return {
venues: peers.length,
liquid_venues: liquid.length,
liquid_floor_usd: LIQUID_VOLUME_FLOOR_USD,
funding_min: fundings.length ? Math.min(...fundings) : null,
funding_max: fundings.length ? Math.max(...fundings) : null,
funding_median: median(fundings),
funding_spread: fundings.length ? Math.max(...fundings) - Math.min(...fundings) : null,
cheapest_long: pick(cheapestLong),
richest_short: pick(richestShort),
price_min: priceMin,
price_max: priceMax,
price_dispersion_pct: priceMin && priceMax ? ((priceMax - priceMin) / priceMin) * 100 : null,
total_open_interest_usd: totalOi || null,
total_volume_24h_usd: totalVol || null,
oi_share_pct: totalOi && current?.open_interest_usd != null ? (current.open_interest_usd / totalOi) * 100 : null,
vol_share_pct: totalVol && current?.volume_24h_usd != null ? (current.volume_24h_usd / totalVol) * 100 : null,
oi_rank: rankBy('open_interest_usd'),
vol_rank: rankBy('volume_24h_usd'),
};
}
// The same underlying on every other venue, ranked by 24h volume. The feed
// keys venues by display name, so each row is resolved back to an id through
// the venue directory in order to link to its own detail page.
async function buildPeers(indexId, contract, venueName) {
if (!indexId) return { peers: [], stats: null };
let rows = [];
try {
const raw = await geckoFetch('/derivatives?include_tickers=unexpired', { ttlMs: FEED_TTL_MS });
rows = Array.isArray(raw) ? raw : [];
} catch {
return { peers: [], stats: null };
}
let byName = new Map();
try {
({ byName } = await fetchDerivativeVenues());
} catch {
// Names without ids still render; they just do not link anywhere.
}
const wantedVenue = venueNameKey(venueName);
const peers = rows
.filter((t) => t && t.contract_type === 'perpetual' && t.index_id === indexId)
.map((t) => shapePeer(t, byName.get(venueNameKey(t.market))))
.sort((a, b) => (b.volume_24h_usd ?? 0) - (a.volume_24h_usd ?? 0));
for (const p of peers) {
if (venueNameKey(p.venue_name) === wantedVenue && p.symbol === contract.symbol) {
p.current = true;
// The venue-scoped read is the fresher of the two feeds for this one
// contract, so the row the visitor is standing on shows those numbers.
p.price = contract.price ?? p.price;
p.funding_rate = contract.funding_rate ?? p.funding_rate;
p.funding_apr = fundingApr(p.funding_rate);
p.open_interest_usd = contract.open_interest_usd ?? p.open_interest_usd;
p.volume_24h_usd = contract.volume_24h_usd ?? p.volume_24h_usd;
}
}
const stats = summarizePeers(peers, contract);
return { peers: peers.slice(0, MAX_PEERS), stats };
}
// Spot market data for the contract's underlying, so the page can put the mark
// price next to the asset it tracks and link through to /coin/:id.
async function buildIndexAsset(coinId) {
if (!coinId) return null;
try {
const raw = await geckoFetch(
`/coins/markets?vs_currency=usd&ids=${encodeURIComponent(coinId)}&price_change_percentage=24h&sparkline=false`,
{ ttlMs: ASSET_TTL_MS },
);
const row = Array.isArray(raw) ? raw[0] : null;
if (!row) return null;
return {
coin_id: str(row.id),
name: str(row.name),
symbol: str(row.symbol)?.toUpperCase() ?? null,
image: httpUrl(row.image),
price_usd: num(row.current_price),
change_24h: num(row.price_change_percentage_24h),
market_cap: num(row.market_cap),
market_cap_rank: num(row.market_cap_rank),
volume_24h: num(row.total_volume),
high_24h: num(row.high_24h),
low_24h: num(row.low_24h),
ath: num(row.ath),
ath_change_pct: num(row.ath_change_percentage),
};
} catch {
return null;
}
}
/**
* Assemble the full contract payload.
* Throws with `status` 404 when the venue or the symbol is unknown upstream.
*/
export async function buildDerivativeContract(venueId, symbol) {
const detail = await geckoFetch(
`/derivatives/exchanges/${encodeURIComponent(venueId)}?include_tickers=unexpired`,
{ ttlMs: VENUE_TTL_MS },
);
const tickers = Array.isArray(detail?.tickers) ? detail.tickers : [];
const wanted = symbol.toLowerCase();
const raw = tickers.find((t) => String(t?.symbol ?? '').toLowerCase() === wanted);
if (!raw) {
const err = new Error(`no contract ${symbol} on ${venueId}`);
err.status = 404;
throw err;
}
const contract = shapeContract(raw, venueId);
const venueName = (detail.name || venueId).trim();
const venue = {
id: venueId,
name: venueName,
image: httpUrl(detail.image),
url: httpUrl(detail.url),
description: detail.description ? htmlToText(detail.description) : null,
country: str(detail.country),
year_established: num(detail.year_established),
open_interest_btc: num(detail.open_interest_btc),
trade_volume_24h_btc: num(detail.trade_volume_24h_btc),
perpetual_pairs: num(detail.number_of_perpetual_pairs),
futures_pairs: num(detail.number_of_futures_pairs),
contracts_listed: tickers.length,
};
// Everything else the venue lists, ranked by volume, minus this contract.
const venueContracts = tickers
.filter((t) => t && String(t.symbol ?? '').toLowerCase() !== wanted)
.map((t) => shapeContract(t, venueId))
.sort((a, b) => (b.volume_24h_usd ?? 0) - (a.volume_24h_usd ?? 0))
.slice(0, MAX_VENUE_CONTRACTS);
const venueOi = tickers.reduce((s, t) => s + (num(t.open_interest_usd) ?? 0), 0);
const venueVol = tickers.reduce((s, t) => s + (num(t.converted_volume?.usd) ?? 0), 0);
contract.venue_oi_share_pct =
venueOi && contract.open_interest_usd != null ? (contract.open_interest_usd / venueOi) * 100 : null;
contract.venue_vol_share_pct =
venueVol && contract.volume_24h_usd != null ? (contract.volume_24h_usd / venueVol) * 100 : null;
const [{ peers, stats }, indexAsset] = await Promise.all([
buildPeers(contract.base, contract, venueName),
buildIndexAsset(contract.coin_id),
]);
return {
venue,
contract,
index: indexAsset,
peers,
peer_stats: stats,
venue_contracts: venueContracts,
funding_periods_per_year: FUNDING_PERIODS_PER_YEAR,
updated_at: Date.now(),
};
}
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'GET,OPTIONS', origins: '*' })) return;
if (!method(req, res, ['GET'])) return;
const rl = await limits.marketDataIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl);
const params = new URL(req.url, 'http://x').searchParams;
const venue = (params.get('venue') || '').trim().toLowerCase();
const symbol = (params.get('symbol') || '').trim();
if (!VENUE_ID_RE.test(venue)) {
return error(res, 400, 'bad_request', 'venue must be a derivatives exchange id');
}
if (!SYMBOL_RE.test(symbol)) {
return error(res, 400, 'bad_request', 'symbol must be a venue contract symbol');
}
try {
const payload = await buildDerivativeContract(venue, symbol);
return json(res, 200, payload, {
'cache-control': 'public, max-age=30, s-maxage=60, stale-while-revalidate=300',
});
} catch (err) {
if (err?.status === 404) {
return error(
res,
404,
'not_found',
`no active contract "${symbol}" on "${venue}"`,
);
}
return error(
res,
502,
'upstream_error',
'contract data is unavailable right now, please retry shortly',
);
}
});