Skip to main content
skill CX Codex

deepbook-move — Claude Code skill: features and installation

The deepbook-move Claude Code skill guides Move contract work with DeepBook V3. It covers pools, orders, swaps, flash loans, and BalanceManager permissions.

Apache-2.0 181 installs ★ 25 updated 2026-11-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add MystenLabs/skills --skill deepbook-move -a claude-code
Open on GitHub

What deepbook-move does

The skill helps write, review, and debug Move contracts that call DeepBook V3. Its guidance covers limit and market orders, swaps that do not use a BalanceManager, flash loans, and calls combined in programmable transaction blocks. Add deepbook = { mvr = "@deepbook/core" } to Move.toml for the dependency.

It explains pool asset type ordering and the roles of TradeProof, TradeCap, DepositCap, and WithdrawCap. A FlashLoan must be consumed by its matching return call in the same transaction; otherwise, the transaction reverts. Borrowing from a pool and trading through that same pool in one transaction can fail.

What it helps with

  • write a Move contract that places a DeepBook order
  • compose a pool swap without a BalanceManager
  • debug flash-loan repayment in a transaction
  • set up BalanceManager permissions for owners and cap holders

Example prompts for the agent

  • Help me add a DeepBook limit order to this Move contract using deepbook::pool.
  • Explain how to call swap_exact_base_for_quote without a BalanceManager.
  • Check how this transaction should return its FlashLoan.

How to install deepbook-move

1Skills CLI (Vercel)

npx skills add MystenLabs/skills --skill deepbook-move -a claude-code

2Manually: put the files in place

~/.claude/skills/deepbook-move/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/deepbook-move/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about deepbook-move

How do I install deepbook-move in Claude Code?

Run npx skills add MystenLabs/skills --skill deepbook-move -a claude-code. The skill file is at ~/.claude/skills/deepbook-move/SKILL.md.

What does deepbook-move do?

It guides implementation, review, and debugging of Move contracts that use DeepBook V3, including orders, swaps, flash loans, and BalanceManager authorization.

What does deepbook-move require?

Add deepbook = { mvr = "@deepbook/core" } to Move.toml as the DeepBook dependency.

Source text

SKILL.md · Apache-2.0
---
name: deepbook-move
description: >
  Guides writing, reviewing, and debugging Move smart contracts that call DeepBook V3:
  placing limit or market orders on-chain, creating pools, swapping without a
  BalanceManager, flash loans, BalanceManager/TradeCap authorization, and composing
  DeepBook calls in programmable transaction blocks. Use when the user asks about
  deepbook::pool, place_limit_order, swap_exact_base_for_quote, borrow_flashloan_base,
  FlashLoan hot potato, TradeProof, TradeCap/DepositCap/WithdrawCap, or adding
  `deepbook = { mvr = "@deepbook/core" }` to Move.toml.
---

# DeepBook V3 Move Integration

## Setup

`Move.toml`:

```toml
[dependencies]
deepbook = { mvr = "@deepbook/core" }
```

```move
use deepbook::pool::{Self, Pool};
use deepbook::balance_manager::{Self, BalanceManager, TradeProof, TradeCap};
```

Every `Pool` function is generic over `<BaseAsset, QuoteAsset>` and the type arguments must match the pool's creation order exactly: `Pool<SUI, USDC>` is a different type from `Pool<USDC, SUI>`.

## Orders (require a BalanceManager + TradeProof)

```move
public fun place_limit_order<BaseAsset, QuoteAsset>(
    self: &mut Pool<BaseAsset, QuoteAsset>,
    balance_manager: &mut BalanceManager,
    trade_proof: &TradeProof,
    client_order_id: u64,
    order_type: u8,
    self_matching_option: u8,
    price: u64,
    quantity: u64,
    is_bid: bool,
    pay_with_deep: bool,
    expire_timestamp: u64,
    clock: &Clock,
    ctx: &mut TxContext,
): OrderInfo
```

`place_market_order` takes the same arguments minus `price` and `expire_timestamp`.
`cancel_order<BaseAsset, QuoteAsset>(pool, balance_manager, trade_proof, order_id, clock, ctx)`.

`order_type` constants: `0` = NO_RESTRICTION, `1` = IMMEDIATE_OR_CANCEL (IOC), `2` = FILL_OR_KILL (FOK), `3` = POST_ONLY.

Every order placement and cancellation needs a `TradeProof`, created in the same transaction:

```move
// owner of the BalanceManager
public fun generate_proof_as_owner(bm: &mut BalanceManager, ctx: &TxContext): TradeProof
// delegated trader holding a TradeCap
public fun generate_proof_as_trader(bm: &mut BalanceManager, trade_cap: &TradeCap, ctx: &TxContext): TradeProof
```

## Swaps (no BalanceManager, no TradeProof)

```move
public fun swap_exact_base_for_quote<BaseAsset, QuoteAsset>(
    self: &mut Pool<BaseAsset, QuoteAsset>,
    base_in: Coin<BaseAsset>,
    deep_in: Coin<DEEP>,
    min_quote_out: u64,
    clock: &Clock,
    ctx: &mut TxContext,
): (Coin<BaseAsset>, Coin<QuoteAsset>, Coin<DEEP>)

public fun swap_exact_quote_for_base<BaseAsset, QuoteAsset>(
    self: &mut Pool<BaseAsset, QuoteAsset>,
    quote_in: Coin<QuoteAsset>,
    deep_in: Coin<DEEP>,
    min_base_out: u64,
    clock: &Clock,
    ctx: &mut TxContext,
): (Coin<BaseAsset>, Coin<QuoteAsset>, Coin<DEEP>)
```

Both return three coins: leftover base, leftover quote, and unused DEEP. `deep_in` pays the taker fee — overestimating is safe because the unused DEEP is returned; underestimating aborts.

Simulate first:

```move
public fun get_quantity_out<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    base_quantity: u64,
    quote_quantity: u64,
    clock: &Clock,
): (u64, u64, u64) // (base_out, quote_out, deep_required)
```

Exactly one of `base_quantity` or `quote_quantity` must be non-zero; passing both or neither is invalid.

## Flash loans

```move
public fun borrow_flashloan_base<BaseAsset, QuoteAsset>(
    self: &mut Pool<BaseAsset, QuoteAsset>, base_amount: u64, ctx: &mut TxContext,
): (Coin<BaseAsset>, FlashLoan)

public fun borrow_flashloan_quote<BaseAsset, QuoteAsset>(
    self: &mut Pool<BaseAsset, QuoteAsset>, quote_amount: u64, ctx: &mut TxContext,
): (Coin<QuoteAsset>, FlashLoan)

public fun return_flashloan_base<BaseAsset, QuoteAsset>(
    self: &mut Pool<BaseAsset, QuoteAsset>, coin: Coin<BaseAsset>, flash_loan: FlashLoan,
)

public fun return_flashloan_quote<BaseAsset, QuoteAsset>(
    self: &mut Pool<BaseAsset, QuoteAsset>, coin: Coin<QuoteAsset>, flash_loan: FlashLoan,
)
```

`FlashLoan` has **no abilities** — it cannot be stored, copied, or dropped, so it must be consumed by the matching `return_flashloan_*` call in the same transaction. If it is not repaid the whole transaction reverts and no state change persists. The maximum borrowable amount is the pool's current holdings of that asset. There is no borrow fee; repay the exact borrowed amount.

## BalanceManager and delegation

A `BalanceManager` is a shared object that holds a user's balances and is reused across **all** pools — deposit once, trade everywhere. Two-tier authorization:

- **Owner** — full control: deposit, withdraw, mint and revoke caps, `generate_proof_as_owner`.
- **Cap holders** — `TradeCap` can only trade (`generate_proof_as_trader`); it **cannot deposit or withdraw**. `DepositCap` can only deposit, `WithdrawCap` can only withdraw.

```move
public fun new(ctx: &mut TxContext): BalanceManager
public fun mint_trade_cap(bm: &mut BalanceManager, ctx: &mut TxContext): TradeCap
public fun deposit<T>(bm: &mut BalanceManager, coin: Coin<T>, ctx: &mut TxContext)
public fun withdraw<T>(bm: &mut BalanceManager, amount: u64, ctx: &mut TxContext): Coin<T>
```

Limit: **1,000 total capabilities per BalanceManager** across TradeCap, DepositCap, and WithdrawCap combined. Beyond that, shard across multiple BalanceManagers.

## Rules and common mistakes

1. **Type parameter order.** `<USDC, SUI>` against a `Pool<SUI, USDC>` is a type mismatch; match the pool's base/quote order.
2. **Return the hot potato.** Forgetting `return_flashloan_*` compiles but aborts at runtime.
3. **Do not borrow from a pool and trade in that same pool in one transaction.** Borrowed funds are unavailable for settlement and the combined operations can fail; use a different pool or venue for the trade leg.
4. **`generate_proof_as_owner` only works from the owner address.** Delegated traders must call `generate_proof_as_trader` with a valid `TradeCap`.
5. **`generate_proof_as_trader` takes `ctx`** — `(bm, trade_cap, ctx: &TxContext)`; omitting it is a compile error.
6. **Use `_v2` variants where they exist** (e.g. `new_with_custom_owner_caps_v2`). The unsuffixed originals are stubs that `abort 1337`.
7. **Plan around the 1,000-cap limit** before building a system with many delegated trading accounts.

## Reference files

- `pool-api.md` — pool creation, order placement and cancellation, pool state queries, governance, constants.
- `balance-manager-api.md` — BalanceManager creation, cap minting and revocation, deposits/withdrawals, TradeProofs, events.
- `flash-loans.md` — borrow/return details, constraints, worked example.

Related skills: `deepbook-overview` (architecture, package addresses, pool IDs), `deepbook-sdk` (TypeScript), `sui-move` (Move fundamentals), `ptbs` (PTB composition).

If a signature is not above, read the reference file or `https://docs.sui.io/onchain-finance/deepbook/deepbookv3/contract-information` and the [deepbookv3 sources](https://github.com/MystenLabs/deepbookv3/tree/main/packages/deepbook/sources). Do not extrapolate from other protocols.

© MystenLabs · Apache-2.0 · MystenLabs/skills

Similar skills

SKILL.md skills catalog →

From the same set30

The whole set →
sui-networks-gas The sui-networks-gas Claude Code skill explains Sui networks and gas costs. It activates for questions about Mainnet, Testnet, Devnet, Localnet, gas budgets, or epochs. CX Codex +1 184installs deepbook-overview 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. CX Codex +1 183installs deepbook-sdk 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. CX Codex +1 183installs deepbook-margin The deepbook-margin Claude Code skill explains margin trading on DeepBook on Sui. It covers borrowed positions, collateral, risk ratios, and liquidation. CX Codex +1 181installs deepbook-predict This Claude Code skill covers DeepBook Predict integration for prediction markets on Sui. It explains position creation, settlement, and the liquidity pool. CX Codex +1 181installs sui-ts-sdk-backend The sui-ts-sdk-backend Claude Code skill covers backend services and agents that interact with Sui through the TypeScript SDK. It is invoked for client setup, transaction signing, package publishing, and high-throughput execution. CX Codex +1 167installs zklogin Explains zkLogin and guides its integration into Sui apps. It activates for questions about OpenID providers, address derivation, session lifetime, or security. CX Codex +1 164installs kiosk This Claude Code skill supports writing, reviewing, and debugging Move code for Sui Kiosk. It covers asset trading, NFT listings, TransferPolicy, and Kiosk extensions. CX Codex +1 162installs

Project sponsors

Companies that keep this analytics open