deepbook-sdk — Claude Code skill: features and installation
The deepbook-sdk Claude Code skill covers TypeScript integration with DeepBook V3 pools. It activates for trading apps, bots, and scripts built with @mysten/deepbook-v3.
Apache-2.0 183 installs ★ 25 updated 2026-11-12
npx skills add MystenLabs/skills --skill deepbook-sdk -a claude-codeWhat deepbook-sdk does
The skill shows how to configure a DeepBook V3 client, manage funds, and trade through the TypeScript SDK. Its guidance covers limit and market orders, swaps, order book queries, order cancellation, and fees.
References are split into client and BalanceManager setup, trading, and fees with DEEP staking. Orders draw on funds deposited into a BalanceManager; swaps use wallet Coin objects instead. Save the manager ID and reuse it across transactions.
Use the SDK’s pool and coin keys rather than hardcoded on-chain addresses. The clientOrderId value must be a numeric string. The project needs the @mysten/deepbook-v3 package.
What it helps with
- configure a DeepBook V3 client in a TypeScript app
- create and reuse a
BalanceManager - place a limit or market order
- run a swap and query the order book
- review trading fees and DEEP staking
Example prompts for the agent
- Set up a TypeScript client for trading on DeepBook V3 pools.
- Add market order placement with retry handling to my trading bot.
- Show how to cancel an order and calculate DeepBook fees.
How to install deepbook-sdk
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-sdk -a claude-code2Manually: put the files in place
~/.claude/skills/deepbook-sdk/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/deepbook-sdk/
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-sdk -a codex2Manually: put the files in place
.agents/skills/deepbook-sdk/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-sdk -a cursor2Manually: put the files in place
.cursor/skills/deepbook-sdk/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install MystenLabs/skills deepbook-sdk2Manually: put the files in place
.github/skills/deepbook-sdk/SKILL.md1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-sdk -a gemini-cli2Platform CLI
gemini skills install https://github.com/MystenLabs/skills --path deepbook-sdkManually: put the files in place
.devin/skills/deepbook-sdk/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-sdk -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about deepbook-sdk
How do I install deepbook-sdk in Claude Code?
Run npx skills add MystenLabs/skills --skill deepbook-sdk -a claude-code. The skill file is located at ~/.claude/skills/deepbook-sdk/SKILL.md.
What does deepbook-sdk do?
It guides TypeScript integrations with DeepBook V3 pools using @mysten/deepbook-v3. Topics include client setup, balances, order placement, swaps, and fees.
What does deepbook-sdk need to work?
The application uses @mysten/deepbook-v3 and a SuiGrpcClient. Orders also require funds deposited in a BalanceManager.
Source text
SKILL.md · Apache-2.0
---
name: deepbook-sdk
description: >
DeepBook V3 TypeScript SDK integration. Use when building trading applications,
bots, or scripts that interact with DeepBook pools using the @mysten/deepbook-v3
SDK. Covers client setup, BalanceManager lifecycle, placing limit and market
orders, swaps, querying order books, order management, and fee handling.
For DeepBook architecture and contract addresses, see the `deepbook-overview` skill.
For Move smart contract integration, see the `deepbook-move` skill.
---
# 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](https://docs.sui.io/onchain-finance/deepbook/deepbookv3), the [deepbook-sandbox examples](https://github.com/MystenLabs/deepbook-sandbox/tree/main/examples/sandbox), and the [deepbookv3 repository](https://github.com/MystenLabs/deepbookv3). 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
| Task | Load |
|------|------|
| Setting up a DeepBook client | client-setup |
| Creating or reusing a BalanceManager | client-setup |
| Depositing or withdrawing funds | client-setup |
| Placing a limit order | trading |
| Placing a market order | trading |
| Executing a swap | trading |
| Querying the order book | trading |
| Checking or canceling orders | trading |
| Understanding fees or staking | fees |
| Funding a BalanceManager with DEEP | fees |
| Building a complete trading bot | **all reference files** |
| Full spot trading workflow | **all reference files** |
---
## 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.
© MystenLabs · Apache-2.0 · MystenLabs/skills