coinhunter/references/user-data-layout.md

# User Data Layout

Store private coinhunter data outside the skill directory.

## Root directory

Use:

```text
~/.coinhunter/
```

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

## Layout

```text
~/.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:

```json
{
  "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:

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

### accounts.json
Store exchange accounts and balances.

Example:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```text
~/.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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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