Market overview

client.marketOverview is the ticker surface: one row per spot market with last and optional index prices, 24-hour stats, top-of-book quotes, listing time, and optional sparklines. It uses the public transport, so no authentication is required.

Prices and quantities come back as decimal strings, already scaled to each pair's precision. Timestamps are epoch milliseconds.

Methods

list(input?, options?)

Returns { markets, nextPageToken }. Every field is optional: with no input you get the top 500 markets by canonical 24-hour USD volume, descending.

await client.catalog.ensureReady();
const { markets } = await client.marketOverview.list({
	limit: 20,
	orderBy: "volume_24h_usd",
	sort: "desc",
	includeSparklines: true,
});

for (const m of markets) {
	const symbol = client.catalog.market.requirePairSymbolBySymbolId(m.symbolId);
	console.log(symbol, m.lastPrice, m.change24hBps);
}

Filter to specific pairs with symbolIds, and page through larger sets with the returned token:

const symbolId = client.catalog.market.requireSymbolIdByPairSymbol("BTC-USDT");
const first = await client.marketOverview.list({ symbolIds: [symbolId] });
const next = await client.marketOverview.list({ pageToken: first.nextPageToken });

ListMarketOverviewInput

subscribe(input)

Streams the live set of market rows. It fetches an initial snapshot, buffers updates until ready, and emits the merged full set as an array on every change. On reconnect it refetches the snapshot before resuming. symbolIds filters the snapshot, buffered updates, and live publications, including after reconnect. Omit it or pass [] for all symbols. Returns an idempotent unsubscribe function.

const unsubscribe = client.marketOverview.subscribe({
	includeSparklines: true,
	sparklineIntervals: ["24h"],
	onEvent: (markets) => {
		// markets is the full merged MarketOverview[] on every update
		console.log(markets.length, "markets");
	},
	onError: (ctx) => console.error(ctx.channel, ctx.error),
});

// later
unsubscribe();

onEvent is required. onOpen, onClose, and onError are optional. See the realtime client reference for the handler contract.

getSpotVolumeHistory(input?, options?)

Returns 97 aligned trailing-24-hour USD-volume samples at 15-minute intervals. With no symbolIds, it returns every configured pair; pass up to 2,000 distinct positive IDs to select specific pairs. The result is { bucket, startTsSec, endTsSec, points, pairs, totalVolumeUsd }: bucket is currently "15m", every pair's volumeUsd and totalVolumeUsd are decimal-string arrays ordered oldest-first, and each pair has its symbolId.

Samples overlap, so do not sum them to calculate traded volume for a period. The request rejects when a contributing trade cannot be valued in USD; it does not return partial or zero-filled valuations.

const history = await client.marketOverview.getSpotVolumeHistory({ symbolIds: [1, 2] });
console.log(history.totalVolumeUsd.at(-1)); // latest trailing-24h USD volume

getCurrencyConversionConfig(options?)

Returns cacheable display metadata as { fiat, stablecoins }, even before rates have been observed. Each entry has code, defaultEnglishName, symbol, and fractionDigits.

getCurrencyConversionRates(options?)

Returns exact decimal-string conversion rates and backend staleness flags. Fiat rates are currency units per USD; stablecoin rates are USD per stablecoin unit.

const config = await client.marketOverview.getCurrencyConversionConfig();
const rates = await client.marketOverview.getCurrencyConversionRates();

for (const rate of rates.fiat?.rates ?? []) {
	console.log(rate.code, rate.unitsPerUsd, rates.fiat?.stale);
}
for (const rate of rates.stablecoins) {
	console.log(rate.code, rate.usdPerUnit, rate.sourceTsMs, rate.stale);
}

The result contains snapshotTsMs, optional fiat, and stablecoins. The fiat snapshot has rates, sourceTsMs, and stale; each fiat rate has code and unitsPerUsd. Each stablecoin rate has code, usdPerUnit, sourceTsMs, and stale. All timestamps are epoch milliseconds.

Unobserved rates remain absent. Before any observation exists, the rates request rejects as unavailable. Preserve absence and staleness in displays; do not substitute zero or assume a stablecoin is worth exactly one USD. Use decimal arithmetic when applying the rates.

The MarketOverview shape

list rows and each element of the subscribe array share one parsed shape. Each row carries a stable numeric symbolId; resolve its display pair through the catalog.

import type {
	SparklineIntervalName,
	MarketOverview,
	MarketOverviewSparkline,
} from "@polyester/sdk";

indexPrice is absent when the venue has no positive index value. Treat absence as unavailable, not as zero. Sparkline interval is a SparklineIntervalName ("1h" | "24h" | "1w" | "1m") plus "unspecified" on the parsed read model.

volume24hBase and volume24hQuote are absent when their scaled wire values overflow. The canonical volume24hUsd is also optional: it is absent when the 24-hour volume cannot be valued reliably. It is a decimal string in USD, based on execution prices and historical quarter-hour marks. Treat unavailable volumes separately from the known zero value "0".

Rows for unknown or disabled catalog symbols are skipped rather than rejecting the full response or stream batch.

For freshly listed pairs, change24hBps may be 0 from the API. Use getMarketOverview24hChangeDisplay(market) to derive a display change from the sparkline when a market is under 24 hours old.

Related

• Market data guide for the task-oriented walkthrough.
• Streaming guide for the subscription model.
• Candles for OHLCV series.
• Order book for depth.
• Public trades for prints.

Related Topics