Skip to main content
skill CX Codex

deepbook-margin — Claude Code skill for margin trading

The deepbook-margin Claude Code skill explains margin trading on DeepBook on Sui. It covers borrowed positions, collateral, risk ratios, and liquidation.

Apache-2.0 181 installs ★ 25 updated 2026-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add MystenLabs/skills --skill deepbook-margin -a claude-code
Open on GitHub

What deepbook-margin does

The skill guides work on DeepBook Margin applications on Sui. It covers collateral deposits, borrowing, risk ratios, interest accrual, and position liquidation.

Its reference material is split into risk models, trading workflows, and contract parameters. Margin orders use the _v2 functions, and every margin operation requires Pyth PriceInfoObject arguments. Governance controls the risk parameters, which can change.

The skill also covers creating and reusing a MarginManager. Each manager is tied to a single DeepBook pool. It routes questions to the relevant reference files based on the task.

What it helps with

  • calculate a position’s risk ratio and borrowing capacity
  • understand when a margin position can be liquidated
  • plan a position lifecycle using a MarginManager
  • compare DeepBook margin and spot trading

Example prompts for the agent

  • Explain how to calculate risk for a DeepBook Margin position and when liquidation can occur.
  • Show the steps for opening a margin position with collateral and a loan.
  • Compare spot trading with margin trading on DeepBook.

How to install deepbook-margin

1Skills CLI (Vercel)

npx skills add MystenLabs/skills --skill deepbook-margin -a claude-code

2Manually: put the files in place

~/.claude/skills/deepbook-margin/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/deepbook-margin/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about deepbook-margin

How do I install deepbook-margin in Claude Code?

Run npx skills add MystenLabs/skills --skill deepbook-margin -a claude-code. The skill file is at ~/.claude/skills/deepbook-margin/SKILL.md.

What does deepbook-margin do?

It explains DeepBook Margin on Sui, including collateral, borrowing, position risk, interest, and liquidation. It also covers MarginManager and application integration.

What does deepbook-margin need to work?

Margin operations require Pyth PriceInfoObject arguments. The skill covers integration with DeepBook Margin on Sui.

Source text

SKILL.md · Apache-2.0
---
name: deepbook-margin
description: >
  DeepBook Margin leveraged trading on Sui. Use when building margin trading
  applications, understanding leveraged positions, risk ratios, liquidation
  mechanics, interest rate models, MarginManager lifecycle, or integrating
  margin trading into a protocol. Also use when the user asks about borrowing
  against collateral on DeepBook, margin pool parameters, or the differences
  between spot and margin trading.

  For spot trading and the DeepBook SDK, see the `deepbook-sdk` skill.
  For DeepBook architecture and contract addresses, see the `deepbook-overview` skill.
  For Move smart contract integration, see the `deepbook-move` skill.
---

# DeepBook Margin

> **MCP tool:** When available in your environment, also query the Sui documentation MCP server (`https://sui.mcp.kapa.ai`) for up-to-date answers. Use it for verification and for details not covered by these reference files.

> **Source constraint:** All information in this skill is sourced exclusively from [docs.sui.io](https://docs.sui.io/onchain-finance/deepbook/deepbook-margin) and the [deepbookv3 repository](https://github.com/MystenLabs/deepbookv3). When extending or updating this skill, only pull from these sources. Do not use third-party blogs, tutorials, or unofficial documentation.

DeepBook Margin enables leveraged trading by allowing users to post collateral, borrow from lending pools, and trade borrowed funds on spot order books. This skill covers the margin system architecture, risk model, and SDK integration. Common mistakes include ignoring continuous interest accrual on borrowed positions, not monitoring risk ratios for liquidation proximity, and creating new MarginManagers per session instead of reusing existing ones.

This skill routes to focused reference files. Load only the ones relevant to the current task.

All patterns in this skill are derived from:
  https://docs.sui.io/onchain-finance/deepbook/deepbook-margin
  https://docs.sui.io/onchain-finance/deepbook/deepbook-margin/design
  https://docs.sui.io/onchain-finance/deepbook/deepbook-margin/leveraged-workflow
  https://docs.sui.io/onchain-finance/deepbook/deepbook-margin/margin-integration
  https://docs.sui.io/onchain-finance/deepbook/deepbook-margin/margin-risks
  https://github.com/MystenLabs/deepbookv3/tree/main/packages/deepbook_margin

If unsure about any API or parameter, fetch the relevant page before answering.
Do not guess or extrapolate from other leverage protocols.

---

## Reference files

### risk-model — Risk Ratio, Interest Rates, and Liquidation
**Path:** `risk-model.md`
**Load when:** the user asks about risk ratios, leverage calculations, liquidation thresholds, interest rate formulas, the kinked utilization model, or margin risks.
**Covers:** risk ratio formula, four risk thresholds, leverage calculation table, interest rate kinked model with formulas and per-pool parameters, liquidation mechanics and rewards, oracle considerations, comprehensive risk categories.

### trading-workflow — Leveraged Position Lifecycle
**Path:** `trading-workflow.md`
**Load when:** the user wants to open, monitor, or close a leveraged position, create a MarginManager, deposit collateral, borrow funds, place margin orders, or withdraw.
**Covers:** SDK setup, MarginManager creation and reuse, reading risk parameters, checking borrow liquidity, depositing collateral, borrowing, placing margin orders, monitoring risk status, closing positions (reduce-only + repay), withdrawing collateral, troubleshooting.

### contract-info — Contract Addresses and Pool Parameters
**Path:** `contract-info.md`
**Load when:** the user needs margin package IDs, supported assets, margin pool IDs and supply caps, trading pair risk parameters, or the spot-vs-margin comparison matrix.
**Covers:** current package version, registry ID, supported tokens, margin pool configurations, trading pair risk parameters and leverage levels, spot-vs-margin structural comparison.

---

## Routing guide

| Task | Load |
|------|------|
| Understanding margin risk and liquidation | risk-model |
| Calculating leverage or risk ratio | risk-model |
| Understanding interest rates | risk-model |
| Opening a leveraged position | trading-workflow |
| Creating or reusing a MarginManager | trading-workflow |
| Depositing collateral and borrowing | trading-workflow |
| Monitoring position health | trading-workflow |
| Closing a position and withdrawing | trading-workflow |
| Looking up margin contract addresses | contract-info |
| Comparing spot vs margin integration | contract-info |
| Building a margin trading application | **all reference files** |
| Integrating margin into a protocol | **all reference files** |

---

## Skill Content

### Key concepts

- **MarginManager.** A shared object that wraps a DeepBook BalanceManager, holds collateral, and tracks borrowing. Each MarginManager is bound to exactly one DeepBook pool (isolated margin, not cross-pool).

- **Risk ratio.** The central metric: `total_assets / total_debt`. This single number controls what operations are allowed. It changes with market price movements and interest accrual.

- **Four risk thresholds.** All stored per-pool in the MarginRegistry and set by governance:
  - **Min withdraw risk ratio** — withdrawal blocked below this (typically 2.0)
  - **Min borrow risk ratio** — borrowing blocked below this; sets max leverage
  - **Target liquidation risk ratio** — liquidation restores position to this level
  - **Liquidation risk ratio** — permissionless liquidation triggered at or below this

- **Kinked interest model.** Borrow rates rise gently below optimal utilization (typically 80%), then spike sharply above it. Interest accrues at event-driven intervals (whenever pool state changes), not continuously — but the effect is that debt grows over time even when prices are stable.

- **Permissionless liquidation.** Once risk ratio reaches the liquidation threshold, anyone can liquidate the position. There is no grace period. Liquidators receive collateral rewards (typically 2%) and the pool takes additional rewards (typically 3%).

### Rules

1. **Read risk parameters on-chain.** All thresholds are governance-set and can change. Never hardcode them.
2. **Use `_v2` functions for margin orders** (`place_limit_order_v2`, `place_market_order_v2`). The unsuffixed originals are deprecated.
3. **Every margin operation requires Pyth `PriceInfoObject` arguments.** Unlike spot trading, margin has an oracle dependency for all operations (borrow, withdraw, risk reads, trading).
4. **Reuse MarginManagers.** Creating a new one per session fragments collateral across orphaned shared objects. Discover existing managers via the registry.
5. **Size borrows from risk parameters, not trial and error.** The min borrow risk ratio defines your maximum leverage per unit of collateral.
6. **`clientOrderId` must be a numeric string** (encoded as u64), same as spot.

### Common mistakes

- **Ignoring interest accrual.** Debt grows at event-driven intervals (whenever pool state changes — borrows, repays, liquidations). A position can drift toward liquidation purely from accumulated interest, even with stable prices.
- **Not monitoring risk ratio.** There is no grace period before liquidation. Integrators must surface the risk ratio and its distance to the liquidation threshold to users.
- **Creating new MarginManagers per run.** This fragments collateral. Use `findMarginManagerId` to discover existing managers before creating new ones.
- **Borrowing and trading in the same pool without oracle freshness checks.** If the Pyth price exceeds the pool's maximum age, the operation reverts.
- **Confusing margin order entry with spot.** Margin orders route through a pool proxy with risk checks, not the direct spot order entry.

© MystenLabs · Apache-2.0 · MystenLabs/skills

Similar skills

All skills for Finance and business →

From the same set30

The whole set →
move-security The move-security Claude Code skill reviews security in Sui Move contracts. It activates for package audits, access-control design, and checks involving keys or randomness. CX Codex +1 381installs sui-networks-gas The sui-networks-gas Claude Code skill explains Sui networks and gas costs. It activates for questions about Mainnet, Testnet, Devnet, Localnet, gas budgets, or epochs. CX Codex +1 184installs deepbook-overview The deepbook-overview Claude Code skill explains DeepBook V3 on Sui and its integration options. It activates for questions about the order book, pool internals, DEEP, or mainnet IDs. CX Codex +1 183installs deepbook-sdk The deepbook-sdk Claude Code skill covers TypeScript integration with DeepBook V3 pools. It activates for trading apps, bots, and scripts built with @mysten/deepbook-v3. CX Codex +1 183installs deepbook-move The deepbook-move Claude Code skill guides Move contract work with DeepBook V3. It covers pools, orders, swaps, flash loans, and BalanceManager permissions. CX Codex +1 181installs deepbook-predict This Claude Code skill covers DeepBook Predict integration for prediction markets on Sui. It explains position creation, settlement, and the liquidity pool. CX Codex +1 181installs sui-ts-sdk-backend The sui-ts-sdk-backend Claude Code skill covers backend services and agents that interact with Sui through the TypeScript SDK. It is invoked for client setup, transaction signing, package publishing, and high-throughput execution. CX Codex +1 167installs zklogin Explains zkLogin and guides its integration into Sui apps. It activates for questions about OpenID providers, address derivation, session lifetime, or security. CX Codex +1 164installs

Project sponsors

Companies that keep this analytics open