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 (POST_ONLY, NO_RESTRICTION), 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 POST_ONLY for taker orders. POST_ONLY 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.SELF_MATCHING_ALLOWED, which means your taker order can fill against your own resting maker orders. This is often unintentional. Explicitly set SelfMatchingOptions.CANCEL_TAKER or SelfMatchingOptions.CANCEL_MAKER to prevent self-fills.