Prediction Trade Journal

Auto-log trades with context, track outcomes, generate calibration reports to improve trading.

Security Scan

The skill appears to do what it claims (sync trades from Simmer and store them locally), but there are small metadata/instruction inconsistencies and an undeclared pip dependency that you should review before installing.

Purpose & Capability

Name/description describe a trade journal and the code implements exactly that: polling https://api.simmer.markets, storing trades in data/trades.json, updating outcomes, exporting reports. Requesting an API key (SIMMER_API_KEY) is appropriate for this purpose. However, registry-level 'Requirements' listed at the top of the pack show none while clawhub.json and SKILL.md require SIMMER_API_KEY and a pip dependency — a metadata mismatch.

Instruction Scope

SKILL.md instructions map to the code: sync, history, report, export. The runtime instructions and code only access the Simmer API and local files in the skill directory (data/, config.json). The code does read environment variables beyond the single documented SIMMER_API_KEY (it also honors SIMMER_API_URL and SIMMER_JOURNAL_* env vars) and exposes a log_trade() integration point for other skills to add context to local records — this is expected but worth noting.

Install Mechanism

This is instruction+code with no explicit install spec, which is low-risk. However clawhub.json declares a pip dependency ('simmer-sdk') even though there's no install script in the package metadata — installing that dependency would pull third-party code from PyPI. That is a standard dependency for this purpose but should be trusted/reviewed before installation.

Credentials

The skill requires a single service credential (SIMMER_API_KEY) which is proportional to fetching trades. Additional environment variables (SIMMER_API_URL, SIMMER_JOURNAL_FETCH_LIMIT, SIMMER_JOURNAL_AUTO_SYNC) are used by the code but not all are documented in SKILL.md or clawhub.json; this is sloppy but not necessarily malicious. The skill does not request unrelated secrets or cloud credentials.

Persistence & Privilege

The skill stores data and config under its own directory (data/*.json, config.json) and does not request always:true or elevated system privileges. It can be invoked autonomously (normal default) but does not modify other skills or system-wide settings.

What to consider before installing

This package largely does what it says: it syncs trades from Simmer and saves them locally. Before installing, verify the following: 1) Confirm you trust the 'simmer-sdk' PyPI package (clawhub.json lists it) — inspect that package or install in an isolated env. 2) Protect your SIMMER_API_KEY: the skill will use it to fetch your trades; consider creating a read-only or limited API key if Simmer supports it. 3) Be aware data/trades.json and context.json are stored in the skill folder and may contain sensitive trade positions/thesis — treat or encrypt/limit access accordingly. 4) Note metadata/documentation mismatches (registry header vs. clawhub.json vs. SKILL.md): the code also uses SIMMER_API_URL and SIMMER_JOURNAL_* env vars even if not documented. 5) If you want stronger assurance, review the full tradejournal.py and the simmer-sdk dependency source, or run the skill in an isolated container/VM and monitor outbound requests (they should go to api.simmer.markets or your SIMMER_API_URL).

Track every trade, learn from outcomes, improve your edge.

When to Use This Skill

Use this skill when the user wants to:

• See their trade history
• Track win rate and P&L
• Generate trading reports
• Analyze which strategies work best

Quick Commands

# Sync trades from API
python tradejournal.py --sync

# Show recent trades
python tradejournal.py --history 10

# Generate weekly report
python tradejournal.py --report weekly

# Export to CSV
python tradejournal.py --export trades.csv

API Reference:

• Base URL: https://api.simmer.markets
• Auth: Authorization: Bearer $SIMMER_API_KEY
• Trades: GET /api/sdk/trades

How It Works

1. Sync - Polls /api/sdk/trades to fetch trade history
2. Store - Saves trades locally with outcome tracking
3. Track - Updates outcomes when markets resolve
4. Report - Generates win rate, P&L, and calibration analysis

CLI Reference

Command	Description
--sync	Fetch new trades from API
--history N	Show last N trades (default: 10)
--sync-outcomes	Update resolved markets
--report daily/weekly/monthly	Generate summary report
--config	Show configuration
--export FILE.csv	Export to CSV
--dry-run	Preview without making changes

Configuration

Setting	Environment Variable	Default
API Key	SIMMER_API_KEY	(required)

Storage

Trades are stored locally in data/trades.json:

{
  "trades": [{
    "id": "uuid",
    "market_question": "Will X happen?",
    "side": "yes",
    "shares": 10.5,
    "cost": 6.83,
    "outcome": {
      "resolved": false,
      "winning_side": null,
      "pnl_usd": null
    }
  }],
  "metadata": {
    "last_sync": "2025-01-29T...",
    "total_trades": 50
  }
}

Skill Integration

Other skills can enrich trades with context:

from tradejournal import log_trade

# After executing a trade
log_trade(
    trade_id=result['trade_id'],
    source="copytrading",
    thesis="Mirroring whale 0x123...",
    confidence=0.70
)

This adds thesis, confidence, and source to the trade record for better analysis.

Example Report

📓 Weekly Report
========================================
Period: Last 7 days
Trades: 15
Total cost: $125.50
Resolved: 8 / 15
Win rate: 62.5%
P&L: +$18.30

By side: 10 YES, 5 NO

Troubleshooting

"SIMMER_API_KEY environment variable not set"

• Set your API key: export SIMMER_API_KEY=sk_live_...

"No trades recorded yet"

• Run python tradejournal.py --sync to fetch trades from API

Trades not showing outcomes

• Run python tradejournal.py --sync-outcomes to update resolved markets