deepbook-overview — Claude Code skill: overview and install
The deepbook-overview Claude Code skill explains DeepBook V3 on Sui and its integration options. It activates for questions about the order book, pool internals, DEEP, or mainnet IDs.
Apache-2.0 183 installs ★ 25 updated 2026-11-12
npx skills add MystenLabs/skills --skill deepbook-overview -a claude-codeWhat deepbook-overview does
The skill describes DeepBook V3 as an order-book exchange on Sui, where price and submission time determine matching priority. It covers limit and market orders, then breaks down a pool: Book stores bids and asks in BigVector structures, State tracks governance, history, and accounts, while Vault handles settlement and DeepPrice conversions.
It compares three integration paths: a Move package, the TypeScript SDK with PTBs, and read-only queries through an indexer or RPC. The guide also covers DEEP fees, staking, and governance votes. Each pool sets its own tick and lot sizes; orders that miss either increment are rejected.
What it helps with
- explain how DeepBook differs from an AMM
- understand the Book, State, and Vault components
- choose an integration path for DeepBook
- learn how DEEP affects fees and governance
Example prompts for the agent
- Explain how DeepBook V3 differs from an AMM such as Uniswap.
- Break down the Book, State, and Vault parts of a DeepBook pool.
- Compare the Move package, TypeScript SDK, and read-only query options.
How to install deepbook-overview
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-overview -a claude-code2Manually: put the files in place
~/.claude/skills/deepbook-overview/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/deepbook-overview/
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-overview -a codex2Manually: put the files in place
.agents/skills/deepbook-overview/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-overview -a cursor2Manually: put the files in place
.cursor/skills/deepbook-overview/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install MystenLabs/skills deepbook-overview2Manually: put the files in place
.github/skills/deepbook-overview/SKILL.md1Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-overview -a gemini-cli2Platform CLI
gemini skills install https://github.com/MystenLabs/skills --path deepbook-overviewManually: put the files in place
.devin/skills/deepbook-overview/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add MystenLabs/skills --skill deepbook-overview -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-overview
How do I install deepbook-overview in Claude Code?
Run npx skills add MystenLabs/skills --skill deepbook-overview -a claude-code. The skill file is at ~/.claude/skills/deepbook-overview/SKILL.md.
What does deepbook-overview do?
It explains DeepBook V3’s order-book model, pool components, integration choices, and the roles of DEEP in fees and governance.
Which DeepBook integration methods does the skill cover?
It covers a Move package for on-chain logic, the TypeScript SDK and PTBs for submitting trades, and read-only queries through an indexer or RPC.
Source text
SKILL.md · Apache-2.0
---
name: deepbook-overview
description: >
Explains DeepBook V3 on Sui: the central limit order book (CLOB) design, how a Pool
is built from Book, State, and Vault, the DEEP token's role in fees, staking and
governance, the three integration models, and mainnet package and pool IDs. Use when
the user asks what DeepBook is or how it compares to an AMM like Uniswap, asks about
DeepBook Pool internals, BigVector, or order matching, asks whether to integrate via
Move package, TypeScript SDK, or read-only queries, asks about DEEP fees, staking,
whitelisted pools, or voting, or needs a DeepBook mainnet package ID, pool object ID,
coin type, or fee tier.
---
# DeepBook V3 Overview
## Quick start
| Question | Answer |
|----------|--------|
| What is it? | A central limit order book (CLOB) on Sui — **not an AMM**. Price-time priority matching, limit and market orders, discrete tick and lot sizes. No end-user interface. |
| What is a Pool made of? | **Book** (two BigVectors: bids, asks), **State** (Governance, History, Account), **Vault** (settlement + DeepPrice). |
| How do I integrate? | Move package, TypeScript SDK & PTBs, or read-only queries — see §3. |
| What is DEEP for? | Default fee token (or input token at +25%), taker-fee discounts via staking, and governance voting. |
| Mainnet v6 package | `0x337f4f4f6567fcd778d5454f27c16c70e2f274cc6377ea6249ddf491482ef497` |
Related skills: `deepbook-sdk` (TypeScript trading), `deepbook-move` (Move integration).
Reference files: `design.md` (matching/injection, governance mechanics, epoch history, full order-placement flow), `contract-info.md` (all 23 mainnet pools, every coin type and decimals, historical package versions, registry IDs).
---
## 1. Explaining DeepBook vs an AMM
State all five points:
- DeepBook V3 is a **central limit order book (CLOB)**, not an AMM — there is no bonding curve, no LP pool pricing, and no constant-product formula.
- Orders are matched by **price-time priority**: best price first, then earliest submission.
- It supports **limit orders** (rest on the book as maker) and **market orders** (take immediately), plus flash loans via a hot potato pattern within a single PTB.
- Prices move in **tick size** increments and quantities in **lot size** increments, set per pool. Orders not aligned to them are rejected. AMMs accept any continuous amount.
- DeepBook ships **no end-user interface**. It is infrastructure for trading apps, bots, and protocols.
## 2. Pool internals (Book / State / Vault)
A Pool is one market (e.g. SUI/USDC) as a Sui shared object with three components:
- **Book** — order storage and matching. Holds **two `BigVector` structures, one for bids and one for asks**. `BigVector` is implemented as a **B+ tree**, so insertion, cancellation, and in-price-order traversal stay efficient as the book grows.
- **State** — three submodules: **Governance** (fee/stake proposals and epoch voting), **History** (per-epoch volumes, fees collected, rebates), **Account** (per-user balances, stake, open orders, settled amounts).
- **Vault** — **asset settlement**: custodies pool balances, moves funds on fill and withdrawal, and maintains **DeepPrice** conversion rates so DEEP-denominated fees can be computed from the pool's own assets.
Full order placement flow, injection/matching details, and governance arithmetic: `design.md`.
## 3. Choosing an integration model
| Model | Use when | Dependency |
|-------|----------|------------|
| **Move package** | A protocol needs on-chain logic guarantees and composability with other Move packages | `deepbook = { mvr = "@deepbook/core" }` |
| **SDK & PTBs** | Apps, bots, and wallets submitting trades from TypeScript | `npm install @mysten/deepbook-v3` |
| **Read-only data** | Price and order book queries only, via indexer or RPC | None — query the endpoints directly |
Checklist for a new integration:
- [ ] Pick one model from the table above; default to **SDK & PTBs** unless on-chain composability is required.
- [ ] Create one **BalanceManager** per user and reuse it; grant `TradeCap`/`DepositCap`/`WithdrawCap` for delegated access.
- [ ] Fund the BalanceManager with the trading assets **and DEEP** (unless trading a whitelisted pool).
- [ ] Read the pool's tick size, lot size, and current taker/maker fees on-chain before sizing orders.
- [ ] Reference pools by SDK pool/coin keys, not hardcoded IDs, so the code works on mainnet and testnet.
## 4. The DEEP token
- **Default fee token.** Trading fees on non-whitelisted pools are paid in DEEP from the BalanceManager.
- **Alternative:** pay fees in the **input token at a 25% premium**.
- **Staking:** staking DEEP reduces taker fees — up to **halving** them once stake and volume thresholds are met. Maker fees are unaffected.
- **Governance:** stakers **propose and vote** on pool parameters each epoch — taker fee, maker fee, and stake requirement.
- **Whitelisted pools:** DEEP/SUI and DEEP/USDC have **0% taker and 0% maker fees**, providing gateway liquidity for DEEP.
## 5. Addresses and pools
Mainnet essentials:
- Current package (**v6**): `0x337f4f4f6567fcd778d5454f27c16c70e2f274cc6377ea6249ddf491482ef497`
- SUI/USDC pool: `0xe05dafb5133bcffb8d59f4e12465dc0e9faeaa05e3e342a08fe135800e3e4407`, **1 bps taker fee, 0 bps maker fee**
Everything else — the other mainnet pools, coin types and decimals, historical package versions, registry IDs — is in `contract-info.md`. Load it before answering any address question not listed above; do not guess an ID.
Answer style for an address lookup — give the label, the full ID, and the fee tier, no truncation:
> **DeepBook V3 mainnet package (v6):** `0x337f4f4f6567fcd778d5454f27c16c70e2f274cc6377ea6249ddf491482ef497`
> **SUI/USDC pool:** `0xe05dafb5133bcffb8d59f4e12465dc0e9faeaa05e3e342a08fe135800e3e4407` — 1 bps taker, 0 bps maker.
## Pitfalls
- **No DEEP in the BalanceManager → trades fail** on every non-whitelisted pool.
- **Hardcoded fees go stale.** Governance can change taker/maker fees and stake requirements each epoch; read them on-chain.
- **Misaligned orders are rejected.** Round price to tick size and quantity to lot size before submitting.
© MystenLabs · Apache-2.0 · MystenLabs/skills