coinhunter/references/user-data-layout.md

User Data Layout

Store private coinhunter data outside the skill directory.

Root directory

Use:

~/.coinhunter/

This keeps personal accounts, positions, and watchlists out of packaged skill artifacts.

Layout

~/.coinhunter/
├── config.json
├── platform.json
├── accounts.json
├── positions.json
├── watchlist.json
├── notes.json
└── cache/

File roles

config.json

Store user-level defaults.

Suggested fields:

• default_exchange
• default_quote_currency
• timezone
• preferred_chains

Example:

{
  "default_exchange": "bybit",
  "default_quote_currency": "USDT",
  "timezone": "Asia/Shanghai",
  "preferred_chains": ["solana", "base"]
}

platform.json

Optional cross-platform runtime configuration. When absent, the framework defaults to Hermes behavior.

Suggested fields:

• platform — runtime name ("hermes" or "openclaw")
• scripts_dir — where platform shims are deployed
• env_file — path to the environment file for secrets
• cron_command — command array used by the external gate to trigger a job
• delivery — default delivery channel ("telegram", "webhook", etc.)

Example:

{
  "platform": "openclaw",
  "scripts_dir": "~/.openclaw/scripts",
  "env_file": "~/.openclaw/.env",
  "cron_command": ["openclaw", "trigger"],
  "delivery": "webhook"
}

accounts.json

Store exchange accounts and balances.

Example:

{
  "accounts": [
    {
      "id": "bybit-main",
      "exchange": "bybit",
      "label": "Bybit Main",
      "currency": "USDT",
      "cash_balance": 0,
      "available_cash": 0,
      "updated_at": null,
      "note": ""
    }
  ]
}

positions.json

Store coin positions.

Example:

{
  "positions": [
    {
      "account_id": "bybit-main",
      "symbol": "BTCUSDT",
      "base_asset": "BTC",
      "quote_asset": "USDT",
      "market_type": "spot",
      "quantity": 0,
      "avg_cost": 0,
      "opened_at": null,
      "updated_at": null,
      "note": ""
    }
  ]
}

watchlist.json

Store watched coins.

Example:

{
  "watchlist": [
    {
      "symbol": "FARTCOIN",
      "chain": "solana",
      "contract_address": null,
      "source": "manual",
      "status": "watching",
      "added_at": null,
      "note": ""
    }
  ]
}

notes.json

Store discretionary notes and thesis fragments.

Example:

{
  "notes": [
    {
      "symbol": "FARTCOIN",
      "title": "Why this stays on radar",
      "body": "Good liquidity, strong meme spread, only for high-risk observation.",
      "updated_at": null
    }
  ]
}

cache/

Store disposable API results or normalized snapshots. Never treat this as source-of-truth portfolio state.

Logs directory

Runtime logs live under ~/.coinhunter/logs/ as daily JSONL files:

~/.coinhunter/logs/
├── decisions_YYYYMMDD.jsonl
├── trades_YYYYMMDD.jsonl
├── predictions_YYYYMMDD.jsonl
├── errors_YYYYMMDD.jsonl
└── external_gate.log

decisions_YYYYMMDD.jsonl

One line per agent decision pass.

{
  "schema_version": "1.0",
  "decision_id": "uuid",
  "timestamp": "2026-04-16T12:00:00Z",
  "decision": "HOLD",
  "confidence": 0.75,
  "primary_reason": "BTC regime bearish",
  "positions_hash": "abc123"
}

trades_YYYYMMDD.jsonl

One line per executed trade.

{
  "schema_version": "1.0",
  "decision_id": "uuid",
  "timestamp": "2026-04-16T12:00:00Z",
  "symbol": "BTCUSDT",
  "side": "BUY",
  "quantity": 0.01,
  "price": 65000.0,
  "status": "filled"
}

predictions_YYYYMMDD.jsonl

One line per prediction made during execution. Used by the hourly review to calibrate accuracy.

{
  "schema_version": "1.0",
  "decision_id": "uuid",
  "timestamp": "2026-04-16T12:00:00Z",
  "symbol": "BTCUSDT",
  "decision": "HOLD",
  "predicted_price_low": 64000.0,
  "predicted_price_high": 67000.0,
  "predicted_direction": "neutral",
  "validation_time": "2026-04-16T16:00:00Z",
  "stop_loss": 63000.0,
  "take_profit": 68000.0,
  "confidence": 0.75
}

Rules for predictions:

• validation_time should be 4 hours after timestamp by default.
• Review logic compares validation_time price against predicted_price_low/high.
• Systematic directional misses should trigger parameter tuning recommendations.

errors_YYYYMMDD.jsonl

One line per error or reconciliation mismatch.

{
  "schema_version": "1.0",
  "decision_id": "uuid",
  "timestamp": "2026-04-16T12:00:00Z",
  "error_type": "api_timeout",
  "message": "Binance fetch_balance timed out after 30s"
}

Rules

• Keep personal data only under ~/.coinhunter/
• Never write personal account or position data into skills/coinhunter/
• Treat cache/ as disposable
• Prefer stable IDs for accounts like bybit-main
• For meme coins, include chain and contract_address when known