DeepBook CLI Skill

Use this skill when the user wants to use deepbook end to end: market data, wallet/config setup, and on-chain execution (spot, swap, manager, margin).

Installation

Check if deepbook is installed:

deepbook --version

If not, install it:

npm install -g deepbook-cli

Setup

1. Work from the deepbook-cli project directory.
2. Ensure ~/.deepbook/config.json exists (auto-created on first run).
3. Configure global defaults in ~/.deepbook (works from any path).
4. Optional one-off overrides can still be provided via global flags.

mainnet/testnet are aliases used consistently for both provider-side reads/streams and on-chain RPC.

Global flags

• --json
• --provider
• --base-url
• --stream-base-url
• --network
• --rpc-url
• --private-key
• --address
• --manager
• --trade-cap

Available commands

• Top-level:
• deepbook providers
• deepbook pools
• deepbook orderbook (alias: deepbook book )
• deepbook trades
• deepbook ohlcv
• deepbook stream ...
• deepbook spot ...
• deepbook swap ...
• deepbook margin ...
• deepbook manager ...
• deepbook config ...
• deepbook account ...

• deepbook config:
• show
• set-network
• set-provider
• set-rpc-url
• set-address
• set-trade-cap
• set-read-key [apiKey]
• set-stream-key [apiKey]
• set-provider-base-url
• set-provider-stream-base-url
• import-key [privateKey]

• deepbook account:
• details
• list
• balance
• import [privateKey]
• use

• deepbook stream:
• trades

• deepbook spot:
• pools
• buy
• sell
• limit

• deepbook swap:
• base-for-quote
• quote-for-base

• deepbook margin:
• pools
• managers
• deposit
• market
• limit
• position
• close

• deepbook manager:
• ls
• create
• deposit
• withdraw
• balance

Command cheat sheet (required args/options)

• deepbook providers
• deepbook pools
• deepbook orderbook
• deepbook trades
• deepbook ohlcv
• deepbook stream trades
• deepbook spot pools
• deepbook spot buy --quantity [--price ] [--manager ]
• deepbook spot sell --quantity [--price ] [--manager ]
• deepbook spot limit --side --price --quantity [--manager ]
• deepbook spot limit --cancel [--manager ]

• deepbook config show
• deepbook config set-network
• deepbook config set-provider
• deepbook config set-rpc-url
• deepbook config set-address
• deepbook config set-trade-cap
• deepbook config set-read-key [apiKey] (or --stdin)
• deepbook config set-stream-key [apiKey] (or --stdin)
• deepbook config set-provider-base-url
• deepbook config set-provider-stream-base-url
• deepbook config import-key [privateKey] (or --stdin, optional --alias)

• deepbook account details
• deepbook account list
• deepbook account balance [--coin ]
• deepbook account import [privateKey] (or --stdin)
• deepbook account use

• deepbook swap base-for-quote --amount
• deepbook swap quote-for-base --amount

• deepbook margin pools
• deepbook margin managers
• deepbook margin deposit --coin --amount [--margin-manager ]
• deepbook margin market --side --quantity [--margin-manager ]
• deepbook margin limit --side --price --quantity [--margin-manager ]
• deepbook margin position [--margin-manager ]
• deepbook margin close [--margin-manager ] + either:
• --full
• OR --side --quantity

• deepbook manager ls
• deepbook manager create
• deepbook manager deposit --coin --amount [--manager ]
• deepbook manager withdraw --coin --amount [--manager ]
• deepbook manager balance --coin [--manager ]

Key margin close flags

• deepbook margin close --full --withdraw
• deepbook margin close --full --non-reduce-only
• deepbook margin close --side --quantity --reduce-only --no-repay

Swap vs spot market buy

• Swap (deepbook swap quote-for-base) is a direct pool swap with exact-input semantics.
• Spot market buy (deepbook spot buy --quantity ...) is an orderbook market order and uses a balance manager.
• CLI output now includes execution.kind and execution.type/direction so the mode is explicit.

Safety defaults

• Prefer --dry-run first for all state-changing commands.
• Validate pool key and manager object ID before placing/canceling orders.
• SUI-involved deposit/collateral paths split from gas coin inside the transaction automatically.
• Never print or log private keys.
• Margin manager type safety:
• Margin managers are generic typed objects: MarginManager.
• The margin manager type must match the exact pool pair being traded.
• Example: MarginManager works with DEEP_USDC, not DEEP_SUI.
• Margin manager resolution behavior:
• If --margin-manager is omitted, CLI auto-selects a compatible manager for that pool, or creates one in-transaction if none exists.
• If --margin-manager is provided, CLI treats it as explicit and strict: it must match signer + pool; no fallback or auto-create is performed.
• Internal margin fee buffer behavior:
• Margin market/limit orders auto-deposit a fee buffer before placing the order.
• With --no-pay-with-deep, buffer is deposited in trade asset collateral (base for sell, quote for buy).
• Without --no-pay-with-deep, buffer is deposited as DEEP into the margin manager.
• Full-close quantity normalization:
• deepbook margin close --full now auto-normalizes inferred quantity to pool lot-size/min-size.
• If reduce-only full close cannot satisfy lot-size exactly, CLI auto-switches to non-reduce-only and rounds up, then repays debt in the same transaction.
• If user explicitly passes --reduce-only, CLI keeps reduce-only semantics and errors when full close cannot be represented as a valid lot-size quantity.

End-to-end spot trading flow (fund -> buy -> withdraw)

Use this when executing a real spot trade through a balance manager.

1. Discover balance managers:
• deepbook manager ls
2. If none exist, create one:
• deepbook manager create
3. Deposit quote coin to manager (for DEEP_SUI buy, fund SUI):
• deepbook manager deposit --coin SUI --amount 1 --manager
4. Optional balance check:
• deepbook manager balance --coin SUI --manager
5. Simulate buy first:
• deepbook spot buy DEEP_SUI --quantity 38 --manager --no-pay-with-deep --dry-run
6. Execute live buy:
• deepbook spot buy DEEP_SUI --quantity 38 --manager --no-pay-with-deep
7. Withdraw purchased asset to signer address (or explicit recipient):
• deepbook manager withdraw --coin DEEP --amount 38 --manager
• optional recipient: --recipient
8. Verify manager balance:
• deepbook manager balance --coin DEEP --manager

Spot trade troubleshooting

• MoveAbort ... balance_manager::withdraw_with_proof code=3 means manager available balance is too low.
• This includes fees/reserved amounts, not just raw deposited balance.
• For spot buys, ensure quote coin is funded in manager (for DEEP_SUI, quote is SUI).
• If fees are attempted in DEEP and manager lacks DEEP, either deposit DEEP or pass --no-pay-with-deep.
• When manager is omitted, CLI resolves dynamically:
• one manager found -> uses it
• none found -> error
• multiple found -> require --manager

Typical workflow

1. Inspect pools/orderbook (deepbook spot pools, deepbook margin pools, deepbook orderbook ...).
2. Confirm manager ID (deepbook manager ls).
3. Simulate order (deepbook spot buy ... --dry-run).
4. Execute live order (same command without --dry-run).
5. Monitor with deepbook orderbook --watch and deepbook stream trades ....