MarketDeck docs

wallets

Manage paper and real wallets — catalog, live exchange state, and signed write operations.

marketdeck wallets is the entry point for both wallet configuration and on-chain trading actions. Read paths are safe; write paths require an unlocked keyring and (for real wallets) a private key stored via the keyring backend.

Usage#

marketdeck wallets <subcommand> [args]

Read#

Subcommand	What it does
`list`	One row per wallet — id, type, name, balance.
`show <ref>`	Full record for one wallet. `<ref>` matches uuid / prefix / name.
`state <ref> [--dex NAME]`	Live Hyperliquid clearinghouse state. Pass `--dex xyz` to query a HIP-3 builder-dex bucket.
`orders <ref>`	Open limit / SL / TP orders at the exchange.
`trades [ref] [--today] [--days-back N]`	Real trade log (JSONL on disk). `<ref>` is optional — omit to scan every real wallet.

Real-wallet write#

These require the keyring to be unlocked and the wallet's private key to be stored.

Subcommand	What it does
`open <ref> <coin> --direction long\	short --leverage N --margin-pct P [--entry P] [--sl P] [--tp p1,p2,…] [--dry-run]`	Open a real perp position. Omit `--entry` for market; pass `--entry` for limit/IOC-style bracket entry. `--dry-run` validates and returns the computed plan without signing.
`limit <ref> <coin> --direction long\	short --price P --size-coin S [--reduce-only] [--tif Gtc\	Alo\	Ioc] [--dry-run]`	Place a standalone limit order. Used by manual add/partial-close flows.
`market <ref> <coin> --direction long\	short --size-coin S [--reduce-only] [--slippage-bps N] [--dry-run]`	Place a standalone market order with caller-supplied size.
`close <ref> <coin> [--slippage-bps N] [--dry-run]`	Close the live position at market.
`cancel <ref> <coin> [--oid X]`	Cancel every order for the coin, or one order with `--oid`.
`modify-triggers <ref> <coin> [--sl PRICE] [--tp p1,p2,…]`	Replace SL + TP trigger orders. Pass `--sl 0` or `--tp ""` to clear.
`transfer <ref> --to DEX --amount N [--from DEX] [--token T] [--destination 0x…]`	Move USDC between perp dexes / spot / peers.

--from="" (the default) is the main USDC perp dex; --to=xyz targets a HIP-3 builder dex. A first order on any builder dex needs a transfer to that dex first — the open path now pre-flights the dex equity check and refuses with a clear error if it's zero.

Catalog write#

Subcommand	What it does
`add --type paper\	real --name N [--start-balance B] [--exchange hyperliquid\	aster\	bybit\	binance] [--address 0x…]`	Add a wallet. `--exchange` defaults to `hyperliquid`. The credential is loaded separately via `set-secret` (HL: 0x-prefixed 32-byte private key on stdin; aster/bybit/binance: `{"apiKey":"…","apiSecret":"…"}` JSON envelope on stdin). Credentials never appear on argv.
`set-secret <ref>` / `unset-secret <ref>`	Store / wipe the per-wallet credential in the keyring. Reads from stdin so the secret never leaks through `ps`, `/proc/<pid>/cmdline`, or shell history.
`remove <ref>`	Drop the wallet from the catalog. Keys are deleted from the keyring; on-disk vault entries are wiped.
`rename <ref> <new-name>`	Cosmetic rename. ID stays the same.

For metadata-only inspection and controlled secret removal, use marketdeck secrets. It can show wallet credential status, export non-secret metadata, generate a rotation plan, and run secrets unset --scope wallet --ref <wallet> --yes without ever printing the private key or API secret.

Examples#

marketdeck wallets list --format text
marketdeck wallets state live --format json | jq .marginSummary.accountValue
marketdeck wallets state live --dex xyz
marketdeck wallets orders live --format text
marketdeck wallets open live BTC --direction long --leverage 3 --margin-pct 10 --sl 74000 --tp 82000
marketdeck wallets open live BTC --direction long --leverage 3 --margin-pct 10 --dry-run
marketdeck wallets open live ETH --direction short --leverage 5 --margin-pct 10 --max-gross-leverage 2 --min-liq-distance-pct 15
marketdeck wallets limit live BTC --direction short --price 90000 --size-coin 0.01 --reduce-only --tif Alo
marketdeck wallets limit live BTC --direction short --price 90000 --size-coin 0.01 --dry-run
marketdeck wallets market live BTC --direction short --size-coin 0.01 --reduce-only --preflight-json
marketdeck wallets close live BTC --slippage-bps 50 --dry-run
marketdeck wallets modify-triggers live ETH --sl 3500 --tp 3800,4000
marketdeck wallets transfer live --to xyz --amount 100
marketdeck wallets add --type paper --name learn --start-balance 10000
marketdeck wallets add --type real --name live --address 0xabc…
marketdeck wallets add --type real --name aster-main   --exchange aster
marketdeck wallets add --type real --name bybit-main   --exchange bybit
marketdeck wallets add --type real --name binance-main --exchange binance
echo -n '0xPRIVATEKEY…' | marketdeck wallets set-secret live
echo -n '{"apiKey":"…","apiSecret":"…"}' | marketdeck wallets set-secret binance-main
marketdeck secrets test --scope wallet --ref live
marketdeck secrets rotate-plan --scope wallet --ref live

Safety rails#

open, limit, market, and close run Trading Preflight v2 before a signed submit. The gate checks the concrete order plan against wallet state, symbol metadata, mark price, sizing, margin, open positions/orders, optional risk limits, and optional kill-switch scenario gates.
Preflight failures block the command with exit code 3. --dry-run returns the preflight payload without signing. Pass --preflight-json to include the same payload in a successful JSON response. --skip-preflight is an explicit operator override for cases where the exchange adapter itself should be the only gate.
openRealPosition (used by agent auto-trade) refuses paper wallets, refuses missing privKey, refuses missing direction, and pre-flights the HIP-3 dex equity. See the test suite for the exact list.
The /exchange audit dump in stderr redacts sz, px, limitPx, vaultAddress, destination, and amount so a syslog dump cannot reveal position sizes or transfer destinations.
Every signed action runs through the deterministic ECDSA path cross-checked against five reference vectors in exchanges/hyperliquid/self-test.js.