MarketDeck docs

Getting started

The shortest path from a clean machine to a running marketdeck install with paper trading and a first AI agent.

This is the fast path. You will install the CLI, run the diagnostics, add a paper wallet, and run a first analysis on a single coin. About five minutes.

What you need#

  • Node.js 20+. The CLI ships as ESM and uses node: built-ins introduced in 20.
  • git. Used to clone the repo and (optionally) update plugins.
  • A terminal. Bash, Zsh, and Fish are all supported via marketdeck completion.

Optional but recommended:

  • gnome-keyring + libsecret. Real-wallet keys are stored in the Secret Service when available; without it, an AES-GCM vault file takes over. The GNOME plugin requires libsecret either way.
  • An AI provider CLI — claude, codex, hermes, openclaw, or ollama. MarketDeck never ships its own model; it spawns the vendor's CLI and reads its output. See the providers reference for what each expects.

Quick setup#

Clone, install, link:

git clone https://git.marketdeck.io/marketdeck/marketdeck
cd marketdeck
npm install
npm link

Verify the binary is reachable on your PATH:

which marketdeck
marketdeck version

marketdeck version prints the package version, the Node version the CLI is running under, the platform/arch, the git SHA the build came from, and the default daemon socket path.

Run the diagnostics:

marketdeck doctor

The doctor walks node version, sqlite backend, DB open + schema, daemon socket, libsecret bridge, keyring file, icon cache, the HTTP log path, gsettings schema, and recent agent activity. Anything that prints [FAIL] blocks the next steps.

Add a paper wallet#

Paper wallets need no exchange account and no private key:

marketdeck wallets add --type paper --name learn --start-balance 10000

You should see the wallet listed:

marketdeck wallets list --format text

Run your first snapshot#

marketdeck snapshot BTC --format text

A successful snapshot pulls market metadata, candles, the L2 book, and funding history from Hyperliquid. The full payload comes back as one JSON object — text mode renders the headline numbers.

Add an agent#

Configure an AI agent that watches BTC every 20 minutes using Claude:

marketdeck agent add \
    --name btc-watch \
    --coins BTC \
    --provider claude \
    --interval 20

Run it once manually:

marketdeck agent run btc-watch --coin BTC

The agent fetches a snapshot, sends it to Claude with the configured system prompt, parses the response for any structured trade idea, and (for paper wallets) routes the idea through the paper-trading engine.

What to do next#