DeepBook V3 SDK

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, the deepbook-sandbox examples, and the deepbookv3 repository. When extending or updating this skill, only pull from these sources. Do not use third-party blogs, tutorials, or unofficial documentation.

The @mysten/deepbook-v3 SDK provides a TypeScript client for interacting with DeepBook V3 pools on Sui. This skill covers how to set up the client, manage balances, place orders, execute swaps, and handle fees. Common AI-coding mistakes include hardcoding on-chain IDs instead of using SDK pool/coin keys, creating a new BalanceManager per transaction instead of reusing one, and using non-numeric clientOrderId values.

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/deepbookv3/spot-workflow https://docs.sui.io/onchain-finance/deepbook/deepbookv3-sdk https://github.com/MystenLabs/deepbook-sandbox/tree/main/examples/sandbox

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

Reference files

client-setup — Client Initialization and BalanceManager Lifecycle

Path: client-setup.md Load when: setting up a DeepBook client, creating or reusing a BalanceManager, configuring the SDK for testnet or mainnet, or understanding the three-tier setup pattern (read-only, basic, advanced). Covers: SDK installation, SuiGrpcClient construction with $extend(deepbook({...})), keypair setup, BalanceManager creation and reuse, deposits and withdrawals, the sandbox setup patterns.

trading — Orders, Swaps, and Order Lifecycle

Path: trading.md Load when: placing limit or market orders, executing swaps, querying order books, checking order status, canceling orders, or understanding the order lifecycle. Covers: limit order placement (POSTONLY, NORESTRICTION), market order placement with retry patterns, swap functions (with and without BalanceManager), order book queries, open order queries, order cancellation, self-matching behavior, the complete order lifecycle from placement to withdrawal.

fees — Fee Structure and DEEP Staking

Path: fees.md Load when: the user asks about trading fees, DEEP token staking, fee discounts, how to fund a BalanceManager with DEEP, or how fees are calculated. Covers: DEEP vs input-token fee payment, fee calculation via DeepPrice, governance fee parameters, staking for fee discounts, acquiring testnet DEEP, referral system.

Routing guide

Skill Content

Key concepts

• DeepBook client via $extend. The SDK uses the deepbook function (imported from @mysten/deepbook-v3) with SuiGrpcClient.$extend(deepbook({...})) to add DeepBook-specific transaction builders. Methods follow a curried pattern under two namespaces: client.deepbook.deepBook.method({ params })(tx) for trading operations and client.deepbook.balanceManager.method({ params })(tx) for balance management, where tx is a Transaction object.

• Pool and coin keys. The SDK references pools and coins by string keys (e.g., "DEEP_SUI", "SUI") rather than raw on-chain addresses. The SDK maps these to the correct addresses per network.

• BalanceManager lifecycle. A BalanceManager is a shared on-chain object. Create it once, persist its ID, and reuse it across transactions. Creating a new one per transaction wastes gas and creates orphaned objects.

• Swaps vs orders. Swaps operate directly on wallet Coin objects without a BalanceManager. Orders require a BalanceManager with deposited funds.

Rules

1. Always use SDK keys for pools and coins. Never hardcode on-chain IDs — the SDK handles address resolution per network.
2. clientOrderId must be a numeric string (encoded as u64). Labels like "order-1" will fail.
3. Reuse BalanceManagers. Persist the ID from creation and pass it when constructing the client.
4. Size deposits to wallet balance. The SDK validates at build time — depositing more than the wallet holds causes an Insufficient balance error before the transaction is even submitted.
5. Handle the market maker rebalance window on localnet/sandbox. The sandbox market maker has a ~15-second rebalance cycle where liquidity temporarily disappears. Use retry helpers.

Common mistakes

• Creating a new BalanceManager every run. This creates orphaned shared objects. Check for existing managers via the indexer or persist the ID.
• Using POSTONLY for taker orders. POSTONLY guarantees the order rests on the book. If it would cross and fill, it is silently rejected — no order is returned and no error is thrown.
• Forgetting to deposit before trading. Orders draw from BalanceManager balances, not wallet balances. Funds must be deposited first.
• Not depositing DEEP for fees. On non-whitelisted pools, DEEP must be in the BalanceManager to pay fees. Without it, trades fail.
• Ignoring self-matching. When selfMatchingOption is not specified, the SDK defaults to SelfMatchingOptions.SELFMATCHINGALLOWED, which means your taker order can fill against your own resting maker orders. This is often unintentional. Explicitly set SelfMatchingOptions.CANCELTAKER or SelfMatchingOptions.CANCELMAKER to prevent self-fills.