MarketDeck docs
paper
Read and mutate paper-trading state — risk-free strategy runs against the live market.
Paper trading runs the same order flow as live, against the live mark price, with no exchange round-trip. Positions, P&L, and trailing stops persist in SQLite so a long-running strategy survives a restart.
Usage#
marketdeck paper <subcommand> [args]Subcommands#
| Subcommand | What it does |
|---|---|
list | One row per paper wallet (id, name, cash balance, open count). |
show <wallet> | Full state dump for one wallet — open + closed positions, equity. |
snapshot | Aggregate P&L across every paper wallet in one call. |
close <wallet> <pos-id> | Close one paper position at the current mark. |
partial <wallet> <pos-id> <pct> | Partial close by percentage of size. |
trigger <wallet> <pos-id> | Force-trigger a pending position. |
equity <wallet> [--from X] [--to Y] | Daily equity-curve snapshots. |
<wallet> accepts the wallet's UUID, a UUID prefix, or its name — the same resolver every other command uses.
Examples#
marketdeck paper list --format text
marketdeck paper show dev --format json | jq '.open_positions | length'
marketdeck paper close dev pos:dev:BTC:long:1714123456000
marketdeck paper partial dev pos:dev:BTC:long:1714123456000 50
marketdeck paper equity dev --from 2026-01-01 --to 2026-04-01How positions get opened#
The paper open write is intentionally not exposed as a top-level verb — paper positions are opened through the agent runtime, not by hand. An agent's analysis produces a structured trade idea, the runtime hands it to the paper-trading engine, and a position is written to the DB. To experiment with an idea without an agent, use marketdeck backtest or invoke runAgentHeadless through agent run.
Where state lives#
| Kind | Path |
|---|---|
| Open + closed positions | positions table |
| Equity history | paper_equity_snapshots table (one row per wallet per UTC day) |
| Frozen analysis snapshots | paper_analysis_snapshots table |
| Cash balance | wallet_state table |
Foreign keys (added in schema v10) cascade position_reviews and paper_analysis_snapshots deletions when the parent position is removed; orphaned entries no longer accumulate.