Margin

Use this page when you need account health, margin requirements, transferable collateral, or liquidation estimates after you have live trader state. For account setup and trader-state subscriptions across subaccounts, see Accounts.

Join Market Prices

For margin and account health, subscribe to trader state and market stats for positions, orders, and collateral pricing markets—even when there is no position in the collateral asset. Preserve spot collateral balances and update both mark and index prices. See Native SOL collateral for the required upgrade and deposit flow. The margin examples below fetch current market prices and collateral configuration from the API. For a live view, recompute after trader-state, price, funding, or collateral-configuration updates; a previous result is a snapshot, not a live calculator.

Local Margin

Use trader-state marginInputs() and market params to compute local margin. For real-time monitoring, update market prices from WebSocket streams before recomputing.

import { MarginMarketParamsStore } from "@ellipsis-labs/rise";

const paramsStore = new MarginMarketParamsStore({
  client: client.api,
});

// Includes spot collateral parameters and pricing-market index prices.
const calculator = await paramsStore.getCalculator();
const marginInputs = resource.marginInputs();

if (marginInputs) {
  const margin = calculator.computeTraderMarginFromInputs(marginInputs);
  console.log(margin.subaccounts[0]?.margin);
}

use phoenix_rise::api::PhoenixMetadata;

let mut metadata = PhoenixMetadata::from_snapshot(http.get_exchange_snapshot().await?)?;
for row in http.markets().get_latest_markets_stats().await?.markets {
    if metadata.get_market(&row.symbol).is_some() {
        metadata.apply_market_stats_v2(&row.into())?;
    }
}
if let Some(cross) = trader.primary_subaccount() {
    let portfolio = cross.to_trader_portfolio_with_metadata(&metadata)?;
    let margin = portfolio.compute_margin(&metadata)?;

    println!(
        "maintenance margin={}",
        margin.margin.maintenance_margin.as_inner()
    );
}

Reference: Rust live margin example.

Cache-Backed Liquidation Estimates (Quote Collateral Only)

For fast UI updates and risk monitoring, estimate liquidation prices from local trader state plus the exchange cache. This avoids API polling and uses the same SDK margin primitives described above. These custom examples support quote-only collateral. They reject spot collateral instead of omitting its value. For SOL-backed accounts, use the SDK margin flow above and Hawkeye simulation for liquidation prices. The examples below binary-search the mark price where the subaccount risk tier crosses into liquidatable or worse. This keeps the estimate tied to SDK margin math, leverage tiers, funding, discounted uPnL, and limit-order margin. Treat it as a local estimate: stream freshness and search bounds matter. Use Hawkeye for the authoritative on-chain simulation. In TypeScript, the flow is client.exchange.ready(), client.exchange.market(symbol), client.marketData().market(symbol), resource.marginInputs(), then createMarginCalculator(...). In Rust, the flow is PhoenixMetadata::apply_market_stats(&stats), Trader::apply_update(&msg), SubaccountState::to_trader_portfolio(), then TraderPortfolio::compute_margin(metadata.all_perp_asset_metadata()).

import {
  createMarginCalculator,
  priceUsdToTicksWithMarketParams,
  type ExchangeMarketSnapshot,
  type MarketParams,
  type SubaccountMarginInputs,
} from "@ellipsis-labs/rise";

const bps = (value: number | undefined, fallback: number) =>
  String(value ?? fallback);

const paramsFromExchangeCache = (
  market: ExchangeMarketSnapshot,
  markPriceUsd: number
): MarketParams => ({
  symbol: market.symbol,
  assetId: market.assetId,
  markPriceTicks: priceUsdToTicksWithMarketParams(markPriceUsd, {
    tickSize: market.tickSize,
    baseLotsDecimals: market.baseLotsDecimals,
  }).toString(),
  tickSize: market.tickSize.toString(),
  baseLotDecimals: market.baseLotsDecimals,
  leverageTiers: market.leverageTiers.map((tier) => ({
    upperBoundSize: tier.maxSizeBaseLots.toString(),
    maxLeverage: String(tier.maxLeverage),
    limitOrderRiskFactorBps: String(tier.limitOrderRiskFactor),
  })),
  riskFactors: {
    maintenanceMarginFactorBps: bps(
      market.riskFactors.maintenanceBps,
      market.riskFactors.maintenance
    ),
    backstopMarginFactorBps: bps(
      market.riskFactors.backstopBps,
      market.riskFactors.backstop
    ),
    highRiskMarginFactorBps: bps(
      market.riskFactors.highRiskBps,
      market.riskFactors.highRisk
    ),
  },
  cancelOrderRiskFactorBps: bps(
    market.riskFactors.cancelOrderBps,
    market.riskFactors.cancelOrder
  ),
  upnlRiskFactor: bps(market.riskFactors.upnlBps, market.riskFactors.upnl),
  upnlRiskFactorForWithdrawals: bps(
    market.riskFactors.upnlForWithdrawalsBps,
    market.riskFactors.upnlForWithdrawals
  ),
  isolatedOnly: market.isolatedOnly,
});

const liquidationTiers = new Set([
  "liquidatable",
  "backstopLiquidatable",
  "highRisk",
]);

const estimateLiquidationPriceUsd = (
  basePositionLots: bigint,
  currentPriceUsd: number,
  crossesLiquidation: (priceUsd: number) => boolean
) => {
  if (basePositionLots === 0n || currentPriceUsd <= 0) return null;
  if (crossesLiquidation(currentPriceUsd)) return currentPriceUsd;

  if (basePositionLots > 0n) {
    let low = Math.max(currentPriceUsd / 1_000_000, Number.EPSILON);
    let high = currentPriceUsd;
    if (!crossesLiquidation(low)) return null;

    for (let i = 0; i < 48; i++) {
      const mid = (low + high) / 2;
      if (crossesLiquidation(mid)) low = mid;
      else high = mid;
    }
    return high;
  }

  let low = currentPriceUsd;
  let high = currentPriceUsd * 2;
  for (let i = 0; i < 20 && !crossesLiquidation(high); i++) {
    low = high;
    high *= 2;
  }
  if (!crossesLiquidation(high)) return null;

  for (let i = 0; i < 48; i++) {
    const mid = (low + high) / 2;
    if (crossesLiquidation(mid)) high = mid;
    else low = mid;
  }
  return high;
};

await client.exchange.ready();

const marketData = client.marketData();
const releaseMarketData = marketData.retain();
await marketData.ready();

const marginInputs = resource.marginInputs();
const subaccount = marginInputs?.subaccounts.find(
  (item) => item.subaccountIndex === 0
);
if (!subaccount) throw new Error("subaccount margin inputs are not ready");
if (
  (subaccount.spotCollaterals ?? []).some((spot) => BigInt(spot.balance) !== 0n) ||
  BigInt(subaccount.nativeSolCollateralLamports ?? "0") !== 0n
) {
  throw new Error("Use Hawkeye for SOL/spot-backed liquidation estimates");
}

const paramsBySymbol: Record<string, MarketParams> = {};
for (const marketInput of subaccount.markets) {
  const market = client.exchange.market(marketInput.symbol);
  const markPrice = marketData.market(marketInput.symbol)?.markPrice;
  if (!market || markPrice === null || markPrice === undefined) {
    throw new Error(`missing cached market data for ${marketInput.symbol}`);
  }
  paramsBySymbol[marketInput.symbol] = paramsFromExchangeCache(market, markPrice);
}

const symbol = "SOL";
const target = subaccount.markets.find((market) => market.symbol === symbol);
const basePositionLots = BigInt(target?.position?.basePositionLots ?? "0");
const currentPrice = marketData.market(symbol)?.markPrice;
if (currentPrice === null || currentPrice === undefined) {
  throw new Error(`missing mark price for ${symbol}`);
}

const crossesLiquidation = (priceUsd: number) => {
  const market = client.exchange.market(symbol);
  if (!market) throw new Error(`unknown market ${symbol}`);

  const calculator = createMarginCalculator(
    Object.values({
      ...paramsBySymbol,
      [symbol]: paramsFromExchangeCache(market, priceUsd),
    })
  );
  const result = calculator.computeSubaccountMarginFromInputs(
    subaccount as SubaccountMarginInputs
  );
  return liquidationTiers.has(result.margin.riskTier);
};

const estimatedLiquidationPriceUsd = estimateLiquidationPriceUsd(
  basePositionLots,
  currentPrice,
  crossesLiquidation
);

console.log(estimatedLiquidationPriceUsd);
releaseMarketData();

use phoenix_rise::api::PhoenixMetadata;
use phoenix_rise::math::{RiskTier, TraderPortfolio};

fn estimate_liquidation_price_usd(
    portfolio: &TraderPortfolio,
    metadata: &PhoenixMetadata,
    symbol: &str,
    current_price: f64,
) -> Result<Option<f64>, String> {
    if current_price <= 0.0 {
        return Ok(None);
    }

    let symbol = symbol.to_ascii_uppercase();
    let Some(position) = portfolio.positions.get(&symbol) else {
        return Ok(None);
    };
    if position.is_neutral() {
        return Ok(None);
    }

    let calculator = *metadata
        .get_market_calculator(&symbol)
        .ok_or_else(|| format!("missing market calculator for {symbol}"))?;
    let mut provider = metadata.all_perp_asset_metadata().clone();

    let mut crosses_liquidation = |price: f64| -> Result<bool, String> {
        let mark_price = calculator
            .price_to_ticks(price)
            .map_err(|err| format!("{err:?}"))?;
        provider
            .get_mut(&symbol)
            .ok_or_else(|| format!("missing perp metadata for {symbol}"))?
            .set_mark_price(mark_price);

        let margin = portfolio
            .compute_margin(&provider)
            .map_err(|err| err.to_string())?;
        let tier = margin.risk_tier().map_err(|err| err.to_string())?;
        Ok(tier >= RiskTier::Liquidatable)
    };

    if crosses_liquidation(current_price)? {
        return Ok(Some(current_price));
    }

    if position.is_long() {
        let mut low = (current_price / 1_000_000.0).max(0.000001);
        let mut high = current_price;
        if !crosses_liquidation(low)? {
            return Ok(None);
        }

        for _ in 0..48 {
            let mid = (low + high) / 2.0;
            if crosses_liquidation(mid)? {
                low = mid;
            } else {
                high = mid;
            }
        }
        return Ok(Some(high));
    }

    let mut low = current_price;
    let mut high = current_price * 2.0;
    for _ in 0..20 {
        if crosses_liquidation(high)? {
            break;
        }
        low = high;
        high *= 2.0;
    }
    if !crosses_liquidation(high)? {
        return Ok(None);
    }

    for _ in 0..48 {
        let mid = (low + high) / 2.0;
        if crosses_liquidation(mid)? {
            high = mid;
        } else {
            low = mid;
        }
    }
    Ok(Some(high))
}

let cross = trader
    .primary_subaccount()
    .ok_or_else(|| "trader state is not ready".to_string())?;
if cross.spot_collaterals.values().any(|spot| spot.balance != 0) {
    return Err("Use Hawkeye for SOL/spot-backed liquidation estimates".into());
}
let portfolio = cross.to_trader_portfolio()?;
let current_price = metadata
    .get_perp_asset_metadata("SOL")
    .and_then(|market| {
        metadata
            .get_market_calculator("SOL")
            .map(|calculator| calculator.ticks_to_price(market.mark_price))
    })
    .ok_or_else(|| "SOL market stats are not initialized".to_string())?;

let estimated_liquidation_price_usd =
    estimate_liquidation_price_usd(&portfolio, &metadata, "SOL", current_price)?;

println!("{estimated_liquidation_price_usd:?}");

This estimate depends on the same cache freshness as margin monitoring. In TypeScript, keep client.exchange and client.marketData() live. In Rust, keep applying PhoenixMetadata::apply_market_stats(&stats) and trader-state updates before recomputing.

Hawkeye Simulation

For an authoritative liquidation-price view, use Hawkeye simulation through the SDK. This runs a read-only simulation and decodes the program return data.

import { symbol } from "@ellipsis-labs/rise";

// `authority` is the trader owner's validated Authority address.
const margin = await client.rpc.hawkeye.viewMargin({
  authority,
  traderPdaIndex: 0,
  traderSubaccountIndex: 0,
});

const liquidation = await client.rpc.hawkeye.viewLiquidationPrice({
  authority,
  traderPdaIndex: 0,
  traderSubaccountIndex: 0,
  symbol: symbol("SOL"),
});
if (margin.err || !margin.returnData) throw new Error("Margin simulation failed");
if (liquidation.err || !liquidation.returnData) throw new Error("Liquidation simulation failed");

console.log(margin.returnData.decoded);
console.log(liquidation.returnData?.decoded.liquidationPriceTicks);

use phoenix_rise::core::{PhoenixHawkeyeClient, TraderKey};

let trader_key = TraderKey::new(authority);
let hawkeye = PhoenixHawkeyeClient::new(
    "https://api.mainnet-beta.solana.com",
    &metadata,
);

let margin = hawkeye
    .view_margin_for_trader(trader_key.pda())
    .await?;
let liquidation = hawkeye
    .view_liquidation_price_for_trader(trader_key.pda(), sol_asset_id)
    .await?;

println!("margin={:?}", margin.value);
println!(
    "liquidation price ticks={}",
    liquidation.value.liquidation_price_ticks
);

Isolated Order Estimates

Server-built isolated order routes can also return the post-trade isolated liquidation estimate.

const result = await client.api.orders().placeIsolatedMarketOrderEnhanced({
  authority: "AUTHORITY_PUBKEY",
  symbol: "SOL",
  side: "buy",
  numBaseLots: 67,
  transferAmount: 100_000_000,
  allowCrossAndIsolatedForAsset: true,
});

console.log(result.estimatedLiquidationPriceUsd);

use phoenix_rise::ix::types::{IsolatedCollateralFlow, Side};

let (ixs, estimated_liq) = http
    .orders()
    .build_isolated_market_order_tx_enhanced(
        &authority,
        "SOL",
        Side::Bid,
        67,
        Some(IsolatedCollateralFlow::TransferFromCrossMargin { collateral: 100_000_000 }),
        true,
        None,
    )
    .await?;

println!("estimated liquidation price: {:?}", estimated_liq);

Start

Trading

On-Chain Programs

Join Market Prices

Local Margin

Cache-Backed Liquidation Estimates (Quote Collateral Only)

Hawkeye Simulation

Isolated Order Estimates

​Join Market Prices

​Local Margin

​Cache-Backed Liquidation Estimates (Quote Collateral Only)

​Hawkeye Simulation

​Isolated Order Estimates

Join Market Prices

Local Margin

Cache-Backed Liquidation Estimates (Quote Collateral Only)

Hawkeye Simulation

Isolated Order Estimates