Markets

This page covers reading markets: discovering them and their labels, a market’s whole live state at one block (its snapshot), the status and flags a UI gates its buttons on, funding for display, and the order book aggregated into price levels.

The samples assume bz connected as in Connecting, with a price source.

Listing Markets

const list = await bz.markets.listMarkets(); // cached per connection after the first call
for (const m of list) {
  console.log(m.label, m.address, m.hours, m.composite ? `composite of ${m.legSymbols.join(" and ")}` : m.legSymbols[0]);
}
const fresh = await bz.markets.listMarkets({ refresh: true }); // only markets listed since are described

const eth = await bz.markets.getMarket("eth/usd"); // a label (any case), a pair address, or a pair id
const byAddress = await bz.markets.getMarket(eth.address);

bz.markets.listMarkets(options?) returns every market the factory has deployed, in the factory’s order (factory.getAllPairs), each with the facts that never change about it. The first call reads the pair list, describes each pair (its pair id, feeds and trading calendar: two batched reads), takes the listing descriptions from the subgraph when the connection has one, and fetches the feeds’ Pyth symbols for the labels. The list is then cached on the connection: later calls make no request.

Each entry is a MarketInfo:

Labels are never taken from descriptions, which anyone listing a market writes and which could name another market.

Finding One Market

bz.markets.getMarket(ref) takes a market’s label (any case), its pair address, its pair id, or a MarketInfo (returned as is). A name the cached list does not know makes one refresh of the pair list, so a market listed since the page loaded is found. It throws an InputError on market for a name that matches nothing (“There is no market called “XYZ/USD”. Markets: BTC/USD, ETH/USD.“) or several markets (”… matches several markets (…); choose one by its address.“). Every function that takes a market accepts any of these forms.

Market Snapshots

const snap = await bz.markets.marketSnapshot(eth); // one block, two batched reads
console.log(`${snap.market.label} at block ${snap.block}: ${snap.status}`);
console.log(`stored ${formatUnits18(snap.price.spot, 2)} (${snap.price.age} s old), mark ${formatUnits18(snap.markPrice, 2)}`);
console.log(`IMR ${snap.margin.imrBp} bp, max leverage ${snap.margin.maxLeverage?.toFixed(1) ?? "-"}x`);
console.log(`OI long ${formatUnits18(snap.openInterest.longNotional, 0)} / short ${formatUnits18(snap.openInterest.shortNotional, 0)} USD`);
console.log(`insurance ${formatUnits18(snap.insurance.fund, 0)} USD, ${formatUnits18(snap.insurance.freeCapital, 0)} free`);

// Many markets at one block, in the same two batched reads.
const all = await bz.markets.marketSnapshots(list);
const live = [...all.values()].filter((s) => s.status === Status.Live);

bz.markets.marketSnapshot(market, options?) reads a market’s live state at one block: the keeper’s own state read and the snapshot’s extra reads (mark price, funding rates, the stored price’s band, ADL clocks, termination figures, the vault’s ledger, the book’s heads), in two batched calls sent together. marketSnapshots(markets, options?) does the same for many markets at once, in the same two calls, and returns a Map from address to snapshot; a market whose core reads fail is left out of the map, where marketSnapshot throws instead.

A snapshot is a plain object: keep it in state and re-render from it. Its time-dependent fields can be re-derived without a read (see Status).

Snapshot Fields

price (StoredPrice):

margin (MarginView), all in basis points of notional:

How these rates are set is in Margin.

openInterest (OpenInterestView): long and short (sizes), longNotional and shortNotional (at the stored spot), and longInventory and shortInventory (liquidated positions the vault holds, by the side they came from).

insurance (InsuranceView):

See Insurance.

adl (AdlView):

termination (TerminationView):

See Termination & Settlement and Termination.

book (BookSummary): bidHead and askHead (the best orders’ ids, 0 for an empty side), and bidCount and askCount (orders resting on each side). For price levels, see The Book.

Status

snapshot.status is one value, judged at the snapshot’s block, in this order of precedence:

The Status constant names them (Status.Live, …). In every status but live, every new order is refused, not only market orders. markets.marketStatusAt(snapshot, time) gives the status at another time without a read (for a countdown to a cutoff), and markets.adlScoreThresholdAt(snapshot, time) the ADL threshold.

Flags

The flags say what the pair refuses right now, each with the reason a UI can show next to a disabled button:

function tradeButtons(s: markets.MarketSnapshot) {
  return {
    marketOrder: { enabled: !s.marketOrdersDisabled, why: s.reasons.marketOrdersDisabled },
    // A position holder is frozen in more cases than a flat account.
    withdraw: (hasPosition: boolean) => {
      const blocked = s.allWithdrawalsPaused || (hasPosition && s.positionWithdrawalsFrozen);
      return { enabled: !blocked, why: s.allWithdrawalsPaused ? s.reasons.allWithdrawalsPaused : s.reasons.positionWithdrawalsFrozen };
    },
    // null: nothing could judge the venue (no live prices, no Pyth Pro source); false on a 24/7 market.
    venueClosed: s.venueClosed,
  };
}

// Countdowns without a new read: the status and the ADL threshold at another time.
const in30s = markets.marketStatusAt(snap, snap.timestamp + 30);
const threshold = markets.adlScoreThresholdAt(snap, snap.timestamp + 30);

snapshot.reasons has one entry per flag, null where the flag is off. An account snapshot applies the flags to the account (withdrawalBlocked). markets.marketFlags(market, state, time, venueClosed) computes them from a state read yourself.

The pair’s rules behind each flag are in Bazaar’s Oracle (closed venues), ADL and Termination chapters.

Funding

const f = snap.funding;
const perHour = Number(f.currentRatePerHour) / 1e16; // percent per hour (1e18 = 100%)
const hoursPerYear = eth.hours === "24/7" ? 8_760 : 1_700; // a trading-hours market accrues only while open
const perYear = markets.annualizedFunding(f.currentRatePerHour, hoursPerYear) * 100; // percent a year
console.log(`${perHour.toFixed(4)}%/h (${perYear.toFixed(2)}% a year), ${f.currentRatePerHour > 0n ? "longs pay shorts" : "shorts pay longs"}`);
console.log(`cap ${formatUnits18(f.maxRatePerHour * 100n)}%/h; next stored price charges ${formatUnits18(f.accruingRatePerHour * 100n, 4)}%/h`);

snapshot.funding (FundingView):

markets.annualizedFunding(ratePerHour, hoursPerYear?) gives a yearly fraction for display (0.0876 is 8.76% a year). A trading-hours market accrues funding only while its venue is open, so pass the hours it actually trades in a year (about 1,700 for a US equity) rather than the default 8,760. See Funding.

The Book

const { bids, asks } = await bz.markets.getBook(eth, 10); // ten levels a side, at one block
for (const l of asks.levels.slice().reverse()) console.log(`  ask ${formatUnits18(l.price, 2)}  ${formatUnits18(l.size, 4)}  (${l.orders})`);
for (const l of bids.levels) console.log(`  bid ${formatUnits18(l.price, 2)}  ${formatUnits18(l.size, 4)}  (${l.orders})`);
if (!bids.complete) console.log("more bids below");

const deep = await bz.markets.getBookDepth(eth, "bids", 100, { pageSize: 200, maxOrders: 5_000 });

bz.markets.getBook(market, levels?, options?) returns { bids, asks }, both sides read at one block. getBookDepth(market, side, levels?, options?) reads one side, "bids" or "asks". Each walks the side from its best order with the lens’s getBookDepth until it has seen enough distinct prices, reads the orders’ sizes in one batch, drops what is no longer live (filled, canceled, or past its expiry block but not yet swept), and sums each price level. Every read is pinned to one block.

A BookDepth has market, side, block, levels (best first: bids from the highest price down, asks from the lowest up) and complete (every level the side has is there). Each DepthLevel has price, size (remaining, 18 decimals), notional (size × price), orders (resting orders at the level) and cumulative (size from the best level through this one).

To keep a book current, re-read it when watchMarket reports bookChanged.

What Can Go Wrong

Related Pages

• Accounts & Portfolios
• Live Prices, Live Updates
• Previews
• History, for candles and trades
• Units & Constants