DeepBook V3 Margin Trading Skill

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.

Agent Skills: DeepBook V3 Margin Trading

Install this agent skill to your local

Skill Files