DeepBook V3 Margin Trading

DeepBook V3 Margin Trading is a decentralized margin trading protocol built on Sui blockchain. It enables users to trade with leverage, lend assets to earn interest, and participate in liquidations.

Quick Start

import { SuiGrpcClient } from '@mysten/sui/grpc';
import { deepbook } from '@mysten/deepbook-v3';

const client = new SuiGrpcClient({ network: 'mainnet', baseUrl: '...' })
  .$extend(deepbook({
    address: '0x...',
    marginManagers: {
      'myManager': { address: '0x...', poolKey: 'SUI_USDC' }
    }
  }));

// Deposit and trade with leverage
const tx = new Transaction();
tx.add(client.deepbook.marginManager.depositBase({ managerKey: 'myManager', amount: 1000 }));
tx.add(client.deepbook.marginManager.borrowQuote('myManager', 2000));
tx.add(client.deepbook.poolProxy.placeLimitOrder({
  poolKey: 'SUI_USDC',
  marginManagerKey: 'myManager',
  clientOrderId: '1',
  price: 2.5,
  quantity: 400,
  isBid: true,
  payWithDeep: true
}));

Core Concepts

Architecture

Component	Purpose	Documentation
MarginManager	User's margin trading account	User Operations
MarginPool	Lending pool for specific assets	Lending Operations
MarginRegistry	Global configuration and risk parameters	Admin Operations
PoolProxy	Trading interface through margin	Trading Operations

Risk Management

Margin trading involves several risk ratios (in 9 decimal precision):

minWithdrawRiskRatio: Minimum collateral ratio for withdrawals
minBorrowRiskRatio: Minimum collateral ratio for new borrows
liquidationRiskRatio: Ratio at which positions become liquidatable
targetLiquidationRiskRatio: Target ratio after liquidation

Key Features

For Traders

Margin Trading: Place limit and market orders with borrowed funds
Take Profit / Stop Loss: Automated conditional orders

For Lenders

Supply Assets: Deposit assets to margin pools and earn interest
Referral Program: Share fees by referring suppliers

For Liquidators

Liquidation: Earn rewards by liquidating undercollateralized positions

For Admins

Pool Management: Configure pools, risk parameters, and oracle settings

SDK Reference

Configuration

// Package IDs (auto-configured by SDK)
const MARGIN_PACKAGE_ID = {
  mainnet: '0xfbd322126f1452fd4c89aedbaeb9fd0c44df9b5cedbe70d76bf80dc086031377',
  testnet: '0xd6a42f4df4db73d68cbeb52be66698d2fe6a9464f45ad113ca52b0c6ebd918b6'
};

const MARGIN_REGISTRY_ID = {
  mainnet: '0x0e40998b359a9ccbab22a98ed21bd4346abf19158bc7980c8291908086b3a742',
  testnet: '0x48d7640dfae2c6e9ceeada197a7a1643984b5a24c55a0c6c023dac77e0339f75'
};

State Queries

// Get margin manager state
const state = await client.deepbook.getMarginManagerState('myManager');

// Get pool metrics
const interestRate = await client.deepbook.getMarginPoolInterestRate('SUI');

// Check risk parameters
const liquidationRatio = await client.deepbook.getLiquidationRiskRatio('SUI_USDC');

Examples

See the examples directory for complete working examples:

Error Handling

Common error codes:

Error	Code	Description
`EInvalidDeposit`	1	Invalid deposit parameters
`EBorrowRiskRatioExceeded`	7	Borrow would exceed risk ratio
`EWithdrawRiskRatioExceeded`	8	Withdrawal would exceed risk ratio
`ECannotLiquidate`	9	Position not eligible for liquidation
`EPoolNotEnabledForMarginTrading`	15	Pool not enabled for margin

Network Support

Mainnet: Full support with production pools
Testnet: Testing environment with test assets

Additional Resources

Note: This skill assumes familiarity with Sui blockchain, Move language, and basic DeFi concepts. For TypeScript SDK basics, see the Sui TypeScript SDK documentation.

deepbook-margin-trading-skill