DeepBook Margin API Overview
The Surflux DeepBook Margin Indexing API provides read access to DeepBook Margin, a fully onchain margin trading system built on DeepBook's shared liquidity layer on Sui. Query margin pools, margin managers, active loans, supply positions, liquidations, and more without running your own indexing infrastructure.
With the DeepBook Margin API, you can build leveraged trading interfaces, lending dashboards, liquidation bots, and risk monitoring tools without the complexity of parsing raw blockchain events or tracking margin positions manually.
What You Can Build
- Leveraged Trading Interfaces — Display margin positions, borrowed amounts, and risk ratios for traders
- Lending Dashboards — Show supply positions, interest earned, and liquidity pool stats
- Liquidation Bots — Monitor at-risk positions and execute liquidations
- Risk Monitoring Tools — Track margin health, utilization rates, and liquidation thresholds
- Portfolio Trackers — Display user's margin managers, loans, and collateral across pools
- Analytics Platforms — Analyze liquidation events, borrowing activity, and pool utilization
What is DeepBook Margin?
DeepBook Margin extends DeepBookV3 by enabling leveraged trading positions. With margin trading, users can borrow funds to increase their buying power beyond their available capital.
Key characteristics of DeepBook Margin:
- Shared Liquidity — Margin trades draw from ecosystem-wide liquidity, not isolated pools
- Composable by Default — Integrate margin via SDK or API into any application
- Fully Onchain — All execution and settlement happens onchain with transparent interest rates
- Risk Management — Built-in liquidation mechanisms protect lenders and maintain system solvency
- Collateral Flexibility — Support for multiple assets as collateral for isolated margin positions
For more details, see the Sui DeepBook Margin documentation.
Core Concepts
Margin Pools
A MarginPool manages liquidity for a single asset type (e.g., SUI or USDC). It handles:
- Supply and borrow operations with interest accrual
- Interest rate calculations based on utilization
- Protocol fees and referral distributions
Margin Managers
A MarginManager wraps a BalanceManager and enables leveraged trading. Each margin manager:
- Is associated with a specific DeepBook trading pool
- Tracks borrowed shares and collateral deposits
- Has a risk ratio that determines liquidation eligibility
Risk Ratios
Risk is measured using the formula:
Risk Ratio = Total Assets / Total Debt
Different thresholds determine allowable actions:
- Withdraw threshold (e.g., 2.0) — Minimum ratio to withdraw collateral
- Borrow threshold (e.g., 1.25) — Minimum ratio to take new loans
- Liquidation threshold (e.g., 1.15) — Below this, positions can be liquidated
Liquidations
When a margin manager's risk ratio falls below the liquidation threshold, anyone can liquidate the position. The liquidator repays debt and receives collateral plus a reward.
API Endpoints
The DeepBook Margin Indexing API includes these core endpoints:
Pool & Configuration
- Get Margin Pools — List all margin pools with interest rate parameters
- Get Registered DeepBook Pools — Get DeepBook pools enabled for margin trading with risk parameters
Position Management
- Get Margin Managers — Query margin managers by owner or filter criteria
- Get Active Loans — View active borrowed positions with risk ratios
- Get Active Supplies — Query liquidity supply positions
Events & History
- Get Liquidations — Query historical liquidation events
Capabilities & Referrals
- Get Supplier Caps — Query supplier capability objects
- Get Supply Referrals — Query supply referral objects
How It Differs from DeepBook Indexing
The DeepBook Margin API focuses on leveraged trading infrastructure while the standard DeepBook API focuses on spot trading data.
| Feature | DeepBook Margin API | DeepBook Indexing API |
|---|---|---|
| Focus | Margin positions, loans, liquidations | Order book, trades, OHLCV |
| Data type | Position state, risk metrics | Trading activity, price data |
| Key objects | MarginManager, MarginPool | Pool, Order Book |
| Use case | Leverage trading, lending | Spot trading, charting |
Use both APIs together to build complete trading interfaces that support both spot and margin trading.
Authentication
All DeepBook Margin Indexing API endpoints require authentication via an API key. Include your API key as a query parameter:
curl "https://api.surflux.dev/deepbook-margin/pools?api-key=YOUR_API_KEY"
Don't have an API key yet? Create your Surflux account to get started.
Base URL
All DeepBook Margin Indexing API endpoints use the base API URL:
https://api.surflux.dev/
Pagination
Most endpoints support pagination with these query parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
page | number | 0 | Page number (starts from 0) |
perPage | number | 10 | Items per page (max 50) |
Responses include pagination metadata:
{
"items": [...],
"isLastPage": false,
"currentPage": 0,
"perPage": 10
}
Next Steps
Ready to start querying DeepBook Margin data? Check out the endpoint documentation:
- Get Margin Pools — List all margin pools
- Get Margin Managers — Query margin positions
- Get Active Loans — View borrowed positions
- Get Liquidations — Query liquidation events
Real-Time Data: DeepBook Margin Flux Streams
For live, real-time margin events, use the DeepBook Margin Flux Streams. Stream:
- Loan Updates — Real-time loan borrowed, repaid, and liquidation events
- Manager Updates — Real-time manager creation, deposits, and withdrawals
Combine the Indexing API for historical data with Flux Streams for live updates to build complete margin trading applications.