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

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:

• Basic Margin Trading
• Lending and Earning Interest
• Setting TP/SL Orders
• Liquidation Bot

Error Handling

Common error codes:

Network Support

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

Additional Resources

• DeepBook V3 Documentation
• Sui SDK Documentation
• Pyth Network Oracle

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