Skip to content

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.

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.css
index 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.js
index 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.js
new file mode 100644
index 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();
+ });
+});