Skip to main content

DeepBook Margin

DeepBook Margin extends DeepBookV3 with leveraged trading. You post collateral, borrow the other side of a trading pair from a lending pool, and trade the borrowed funds on the same order book that spot traders use. The borrow amplifies both your gains and your losses, and it accrues interest for as long as you hold it.

caution

Margin trading borrows funds against collateral, and liquidation is permissionless. Once your position's risk ratio reaches the pool's liquidation threshold, anyone can liquidate it, and the reward the liquidator takes from your collateral is a permanent loss. No grace period applies. Read Margin Risks before you open a position.

How leveraged trading works​

Three shared objects sit on top of the spot order book:

ObjectRole
MarginManagerYour account. It wraps a DeepBook BalanceManager, binds to one DeepBook pool, holds your collateral, and tracks your borrow.
MarginPoolThe lending pool for a single asset. Your borrow draws from it, and your interest accrues to it.
MarginRegistryGovernance state. It stores each pool's risk parameters and tracks which DeepBook pools have margin enabled.

Each MarginManager borrows from one margin pool at a time, base or quote. That is isolated margin, not a cross-pool account, which keeps risk on a single axis. See Design for the full object model.

One number governs everything you can do with a position:

risk_ratio = total_assets / total_debt

The protocol values both sides through Pyth oracles, so your risk ratio moves whenever the market moves, and it drifts down on its own as interest accrues even when prices are flat. Each pool defines four thresholds against that ratio, and the ordering liquidation < min borrow < min withdraw always holds.

ThresholdEffect
Min borrow risk ratioA borrow must leave your ratio at or above this. It sets your maximum leverage.
Min withdraw risk ratioA withdraw must leave your ratio at or above this, so you cannot pull collateral out from under an open borrow.
Liquidation risk ratioAt or below this, anyone can liquidate your position.
Target liquidation risk ratioThe ratio a liquidation restores your position to.

The min borrow risk ratio determines how much leverage a pair allows:

max_leverage ≈ 1 / (1 - 1 / min_borrow_risk_ratio)

A min borrow ratio of 1.25 permits roughly 5x, and 1.5 permits roughly 3x. Higher-volatility assets carry stricter parameters and therefore less leverage. Risk Ratio works a full position lifecycle through with numbers.

Open a leveraged position​

The path from an empty wallet to an open leveraged position is six steps. Each names the DeepBook SDK call that performs it. The Leveraged Position Workflow runs all six on Testnet with type-checked code and the result to confirm at each step.

  1. Create a MarginManager for the pool with marginManager.newMarginManager(poolKey). One call creates it, shares it, and registers it. Save the resulting object ID and reuse it, because creating a new manager each run fragments your collateral across orphaned objects.
  2. Read the pool's risk parameters from the MarginRegistry. Governance sets them per pool, so read them onchain instead of assuming the protocol defaults.
  3. Check borrow liquidity in the margin pool you intend to borrow from. A pool with no headroom under its max utilization rate rejects the borrow, and a nearly full pool charges a high interest rate.
  4. Deposit collateral with marginManager.depositBase or depositQuote. The more you deposit before borrowing, the higher your starting risk ratio.
  5. Borrow with marginManager.borrowBase or borrowQuote. The call aborts unless the resulting ratio stays at or above the min borrow risk ratio, so size the borrow from the parameters you read rather than by trial and error.
  6. Trade through the pool proxy with poolProxy.placeLimitOrder. Margin orders never use the spot order entry, because the proxy applies the risk checks that keep a borrow safe.

Closing reverses the sequence. Reduce exposure with poolProxy.placeReduceOnlyLimitOrder, repay the borrow plus accrued interest with marginManager.repayBase or repayQuote, then withdraw your collateral.

Read the parameters before you borrow​

Every threshold is a read-only query, so you can inspect a pool before committing any funds. The following helper reads all six values a position depends on, using the MarginRegistry accessors in @mysten/deepbook-v3:

examples/deepbook-margin/src/risk-params.ts
import type { DeepBookMarginClient } from './client.js';

// A pool's risk thresholds and liquidation rewards are stored per pool in the
// MarginRegistry and are set by governance, not fixed in code. Read them on
// chain rather than hardcoding: the values below differ from the protocol
// defaults and can change. `liquidation < minBorrow < minWithdraw` always holds.
export interface RiskParams {
	liquidationRiskRatio: number; // at or below this, the position can be liquidated
	minBorrowRiskRatio: number; // a borrow must leave the ratio at or above this
	minWithdrawRiskRatio: number; // a withdraw must leave the ratio at or above this
	targetLiquidationRiskRatio: number; // liquidation restores the ratio to this
	userLiquidationReward: number; // fraction of collateral paid to the liquidator
	poolLiquidationReward: number; // fraction of collateral paid to the pool
}

export async function readRiskParams(
	client: DeepBookMarginClient,
	poolKey: string,
): Promise<RiskParams> {
	const db = client.deepbook;
	const [
		liquidationRiskRatio,
		minBorrowRiskRatio,
		minWithdrawRiskRatio,
		targetLiquidationRiskRatio,
		userLiquidationReward,
		poolLiquidationReward,
	] = await Promise.all([
		db.getLiquidationRiskRatio(poolKey),
		db.getMinBorrowRiskRatio(poolKey),
		db.getMinWithdrawRiskRatio(poolKey),
		db.getTargetLiquidationRiskRatio(poolKey),
		db.getUserLiquidationReward(poolKey),
		db.getPoolLiquidationReward(poolKey),
	]);
	return {
		liquidationRiskRatio,
		minBorrowRiskRatio,
		minWithdrawRiskRatio,
		targetLiquidationRiskRatio,
		userLiquidationReward,
		poolLiquidationReward,
	};
}

Confirm the pool supports margin at all with isPoolEnabledForMargin, and monitor a live position with getMarginManagerState, which returns the oracle-priced risk ratio alongside the prices it used.

Interest and liquidation​

Your borrow accrues interest under a kinked utilization model. Rates rise gently below the kink and steeply above it, which discourages borrowing from a nearly exhausted pool. The pool applies that interest whenever its state changes, so your debt grows on its own and your risk ratio drifts down even when prices hold flat. Suppliers receive most of the interest, and a protocol spread splits the rest between referrals, the treasury, and the pool maintainer. Interest Rates covers the formulas and the accrual mechanics.

If your risk ratio falls to the liquidation threshold, a liquidator repays part of your debt and takes a reward from your collateral, sized to restore your position to the target liquidation ratio rather than to close it entirely. You keep a smaller, healthier position, minus the reward. A deeply underwater position can be fully liquidated, and the lending pool can absorb bad debt. Monitoring your ratio and acting early, by adding collateral or reducing the position, is the only defense.

To build an application on top of margin rather than trade it directly, see Integrating DeepBook Margin for the structural differences from the spot path, and the DeepBook Margin SDK reference for the TypeScript surface.