🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί DeepBook CLI. Watch, Make & Take the Sui Market
πŸ¦€ ClawHub

DeepBook CLI. Watch, Make & Take the Sui Market

by @astinz

Operate the deepbook CLI for DeepBook reads (REST/SSE), global ~/.deepbook config/account management, on-chain spot trading, top-level swap execution, balance-manager ops, and margin trading.

Versionv0.0.1
Downloads2,206
Stars⭐ 1
#legal#productivity
TERMINAL
clawhub install deepbook-cli

πŸ“– About This Skill

name: deepbook-cli description: Operate the deepbook CLI for DeepBook reads (REST/SSE), global ~/.deepbook config/account management, on-chain spot trading, top-level swap execution, balance-manager ops, and margin trading.

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 ....

    βš™οΈ Configuration

    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.