MarketDeck docs

agent

Configure and run AI agents — the bridge between snapshot data and a structured trade idea.

An agent ties a coin (or a set of coins) to an AI provider, a system prompt, and a cadence. Running an agent fetches a snapshot, hands it to the configured provider's CLI, parses the output for a structured trade idea, and (optionally) routes that idea into paper or real trading.

Usage#

marketdeck agent <subcommand> [args]

Read#

Subcommand	What it does
`list`	One row per configured agent.
`show <id>`	Full record for one agent — coins, prompt, schedule, last run.
`history [--agent <id>]`	Recent agent runs from the `agent_runs` table.
`due`	Agents whose interval has elapsed.
`schedule status`	Interval and next-run overview for every agent.
`dry-run <id> [--coin BTC]`	Show the run plan without calling the provider.
`providers list\	test\	models`	AI provider inventory, probe, and model enumeration.
`run <id> [--coin BTC]`	Invoke `runAgentHeadless` once. Useful for ad-hoc checks and cron.
`run-all [--due] [--parallel N]`	Run every agent, or only due agents, optionally in bounded parallel batches.
`failures [--limit N]`	Recent failed runs and retry markers.
`retry <marker-name	agent-ref>`	Re-run the agent referenced by a failure marker or agent ref.
`evaluate [--agent ID]`	Aggregate recent run quality and failure rates.
`daemonize [--user]`	Print a systemd unit for scheduled CLI-first agent execution.
`prompt show\	edit\	reset <id>`	Inspect or update the custom prompt on an agent record.

Write#

add and edit go through config-store.js so the GSettings-backed prefs UI stays in sync.

marketdeck agent add \
    --name X \
    --coins BTC,ETH \
    --provider P \
    [--interval 20] \
    [--wallet W] \
    [--mode perp|spot] \
    [--auto-trade]

marketdeck agent edit <ref> \
    [--name X] \
    [--coins A,B] \
    [--provider P] \
    [--interval N] \
    [--wallet W] \
    [--mode perp|spot] \
    [--auto-trade true|false] \
    [--prompt STR]

marketdeck agent remove <ref>

--mode defaults to perp for backward compatibility. Set --mode spot to make the agent emit BUY / SELL / HOLD actions against a wallet's spot balances instead of perp positions — see Spot mode below for the prompt schema.

<ref> resolves by uuid, uuid prefix, or name.

Examples#

marketdeck agent list --format text
marketdeck agent add --name btc-watch --coins BTC --provider claude --interval 20
marketdeck agent run btc-watch --coin BTC
marketdeck agent run-all --due --parallel 2
marketdeck agent dry-run btc-watch --coin BTC
marketdeck agent due
marketdeck agent schedule status
marketdeck agent failures --limit 20
marketdeck agent retry btc-watch
marketdeck agent evaluate --agent btc-watch
marketdeck agent daemonize --user
marketdeck agent providers list
marketdeck agent history --agent btc-watch --format text
marketdeck agent edit btc-watch --interval 30 --auto-trade true

How a run works#

Resolve the agent's coin list. If --coin was passed, run only that one; otherwise iterate the configured set.
Build a snapshot via marketdeck snapshot internals — same TTL cache, same shape.
Compose the full prompt: the agent's system prompt + the JSON snapshot + a language directive when configured.
Spawn the provider's vendor CLI — claude, codex, hermes, openclaw, or ollama run <model>. Marketdeck never sees the model's API key.
Parse the output for an **Action:** keyword line — HOLD, ADJUST_SL, ADJUST_TP, CLOSE_PARTIAL, CLOSE_FULL, or a new trade idea with direction / entry / SL / TP / leverage.
If the agent has a --wallet, route the idea into paper or real trading. Real-wallet auto-trade only fires for wallets of type real with a stored key and a passing Trading Preflight v2 gate; paper-wallet auto-trade fires unconditionally.
Append a row to agent_runs for history; emit a desktop notification when configured.

Auto-trade safety#

--auto-trade defaults to off.
Auto-trade on a real wallet checks: keyring available, key loadable, idea well-formed, daily open cap, cash balance, existing positions, notional cap, Trading Preflight v2, and HIP-3 dex equity.
A blocked real-perp agent trade is recorded in the run marker as real: "safety-preflight" with the structured real_preflight payload, so marketdeck agent history, show, and evaluate can surface safety blocks without needing exchange-side errors.
Without a --wallet, the agent only writes to analyses — no position is opened.

Spot mode#

Spot agents (--mode spot) emit a much narrower trade-idea schema and route to the spot wallet surface — paper-spot for paper wallets, the venue's spot adapter for real ones. There is no leverage, no SL/TP brackets at the entry leg, and no liquidation math.

Schema the prompt enforces (only when --auto-trade is on the section is appended automatically; otherwise the agent stays analysis-only):

**Action:** BUY | SELL | HOLD
**Symbol:** BTCUSDT          (or just BTC — runtime appends quote)
**Type:** MARKET | LIMIT
**Quantity:** 0.001 BTC      (base-asset units)
              — OR —
              100 USDT       (quote-asset units; BUY only)
**Limit Price:** 60000       (LIMIT only)
**Reasoning:** one or two sentences

Behaviour:

HOLD is treated as a clean "decline" — the run finishes, the analysis is saved, but no order is placed.
BUY debits the wallet's USDT and credits base-asset; SELL reverses. Paper wallets settle at the daemon's cached mark plus the shared paper-slippage-bps / paper-taker-fee-bps keys; limit orders ride the paper-tick loop.
Real-spot agents respect the same real-agent-autotrade-enabled master switch and real-agent-max-daily-opens cap as perp agents — daily-cap counts spot opens together with perp opens.
Existing agents keep mode='perp' implicitly; nothing changes for them.

marketdeck agent add \
    --name btc-accumulator \
    --coins BTC \
    --provider claude \
    --interval 60 \
    --wallet paper-demo \
    --mode spot \
    --auto-trade