Previews

A preview tells a user what an order or a withdrawal will do before they sign it: the fills it meets, each fill’s fee, the collateral it needs, the position it leaves and that position’s liquidation price, the most they can withdraw, and every reason the pair would refuse. Nothing is sent.

bz.previews.previewOrder and bz.previews.previewWithdrawal read the pair (two batched reads each), then run the inputs through TypeScript ports of the pair’s own arithmetic: the matching walk, the fee schedule, the per-fill margin gate, the position transition and the creation margin check. The pure functions underneath (previews.simulateOrder and the fee and margin helpers) take every input explicitly, for a UI that already holds the pair’s state and wants to re-run them on every keystroke.

The samples assume bz connected as in Connecting, user the wallet’s address and eth a market. For the mechanics behind the numbers see Margin, Fees and Matching.

Exact and Estimated

The integer math is the contract’s, so a preview matches the transaction whenever its inputs still hold when the transaction lands. They may not: the call stores a fresh price first, which can move the funding index, the fee rates and (at most once a minute) the margin rates, and other transactions can change the book in between.

One more difference: a fill whose fees exceed what the pair’s deposits ledger can fund has its fees waived on chain; previews always charge them.

Previews value everything at the pair’s last stored price unless you pass the live one. Pass it: the call will carry a fresh print, and the stored price may be seconds or (on a quiet market) minutes old.

previewOrder

bz.previews.previewOrder(pair, account, order, opts?):

// Judge at the live price the call will carry, not the pair's last stored one.
const live = await bz.trade.livePairPrice(eth.address);
const price: previews.PriceInput = { spot: live.price.spot, low: live.price.low, high: live.price.high, publishTime: live.publishTime };

const p = await bz.previews.previewOrder(
  eth.address,
  user,
  { orderType: OrderType.Market, isLong: true, size: parseUnits18("2"), maxSlippageBp: 50n },
  { price },
);

if (p.blockers.length > 0) {
  console.log(p.blockers.map((b) => b.message)); // every reason the pair would refuse it
} else {
  console.log(`fills ${formatUnits18(p.takerSize)} at an average ${formatUnits18(p.takerAvgPrice ?? 0n, 2)}`);
  console.log(`fees ${usd(p.fees.total)}, ${usd(p.fees.toInsuranceFund)} of it to the insurance fund`);
  console.log(`needs ${usd(p.margin.requiredCollateral)} of collateral; has ${usd(p.margin.collateral)}`);
  console.log(`position after: ${formatUnits18(p.after.size)} ${p.after.isLong ? "long" : "short"}`);
  console.log(`liquidation price ~${p.after.liquidationPrice === null ? "none" : formatUnits18(p.after.liquidationPrice, 2)}`);
  if (p.canceledSize > 0n) console.log(`${formatUnits18(p.canceledSize)} canceled: ${p.cancelReason}`);
}

order is the preview’s OrderInput, the same fields as an order for createOrder with a few differences: orderType defaults to Market, tif is a number (0 GTC, 1 IOC, 2 FOK), a bounty packed into triggerPrice is ignored, there is no expiry, and integrator (default: the connection’s) can be set to see the fees with or without one.

The preview throws InputError on price when the pair has no stored price yet and none was given.

The Result

previewOrder returns an OrderPreviewResult:

margin:

A PositionView (before, after, afterArrival):

A PreviewIssue names the custom error the pair would revert with (error, its ABI name), its args, and message, the same user message a decoded revert shows (Errors & Messages). For a freeze, until is when it lifts at the latest (unix seconds) when known.

Orders That Rest

// A resting bid: what fills now, what rests, and whether the rest would pass its margin gate later.
const bid = await bz.previews.previewOrder(eth.address, user, {
  orderType: OrderType.Limit,
  isLong: true,
  size: parseUnits18("5"),
  limitPrice: parseUnits18("2950"),
});
bid.restingSize; // the part that rests in the book
bid.laterFillOk; // null when nothing rests
bid.afterArrival; // the position after this transaction only
bid.after; // ...and once the resting part has filled at its limit, as maker

For a Limit order the preview walks what crosses now, then treats the remainder: it rests (and is assumed to fill later at its limit, as maker, which after includes), or is canceled (IOC, post-only, a remainder under $5). A trigger order that has not fired is previewed at its trigger price, with assumed fills.

previewWithdrawal

bz.previews.previewWithdrawal(pair, account, amountBazaar?, opts?) gives the most the account can withdraw now and every freeze that applies, and, given an amount (BAZAAR precision), whether it goes through:

const w = await bz.previews.previewWithdrawal(eth.address, user, parseUnits18("250"), { price });
w.maxWithdrawable; // the most withdrawCollateral accepts now
w.freezes; // what stops every withdrawal now, each { error, args, message, until? }
w.ok; // whether 250 goes through
w.blocker?.message; // if not, the pair's reason: "With a position open you must keep $812.40 of collateral ..."

opts.price is the price the call will carry ({ spot, low?, high?, publishTime? }); a position is valued at the conservative edge of it, a long at low and a short at high, as the pair values a withdrawal. A negative amount throws InputError.

Running the Arithmetic Yourself

previews.simulateOrder(input) is previewOrder without the reads: it applies createOrder’s validation, its margin check, the arrival walk against book (per-fill fees, margin gates and the position after each fill), and the remainder’s disposal, and returns an OrderPreview (the result above without mark, venueClosed and feeRates). Read the state once, then call it as often as a slider moves:

// A size slider: read the pair once, then re-run the arithmetic locally on every change.
const [snap, acct] = await Promise.all([bz.markets.marketSnapshot(eth), bz.account.accountSnapshot(eth, user)]);
const rates: previews.MarginRates = { imrBp: snap.margin.imrBp, mmrBp: snap.margin.mmrBp, laggedMmrBp: snap.margin.laggedMmrBp };

function quote(size: string): previews.OrderPreview {
  return previews.simulateOrder({
    order: { orderType: OrderType.Market, isLong: true, size: parseUnits18(size), maxSlippageBp: 50n },
    account: user,
    integrator: bz.ctx.integrator,
    bucket: acct.position,
    mark: price.spot,
    fundingIndex: snap.funding.projectedIndex,
    rates,
    fees: p.feeRates, // the taker rates the full preview above read
    continuous: snap.market.continuous,
  });
}
quote("0.5").margin.shortfall; // 0n when the collateral covers it

Fees, Margin and Liquidation

const pos = acct.position;
previews.liquidationPrice(pos, snap.funding.projectedIndex, rates); // estimated; null when flat
previews.maxLeverage(rates.imrBp); // 25 at a 4% initial margin

const fee = previews.takerFillFee(parseUnits18("1"), parseUnits18("3000"), true, pos, p.feeRates, true);
previews.feeBreakdown(fee); // { insurance, integrator, total, toInsuranceFund, toIntegrator, toBugBounty }
previews.makerFillFee(parseUnits18("1"), parseUnits18("3000"), true).total; // 0.5 bp of $3,000 = $0.15

previews.takerInsuranceFeeRates(150n, 200n); // below the 2% target: the taker rate rises above the base

Rates are in EBP, 1/100 of a basis point (EBP_SCALE = 1,000,000). The constants they use are exported too (MAKER_INSURANCE_FEE_EBP, TAKER_INSURANCE_FEE_MIN_EBP, BUG_BOUNTY_TAX_BP, …).

Related Pages

• Placing Orders and Collateral: the calls these preview.
• Accounts & Portfolios: the account’s live health between previews.
• Markets: margin rates, funding and the insurance fund on a market snapshot.