Paper Trading

SQLite-backed paper trading with immutable event logs.

Asset identity:

• symbol is required for trade/snapshot commands.
• mint is REQUIRED for snapshot and open (--mint <address>).
• If multiple positions share the same symbol, pass --mint for close/set-levels so you target the right one.
• For ETH/BTC on DEXs, use wrapped token contract addresses (WETH, WBTC/cbBTC) as the mint.

When to Use

Use this skill when the user wants to:

• paper trade ideas before live capital
• track entries/exits/stops/takes over time
• compute realized and unrealized PnL
• keep a thesis journal and periodic review

Database

Default DB path:

~/.openclaw/paper-trading.db

Override with --db <path>.

Commands

Use the script:

node --experimental-strip-types {baseDir}/scripts/paper_trading.ts --help

Environment notes:

• No npm dependency is required for SQLite (uses node:sqlite).
• Node may print ExperimentalWarning for SQLite in current versions; this is expected.

1) Initialize account

node --experimental-strip-types {baseDir}/scripts/paper_trading.ts init 
  --account main 
  --name "Main Paper Account" 
  --base-currency USD 
  --starting-balance 10000

2) Log market snapshot (for unrealized PnL)

node --experimental-strip-types {baseDir}/scripts/paper_trading.ts snapshot 
  --symbol BTC 
  --mint 6p6xgHyF7AeE6TZk8x9mNQd2r2hH7r4mYJ8t6x6hYfSR 
  --price 62000 
  --source dexscreener

3) Open position

node --experimental-strip-types {baseDir}/scripts/paper_trading.ts open 
  --account main 
  --symbol BTC 
  --mint 6p6xgHyF7AeE6TZk8x9mNQd2r2hH7r4mYJ8t6x6hYfSR 
  --side LONG 
  --qty 0.1 
  --price 62000 
  --fee 4 
  --stop-price 60500 
  --take-price 65000 
  --max-risk-pct 1.5 
  --note "Breakout + volume confirmation"

4) Update stop/take

node --experimental-strip-types {baseDir}/scripts/paper_trading.ts set-levels 
  --account main 
  --symbol BTC 
  --mint 6p6xgHyF7AeE6TZk8x9mNQd2r2hH7r4mYJ8t6x6hYfSR 
  --side LONG 
  --stop-price 61200 
  --take-price 66000 
  --note "Move stop to reduce downside"

5) Close position

node --experimental-strip-types {baseDir}/scripts/paper_trading.ts close 
  --account main 
  --symbol BTC 
  --mint 6p6xgHyF7AeE6TZk8x9mNQd2r2hH7r4mYJ8t6x6hYfSR 
  --side LONG 
  --qty 0.05 
  --price 63500 
  --fee 3 
  --note "Partial take profit"

6) Journal note

node --experimental-strip-types {baseDir}/scripts/paper_trading.ts note 
  --account main 
  --symbol BTC 
  --side LONG 
  --note "Invalidation if daily close < 61k" 
  --tags thesis risk macro

7) Portfolio status

node --experimental-strip-types {baseDir}/scripts/paper_trading.ts status --account main
node --experimental-strip-types {baseDir}/scripts/paper_trading.ts status --account main --format json --pretty

8) Weekly review

node --experimental-strip-types {baseDir}/scripts/paper_trading.ts review --account main
node --experimental-strip-types {baseDir}/scripts/paper_trading.ts review --account main --format json --pretty

Workflow

1. Keep snapshots updated for symbols with open positions, always with --mint and --source dexscreener.
2. Open trades only with explicit stop and risk cap (--max-risk-pct).
3. Log every change as an event, do not edit old events.
4. Run status after each trade and review at week end.

Notes

• Events are append-only in SQLite (events table).
• PnL is recomputed by replaying events.
• status uses the latest snapshot per symbol + mint pair for unrealized PnL.

Validation

Run the full paper-trading test suite:

node --test {baseDir}/tests/paper_trading.test.mjs