GodzillaBot v0.5.5

STATUS: SUPERSEDED / ARCHIVED (2026-08-07) — Not under active development. Forward trading work lives in eternal-roman/hydra. This repo is preserved for history and reference (shadow-ledger experiments, prior dashboard). Do not open feature work here without an explicit un-archive decision.

Kraken spot trading bot: regime-based strategies, optional xAI Grok trend signals, 10 risk gates, shadow ledger (Decimal), FastAPI + React dashboard.

Repo: eternal-roman/godzilla-bot · Package: godzilla-bot · CLI: godzillabot

Not financial advice. Default mode is dry-run. Live trading can lose money. You are responsible for keys, permissions, taxes, and exchange compliance. MIT licensed — no warranty.

Quick start

git clone https://github.com/eternal-roman/godzilla-bot.git
cd godzilla-bot
pip install -r requirements.txt   # or: pip install -e ".[dev]"

cp .env.example .env              # fill KRAKEN_* and optional XAI_* / tokens

python main.py --dashboard --dry-run --port 8080   # or start_all.bat
python main.py --dry-run   # public market data OK without keys; balances need keys
# live only when ready: python main.py --live   # requires KRAKEN_* keys

Dry-run without Kraken keys uses public market data only (no balances, no private history). Dashboard and headless behave the same.

Pipeline

Market data → TA → Regime → Strategy → Risk gates → Execute
                 Grok (trend only) | rules (grid / mean reversion / cash)

Step	Behavior
Data	OHLCV via CCXT; ticker + L2 book via WS v2 (REST fallback)
TA	RSI, MACD, ATR, BB(20,2σ), EMA 9/21/55, Donchian 20/55, OBV, trend strength; multi-TF
Route	Uptrend → Grok trend; ranging → grid; down/range → MR; strong down → cash
Risk	Gates 0–9 on discretionary buys and grid deploy; MR may skip AI after HOLD (mean_reversion_exclusive)
Execute	Limit first (maker), market after timeout; basis prefers shadow lots (fee-inclusive), else FIFO

Layout

Path	Role
core/	Entities, value objects, enums
services/	TA, AI, risk, strategies, portfolio, fees, WS, learning, accounting
exchange/	Kraken adapter (CCXT + nonces)
persistence/	SQLite WAL + repositories
bot/	Dual-speed orchestrator; optional headless POST /halt
ui/	Headless console
dashboard/	FastAPI + WebSocket
frontend/	React SPA (Vite)
ledger/	Vendored double-entry kernel (shadow posts only)
main.py, config.py, config.json	Entry + settings

Modes

Mode	Command
Dashboard dry / live	python main.py --dashboard --dry-run / --live
Headless dry / live	python main.py --dry-run / --live
Backtest	python main.py --backtest --pair BTC/USD
Walk-forward	python main.py --backtest --optimize

Windows stop: Ctrl+Break (Ctrl+C is copy/paste).

Configuration

config.json (defaults in config.py):

{
  "trading": {
    "mode": "dry_run",
    "pairs": ["BTC/USD", "ETH/USD", "ADA/USD", "SOL/USD"],
    "intervals": ["1h", "4h"],
    "confidence_threshold": 0.65,
    "cycle_interval": 900,
    "position_check_interval": 60,
    "min_trade_size_usd": 10,
    "max_trade_size_usd": 5000,
    "scanner_enabled": true,
    "scanner_top_n": 5,
    "db_path": "data/godzillabot.db"
  },
  "risk": {
    "max_position_pct": 0.10,
    "max_daily_loss_pct": 0.05,
    "max_open_positions": 5,
    "stop_loss_atr_multiplier": 2.0,
    "trailing_stop_enabled": true,
    "trailing_stop_atr_multiplier": 1.5,
    "emergency_drawdown_pct": 0.10
  },
  "ai": {
    "enabled": true,
    "provider": "xai",
    "model": "grok-4-1-fast-reasoning",
    "temperature": 0.2
  },
  "reconciliation": { "enabled": true, "auto_repair": false },
  "backtest": { "slippage_pct": 0.0, "half_spread_pct": 0.0 },
  "logging": {
    "level": "INFO",
    "file_enabled": true,
    "console_enabled": true,
    "log_file": "data/godzillabot.log"
  }
}

Optional trading keys: mean_reversion_exclusive, grid_min_confidence, grid_fee_edge_multiplier, max_market_slippage_pct, admin_bind.

Fees (Kraken Pro Spot)

Authority: live TradeVolume rates when available; else volume fallback in services/fee_calculator.py.

Static table = Spot Crypto volume-only tiers (does not model Assets on Platform). Verified against Kraken fee schedule 2026-07-10 (schedule effective 2026-07-09). Round-trip = maker entry + taker exit.

30d spot vol	Maker	Taker	RT
$0+	0.40%	0.80%	1.20%
$2.5K+	0.30%	0.60%	0.90%
$10K+	0.22%	0.38%	0.60%
$25K+	0.20%	0.35%	0.55%
$50K+	0.15%	0.30%	0.45%
$100K+	0.12%	0.25%	0.37%
$250K+	0.10%	0.22%	0.32%
$500K+	0.08%	0.20%	0.28%
$1M+	0.06%	0.18%	0.24%
$2.5M+	0.04%	0.15%	0.19%
$5M+	0.02%	0.12%	0.14%
$10M+	0.00%	0.10%	0.10%
$50M+	0.00%	0.09%	0.09%
$100M+	0.00%	0.08%	0.08%
$250M+	0.00%	0.07%	0.07%
$400M+	0.00%	0.06%	0.06%
$500M+	0.00%	0.05%	0.05%

Single-leg recording: BUY stores entry fee; SELL stores exit fee. No artificial fee inflation.

Position sizing

ATR-normalized: size ≈ risk_budget / (ATR × stop_mult), ~2% portfolio risk default, capped by max_position_pct and cash reserve.

Testing & CI

python -m pytest tests/ -v

Domain VOs, fees/TA/risk/strategies, FIFO, Kraken adapter, scanner, ParameterStore, sessions, sentiment, WebSocket, backtest friction, accounting integrity, circuit breaker, admin halt.

CI: Python 3.11/3.12 + frontend production build. Dependabot: pip, npm, Actions.

Requires Python ≥ 3.11, Node 18+ for frontend build, Kraken + xAI API keys.

Troubleshooting

Symptom	Fix
Missing Kraken keys	KRAKEN_API_KEY / KRAKEN_SECRET_KEY in .env
AI key missing	XAI_API_KEY; bot stays HOLD-safe without it
Invalid nonce	Auto-retry (ns). Persistent → new key + higher nonce window
Cost basis UNKNOWN	Sync history or insert a transfer lot (below)
Windows encoding	UTF-8 set at startup; no emoji in console

External transfer (cost basis)

One transfer → one trades row. Price = USD per unit.

Field	Value
id	transfer-{ASSET}-{YYYYMMDD-HHMMSS}
pair_base / pair_quote	e.g. BTC / USD
side / order_type / status	BUY / MARKET / EXECUTED
quantity	Amount
price, executed_price	Cost basis per unit (USD)
timestamps	ISO 8601

Skip if id already exists.

Limitations

• Regime is rule-based; Grok signals trend entries only. Learning agents tune parameters, not the model.
• Stops are app-polled (10–60s), not exchange stop orders.
• Recon logs orphan open orders; does not auto-cancel them.
• Backtest: no live AI; simplified grid; optional friction only.
• Dashboard not mobile-first; most config changes need restart.
• Kraken spot only.

Security

• Secrets from .env only (see .env.example). Never commit keys.
• Dashboard defaults to 127.0.0.1. Binding 0.0.0.0 requires GODZILLABOT_DASHBOARD_TOKEN.
• With token set: mutating /api/* need Authorization: Bearer …; frontend stores token in localStorage key godzillabot_token.
• Headless halt: trading.admin_bind + GODZILLABOT_ADMIN_TOKEN → POST /halt (loopback only).
• Drawdown circuit breaker (default 10%) and emergency stop halt until process restart.
• Full policy: SECURITY.md.