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
fix(derivative): say who pays the funding cost once, above the number, instead of inside it
ni3a9ddd3b84c7f2
diff --git a/src/derivative-page.css b/src/derivative-page.cssindex b34dd7c14..29854ef92 100644--- a/src/derivative-page.css+++ b/src/derivative-page.css@@ -99,9 +99,12 @@background: var(--cv-surface-2);color: var(--cv-text-2);}+/* --cv-accent-solid is the accent darkened for text that has to clear AA;+ --cv-accent on its own 10% tint reads 3.28:1 in light. Dark maps the two to+ the same value, so only light moves. */.dc-chip-perp {border-color: color-mix(in srgb, var(--cv-accent) 40%, var(--cv-border));- color: var(--cv-accent);+ color: var(--cv-accent-solid);background: color-mix(in srgb, var(--cv-accent) 10%, transparent);}@@ -170,6 +173,10 @@.dc-trade:active {transform: translateY(1px);}+.dc-trade:focus-visible {+ outline: 2px solid var(--cv-accent);+ outline-offset: 2px;+}/* ── Stat grid ──────────────────────────────────────────────────────────── */@@ -192,10 +199,10 @@grid-template-columns: repeat(4, minmax(0, 1fr));}}+/* The info affordance sits inside the label text, so a two-line label keeps it+ beside the last word instead of pushing it to the far edge of the card. */.dc-stat .label {- display: flex;- align-items: center;- gap: 0.25rem;+ display: block;text-transform: uppercase;letter-spacing: 0.05em;font-size: 0.6875rem;@@ -306,6 +313,11 @@border-color: var(--cv-accent);box-shadow: 0 0 0 3px color-mix(in srgb, var(--cv-accent) 25%, transparent);}+.dc-calc-cap {+ margin: 0 0 0.375rem;+ font-size: 0.75rem;+ color: var(--cv-text-3);+}.dc-calc-out {display: flex;flex-wrap: wrap;@@ -441,6 +453,19 @@color: var(--cv-accent);text-decoration: underline;}+.dc-table a:focus-visible,+.dc-venue-line a:focus-visible,+.dc-callout .v a:focus-visible {+ outline: 2px solid var(--cv-accent);+ outline-offset: 2px;+ border-radius: 2px;+}+.dc-table tbody tr:hover {+ background: var(--cv-surface-2);+}+.dc-table tr.dc-current:hover {+ background: color-mix(in srgb, var(--cv-accent) 16%, transparent);+}.dc-table tr.dc-current {background: color-mix(in srgb, var(--cv-accent) 10%, transparent);}@@ -490,6 +515,13 @@border-color: var(--cv-border-hover);box-shadow: var(--cv-shadow-card-hover);}+.dc-asset:focus-visible {+ outline: 2px solid var(--cv-accent);+ outline-offset: 2px;+}+.dc-asset:active {+ transform: translateY(1px);+}.dc-asset img {width: 40px;height: 40px;diff --git a/src/derivative-page.js b/src/derivative-page.jsindex 311131b39..75536c1b9 100644--- a/src/derivative-page.js+++ b/src/derivative-page.js@@ -336,7 +336,10 @@ function renderFunding(p) {value="${state.positionUsd}" aria-label="Position size in US dollars" /></div></div>- <div class="dc-calc-out" id="dc-calc-out">${fundingOutput(cost, longsPay)}</div>+ <div>+ <p class="dc-calc-cap">Paid by the ${esc(longsPay ? 'long' : 'short')} at the current rate</p>+ <div class="dc-calc-out" id="dc-calc-out">${fundingOutput(cost)}</div>+ </div></div></section>`;@@ -344,20 +347,19 @@ function renderFunding(p) {input.addEventListener('input', () => {const raw = Number(input.value);state.positionUsd = Number.isFinite(raw) && raw >= 0 ? raw : 0;- $('dc-calc-out').innerHTML = fundingOutput(- fundingCost(c.funding_rate, state.positionUsd),- longsPay,- );+ $('dc-calc-out').innerHTML = fundingOutput(fundingCost(c.funding_rate, state.positionUsd));});}-function fundingOutput(cost, longsPay) {+// All three figures are the same outflow over three horizons, so all three+// carry the same treatment. Colouring only two of them read as if the per+// interval number were a different kind of thing.+function fundingOutput(cost) {if (!cost) return '';- const side = longsPay ? 'long' : 'short';const cell = (k, v) =>`<div><p class="k">${esc(k)}</p><p class="v cv-down">${esc(formatUsdExact(v))}</p></div>`;return [- `<div><p class="k">Paid by the ${esc(side)}</p><p class="v">${esc(formatUsdExact(cost.perInterval))}</p></div>`,+ cell('Per interval', cost.perInterval),cell('Per day', cost.perDay),cell('Per year', cost.perYear),].join('');diff --git a/tests/api/derivative-contract.test.js b/tests/api/derivative-contract.test.jsnew file mode 100644index 000000000..578d1fd12--- /dev/null+++ b/tests/api/derivative-contract.test.js@@ -0,0 +1,385 @@+// /api/coin/derivative and the contract-slug helpers behind /derivative/:venue/:symbol.+//+// Three contracts are pinned here because each of them was a real decision, not+// an implementation detail:+//+// 1. The slug. Venue symbols include "ETH/USDT", which cannot ride a path+// segment: a percent-encoded slash is decoded before routing and splits+// the route. The "~" fold has to round-trip exactly, and the browser copy+// of the helper has to stay byte-identical to the server copy, because the+// server build context excludes src/ and cannot import it.+// 2. The basis sign. CoinGecko publishes the INDEX's premium over the+// contract; the page states "trading above/below its index" about the+// CONTRACT, so the sign is flipped on the way out. Getting this backwards+// is invisible in a diff and wrong on every page.+// 3. Fail-soft. Only the venue read is load-bearing. The cross-venue feed,+// the venue directory and the spot lookup must each degrade to+// empty/null rather than 502 a page whose headline numbers are already in+// hand.++import { describe, it, expect, vi, beforeEach } from 'vitest';+import { readFileSync } from 'node:fs';+import { fileURLToPath } from 'node:url';++vi.mock('../../api/_lib/zauth.js', () => ({ instrument: () => {}, drain: async () => {} }));+vi.mock('../../api/_lib/sentry.js', () => ({ captureException: () => {} }));+vi.mock('../../api/_lib/rate-limit.js', () => ({+ limits: { marketDataIp: async () => ({ success: true }) },+ clientIp: () => '203.0.113.1',+}));++const geckoFetch = vi.fn();+vi.mock('../../api/_lib/coingecko.js', () => ({+ geckoFetch: (...args) => geckoFetch(...args),+ htmlToText: (s) => String(s || '').replace(/<[^>]+>/g, ''),+}));++vi.mock('../../api/_lib/hyperliquid.js', () => ({ fetchHyperliquidPerps: async () => [] }));+vi.mock('../../api/_lib/deribit.js', () => ({ fetchDeribitSummary: async () => null }));++const handler = (await import('../../api/coin/derivative.js')).default;+const listHandler = (await import('../../api/coin/derivatives.js')).default;+const slugServer = await import('../../api/_lib/derivative-slug.js');+const slugClient = await import('../../src/shared/derivative-slug.js');++// ── Fixtures: real-shaped, trimmed captures ─────────────────────────────────++const VENUE_DETAIL = {+ name: 'Acme Futures',+ image: 'https://cdn.example/acme.png',+ url: 'https://acme.example/futures',+ description: '<p>Acme Futures is a derivatives venue.</p>',+ country: 'Lithuania',+ year_established: 2022,+ open_interest_btc: 1000,+ trade_volume_24h_btc: 5000,+ number_of_perpetual_pairs: 3,+ number_of_futures_pairs: 0,+ tickers: [+ {+ symbol: 'ETH/USDT',+ base: 'ETH',+ target: 'USDT',+ coin_id: 'ethereum',+ trade_url: 'https://acme.example/trade/ETH_USDT',+ contract_type: 'perpetual',+ last: 2000,+ h24_percentage_change: -1.5,+ index: 1980,+ // Upstream convention: (index - last) / last, i.e. the index's premium.+ index_basis_percentage: -1,+ bid_ask_spread: 0.0002,+ funding_rate: 0.01,+ open_interest_usd: 600_000_000,+ h24_volume: 42,+ converted_volume: { usd: '800000000' },+ last_traded: 1789883238,+ expired_at: null,+ },+ {+ symbol: 'BTC_PERP',+ base: 'BTC',+ target: 'USDT',+ coin_id: 'bitcoin',+ contract_type: 'perpetual',+ last: 80000,+ funding_rate: 0.005,+ open_interest_usd: 400_000_000,+ converted_volume: { usd: '200000000' },+ },+ ],+};++const VENUE_DIRECTORY = [+ { id: 'acme_futures', name: 'Acme Futures', image: 'https://cdn.example/acme.png', open_interest_btc: 1000 },+ { id: 'zeta_futures', name: 'Zeta (Futures)', image: 'https://cdn.example/zeta.png', open_interest_btc: 900 },+ { id: 'dust_futures', name: 'Dust (Futures)', image: null, open_interest_btc: 1 },+];++// Zeta is liquid and funds cheapest; Dust funds far cheaper still but trades+// under the floor, so it must never be offered as somewhere to act.+const CROSS_VENUE_FEED = [+ {+ market: 'Acme Futures',+ symbol: 'ETH/USDT',+ index_id: 'ETH',+ contract_type: 'perpetual',+ price: 1999,+ price_percentage_change_24h: -1.4,+ funding_rate: 0.01,+ open_interest: 600_000_000,+ volume_24h: 800_000_000,+ },+ {+ market: 'Zeta (Futures)',+ symbol: 'ETHUSDT',+ index_id: 'ETH',+ contract_type: 'perpetual',+ price: 2010,+ price_percentage_change_24h: -1.2,+ funding_rate: -0.004,+ open_interest: 1_400_000_000,+ volume_24h: 5_000_000,+ },+ {+ market: 'Dust (Futures)',+ symbol: 'ETH-PERP',+ index_id: 'ETH',+ contract_type: 'perpetual',+ price: 2500,+ funding_rate: -9,+ open_interest: 10_000,+ volume_24h: 12,+ },+ // Different index, and an expiring future: neither belongs in the peer set.+ { market: 'Zeta (Futures)', symbol: 'BTCUSDT', index_id: 'BTC', contract_type: 'perpetual', funding_rate: 0.002, volume_24h: 9_000_000 },+ { market: 'Zeta (Futures)', symbol: 'ETH-0325', index_id: 'ETH', contract_type: 'futures', funding_rate: 0.5, volume_24h: 9_000_000 },+];++const SPOT_ROW = {+ id: 'ethereum',+ name: 'Ethereum',+ symbol: 'eth',+ image: 'https://cdn.example/eth.png',+ current_price: 1985,+ price_change_percentage_24h: -1.44,+ market_cap: 240_000_000_000,+ market_cap_rank: 2,+ total_volume: 11_000_000_000,+ high_24h: 2050,+ low_24h: 1970,+ ath: 4946,+ ath_change_percentage: -59.8,+};++function routeGecko(path) {+ if (path.startsWith('/derivatives/exchanges/acme_futures')) return VENUE_DETAIL;+ if (path.startsWith('/derivatives/exchanges?')) return VENUE_DIRECTORY;+ if (path.startsWith('/derivatives?')) return CROSS_VENUE_FEED;+ if (path.startsWith('/coins/markets')) return [SPOT_ROW];+ const err = new Error(`CoinGecko 404 for ${path}`);+ err.status = 404;+ throw err;+}++function makeRes() {+ return {+ statusCode: 200,+ _h: {},+ setHeader(k, v) {+ this._h[k.toLowerCase()] = v;+ },+ getHeader(k) {+ return this._h[k.toLowerCase()];+ },+ end(body) {+ this._body = body;+ },+ };+}++async function call(query) {+ const res = makeRes();+ await handler({ url: `/api/coin/derivative?${query}`, method: 'GET', headers: {} }, res);+ return { res, body: JSON.parse(res._body) };+}++beforeEach(() => {+ geckoFetch.mockReset();+ geckoFetch.mockImplementation(async (path) => routeGecko(path));+});++// ── Slug helpers ────────────────────────────────────────────────────────────++describe('derivative contract slugs', () => {+ it('keeps the browser and server copies byte-identical', () => {+ const server = readFileSync(+ fileURLToPath(new URL('../../api/_lib/derivative-slug.js', import.meta.url)),+ 'utf8',+ );+ const client = readFileSync(+ fileURLToPath(new URL('../../src/shared/derivative-slug.js', import.meta.url)),+ 'utf8',+ );+ expect(client).toBe(server);+ });++ it('round-trips every symbol shape the feed carries', () => {+ for (const symbol of ['ETH_PERP', 'BTCUSDT', 'ETH-USDT-SWAP', 'ETH/USDT', 'BTC.USD:PERP']) {+ const slug = slugServer.contractSlug(symbol);+ expect(slug).not.toBeNull();+ expect(slug).not.toContain('/');+ expect(slugServer.symbolFromSlug(slug)).toBe(symbol);+ expect(slugClient.contractSlug(symbol)).toBe(slug);+ }+ });++ it('refuses a symbol it cannot address, rather than mangling it', () => {+ expect(slugServer.contractSlug('')).toBeNull();+ expect(slugServer.contractSlug('ETH~USDT')).toBeNull(); // the fold char itself+ expect(slugServer.contractSlug('ETH USDT')).toBeNull();+ expect(slugServer.contractSlug('a'.repeat(49))).toBeNull();+ expect(slugServer.derivativePath('acme futures', 'ETH_PERP')).toBeNull();+ });++ it('tolerates a still-encoded path segment', () => {+ expect(slugServer.symbolFromSlug('ETH%7EUSDT')).toBe('ETH/USDT');+ expect(slugServer.symbolFromSlug('%E0%A4%A')).toBeNull(); // malformed escape+ });++ it('builds the canonical path', () => {+ expect(slugServer.derivativePath('Acme_Futures', 'ETH/USDT')).toBe(+ '/derivative/acme_futures/ETH~USDT',+ );+ });+});++// ── Endpoint ────────────────────────────────────────────────────────────────++describe('GET /api/coin/derivative', () => {+ it('rejects a venue or symbol it could not address', async () => {+ expect((await call('venue=not a venue&symbol=ETH_PERP')).res.statusCode).toBe(400);+ expect((await call('venue=acme_futures&symbol=')).res.statusCode).toBe(400);+ });++ it('404s a symbol the venue does not list', async () => {+ const { res, body } = await call('venue=acme_futures&symbol=NOPE');+ expect(res.statusCode).toBe(404);+ expect(body.error).toBe('not_found');+ });++ it('404s an unknown venue', async () => {+ const { res } = await call('venue=nosuchvenue&symbol=ETH_PERP');+ expect(res.statusCode).toBe(404);+ });++ it('reports basis as the contract premium over the index, not the reverse', async () => {+ const { res, body } = await call('venue=acme_futures&symbol=ETH%2FUSDT');+ expect(res.statusCode).toBe(200);+ // last 2000 over index 1980 is a contract trading ~1.01% ABOVE its index,+ // even though upstream called the same gap -1.+ expect(body.contract.basis_pct).toBeCloseTo(1.0101, 3);+ });++ it('annualizes funding at three settlements a day', async () => {+ const { body } = await call('venue=acme_futures&symbol=ETH%2FUSDT');+ expect(body.contract.funding_rate).toBe(0.01);+ expect(body.contract.funding_apr).toBeCloseTo(0.01 * 3 * 365, 6);+ expect(body.funding_periods_per_year).toBe(1095);+ });++ it('finds the contract case-insensitively and carries its own slug', async () => {+ const { body } = await call('venue=acme_futures&symbol=eth%2Fusdt');+ expect(body.contract.symbol).toBe('ETH/USDT');+ expect(body.contract.slug).toBe('ETH~USDT');+ });++ it('sizes the contract against its venue and its underlying', async () => {+ const { body } = await call('venue=acme_futures&symbol=ETH%2FUSDT');+ // 600 of 1000 open interest, 800 of 1000 volume across the venue's book.+ expect(body.contract.venue_oi_share_pct).toBeCloseTo(60, 6);+ expect(body.contract.venue_vol_share_pct).toBeCloseTo(80, 6);+ // 600M of the 2.00001B open across every venue listing an ETH perp.+ expect(body.peer_stats.oi_share_pct).toBeCloseTo((600_000_000 / 2_000_010_000) * 100, 6);+ expect(body.peer_stats.oi_rank).toBe(2);+ });++ it('marks the contract being viewed inside the cross-venue table', async () => {+ const { body } = await call('venue=acme_futures&symbol=ETH%2FUSDT');+ const current = body.peers.filter((p) => p.current);+ expect(current).toHaveLength(1);+ expect(current[0].venue_id).toBe('acme_futures');+ // The venue-scoped read is fresher, so its numbers win on that one row.+ expect(current[0].price).toBe(2000);+ });++ it('keeps only perpetuals on the same index, and resolves each venue id', async () => {+ const { body } = await call('venue=acme_futures&symbol=ETH%2FUSDT');+ expect(body.peers.map((p) => p.symbol).sort()).toEqual(['ETH-PERP', 'ETH/USDT', 'ETHUSDT']);+ expect(body.peers.find((p) => p.symbol === 'ETHUSDT').venue_id).toBe('zeta_futures');+ expect(body.peers.find((p) => p.symbol === 'ETH-PERP').slug).toBe('ETH-PERP');+ });++ it('never nominates a dormant book as somewhere to act', async () => {+ const { body } = await call('venue=acme_futures&symbol=ETH%2FUSDT');+ const s = body.peer_stats;+ expect(s.venues).toBe(3);+ expect(s.liquid_venues).toBe(2);+ // Dust funds at -9% and would win on rate alone; it trades $12 a day.+ expect(s.cheapest_long.venue_id).toBe('zeta_futures');+ expect(s.richest_short.venue_id).toBe('acme_futures');+ // Its 2500 print must not set the dispersion band either.+ expect(s.price_max).toBe(2010);+ // Totals still count every venue, dormant or not.+ expect(s.total_open_interest_usd).toBe(2_000_010_000);+ });++ it('lists the venue’s other contracts without repeating this one', async () => {+ const { body } = await call('venue=acme_futures&symbol=ETH%2FUSDT');+ expect(body.venue_contracts.map((t) => t.symbol)).toEqual(['BTC_PERP']);+ expect(body.venue.contracts_listed).toBe(2);+ expect(body.venue.description).toBe('Acme Futures is a derivatives venue.');+ });++ it('attaches the underlying spot market', async () => {+ const { body } = await call('venue=acme_futures&symbol=ETH%2FUSDT');+ expect(body.index.coin_id).toBe('ethereum');+ expect(body.index.symbol).toBe('ETH');+ expect(body.index.price_usd).toBe(1985);+ });++ it('still serves the contract when every secondary source is down', async () => {+ geckoFetch.mockImplementation(async (path) => {+ if (path.startsWith('/derivatives/exchanges/acme_futures')) return VENUE_DETAIL;+ throw new Error(`CoinGecko 429 for ${path}`);+ });+ const { res, body } = await call('venue=acme_futures&symbol=BTC_PERP');+ expect(res.statusCode).toBe(200);+ expect(body.contract.symbol).toBe('BTC_PERP');+ expect(body.peers).toEqual([]);+ expect(body.peer_stats).toBeNull();+ expect(body.index).toBeNull();+ // The venue read alone is enough to size the contract against its book.+ expect(body.contract.venue_vol_share_pct).toBeCloseTo(20, 6);+ });++ it('502s only when the venue read itself fails', async () => {+ geckoFetch.mockImplementation(async () => {+ throw new Error('CoinGecko 429');+ });+ const { res, body } = await call('venue=acme_futures&symbol=ETH_PERP');+ expect(res.statusCode).toBe(502);+ expect(body.error).toBe('upstream_error');+ });+});++// ── The table that links here ───────────────────────────────────────────────++describe('GET /api/coin/derivatives', () => {+ it('addresses every row it can, so the table rows are clickable', async () => {+ const res = makeRes();+ await listHandler({ url: '/api/coin/derivatives', method: 'GET', headers: {} }, res);+ const body = JSON.parse(res._body);+ const acme = body.tickers.find((t) => t.market === 'Acme Futures');+ expect(acme.venue_id).toBe('acme_futures');+ expect(acme.slug).toBe('ETH~USDT');+ });++ it('leaves a row unaddressed rather than pointing it at a 404', async () => {+ geckoFetch.mockImplementation(async (path) => {+ if (path.startsWith('/derivatives/exchanges?')) throw new Error('CoinGecko 429');+ return routeGecko(path);+ });+ // Both the ticker table and the venue directory hold module-level caches+ // that outlive a test, and a warm directory would answer from the copy the+ // earlier case fetched. A fresh registry is what actually exercises the+ // directory being unreachable.+ vi.resetModules();+ const freshList = (await import('../../api/coin/derivatives.js')).default;+ const res = makeRes();+ await freshList({ url: '/api/coin/derivatives', method: 'GET', headers: {} }, res);+ const body = JSON.parse(res._body);+ expect(body.tickers.length).toBeGreaterThan(0);+ for (const t of body.tickers) expect(t.venue_id ?? null).toBeNull();+ });+});