deepbook-cli

# 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:

```bash
deepbook --version
```

If not, install it:

```bash
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 <name>`
- `--base-url <url>`
- `--stream-base-url <url>`
- `--network <mainnet|testnet>`
- `--rpc-url <url>`
- `--private-key <suiprivkey>`
- `--address <address>`
- `--manager <id>`
- `--trade-cap <id>`

## Available commands

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

- `deepbook config`:
  - `show`
  - `set-network <network>`
  - `set-provider <provider>`
  - `set-rpc-url <network> <url>`
  - `set-address <address>`
  - `set-trade-cap <id>`
  - `set-read-key [apiKey]`
  - `set-stream-key <pool> [apiKey]`
  - `set-provider-base-url <network> <url>`
  - `set-provider-stream-base-url <network> <url>`
  - `import-key [privateKey]`

- `deepbook account`:
  - `details`
  - `list`
  - `balance`
  - `import <alias> [privateKey]`
  - `use <alias>`

- `deepbook stream`:
  - `trades <pool>`

- `deepbook spot`:
  - `pools`
  - `buy <pool>`
  - `sell <pool>`
  - `limit <pool>`

- `deepbook swap`:
  - `base-for-quote <pool>`
  - `quote-for-base <pool>`

- `deepbook margin`:
  - `pools`
  - `managers`
  - `deposit <pool>`
  - `market <pool>`
  - `limit <pool>`
  - `position <pool>`
  - `close <pool>`

- `deepbook manager`:
  - `ls`
  - `create`
  - `deposit`
  - `withdraw`
  - `balance`

## Command cheat sheet (required args/options)

- `deepbook providers`
- `deepbook pools`
- `deepbook orderbook <pool>`
- `deepbook trades <pool>`
- `deepbook ohlcv <pool>`
- `deepbook stream trades <pool>`
- `deepbook spot pools`
- `deepbook spot buy <pool> --quantity <value> [--price <value>] [--manager <id>]`
- `deepbook spot sell <pool> --quantity <value> [--price <value>] [--manager <id>]`
- `deepbook spot limit <pool> --side <buy|sell> --price <value> --quantity <value> [--manager <id>]`
- `deepbook spot limit <pool> --cancel <id> [--manager <id>]`

- `deepbook config show`
- `deepbook config set-network <mainnet|testnet>`
- `deepbook config set-provider <surflux>`
- `deepbook config set-rpc-url <mainnet|testnet> <url>`
- `deepbook config set-address <address>`
- `deepbook config set-trade-cap <objectId>`
- `deepbook config set-read-key [apiKey]` (or `--stdin`)
- `deepbook config set-stream-key <pool> [apiKey]` (or `--stdin`)
- `deepbook config set-provider-base-url <mainnet|testnet> <url>`
- `deepbook config set-provider-stream-base-url <mainnet|testnet> <url>`
- `deepbook config import-key [privateKey]` (or `--stdin`, optional `--alias`)

- `deepbook account details`
- `deepbook account list`
- `deepbook account balance [--coin <SUI|USDC|DEEP|coinType>]`
- `deepbook account import <alias> [privateKey]` (or `--stdin`)
- `deepbook account use <alias>`


- `deepbook swap base-for-quote <pool> --amount <value>`
- `deepbook swap quote-for-base <pool> --amount <value>`

- `deepbook margin pools`
- `deepbook margin managers`
- `deepbook margin deposit <pool> --coin <BASE|QUOTE|DEEP|coinKey> --amount <value> [--margin-manager <id>]`
- `deepbook margin market <pool> --side <buy|sell> --quantity <value> [--margin-manager <id>]`
- `deepbook margin limit <pool> --side <buy|sell> --price <value> --quantity <value> [--margin-manager <id>]`
- `deepbook margin position <pool> [--margin-manager <id>]`
- `deepbook margin close <pool> [--margin-manager <id>]` + either:
  - `--full`
  - OR `--side <buy|sell> --quantity <value>`

- `deepbook manager ls`
- `deepbook manager create`
- `deepbook manager deposit --coin <key> --amount <value> [--manager <id>]`
- `deepbook manager withdraw --coin <key> --amount <value> [--manager <id>]`
- `deepbook manager balance --coin <key> [--manager <id>]`

## Key margin close flags

- `deepbook margin close <pool> --full --withdraw`
- `deepbook margin close <pool> --full --non-reduce-only`
- `deepbook margin close <pool> --side <buy|sell> --quantity <q> --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 <pool> --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<Base, Quote>`.
  - The margin manager type must match the exact pool pair being traded.
  - Example: `MarginManager<DEEP,USDC>` 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 <pool> --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 <id>`
4. Optional balance check:
   - `deepbook manager balance --coin SUI --manager <id>`
5. Simulate buy first:
   - `deepbook spot buy DEEP_SUI --quantity 38 --manager <id> --no-pay-with-deep --dry-run`
6. Execute live buy:
   - `deepbook spot buy DEEP_SUI --quantity 38 --manager <id> --no-pay-with-deep`
7. Withdraw purchased asset to signer address (or explicit recipient):
   - `deepbook manager withdraw --coin DEEP --amount 38 --manager <id>`
   - optional recipient: `--recipient <address>`
8. Verify manager balance:
   - `deepbook manager balance --coin DEEP --manager <id>`

## 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 <id>`


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