coinhunter/references/user-data-layout.md

User Data Layout

Store private coin-hunter data outside the skill directory.

Root directory

Use:

~/.coin-hunter/

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

Layout

~/.coin-hunter/
├── config.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"]
}

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.

Rules

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