quantgridbot 2.3.1

Quant-Grade Dynamic Ethereum Grid Trading and Intelligent Portfolio Rebalancing Engine with Live Dashboard Monitoring and Resilient Execution

Quant-GridBot

---

Quant-Grade Ethereum Grid Trading System with Terminal UI, Volatility-Driven Token Scoring, and Raw Transaction Execution

---

---

Overview

Quant-GridBot is a high-performance, modular Ethereum trading engine that executes adaptive grid strategies across multiple ERC20 tokens. The system features a real-time terminal dashboard, inline configuration editing, token volatility scoring, and robust transaction execution directly over RPC with raw RLP + ECDSA signing—no web3.py, no intermediaries.

---

Features

Trading Intelligence

• Adaptive Grid Execution
  Grid levels and trade triggers adapt in real time based on volatility shifts.

• Token Volatility Scoring
  Automatic scoring of ERC20 tokens using dual-cluster deviation to select optimal trading targets.

• Live ETH/Token Portfolio Rebalancer
  Automatic rebalancing when portfolio deviates beyond threshold against a stablecoin.

---

Execution Layer

• Direct RPC Transactions
  Raw transaction encoding using RLP + ECDSA — no web3.py, no abstraction.

• Safe Retry Logic
  Backoff handling for gas estimation, nonce sync, token approvals, and slippage conditions.

• Simulation Mode Support
  Toggle full dry-run simulation with exact execution logic without broadcasting to chain.

---

Terminal UI

• Live Interactive Dashboard (Rich + Prompt Toolkit)

  • Infinite scrolling banner
  • Live decision feed (BUY/SELL)
  • Scrollable logs and actions (arrow keys, PgUp/PgDn)
  • Real-time thread heartbeat

• Inline Config Prompt

  • Press Space to open
  • Commands:
    • set key value – apply changes live
    • get key – query current config value
    • reset – reserved for future reset logic

• Auto Layout Resizing
  TUI adapts to your terminal window height.

• Graceful Shutdown
  SIGINT and SIGTERM safely trigger shutdown and DB flush.

---

Installation

From Source

git clone https://github.com/LoQiseaking69/qgbot.git
cd qgbot
pip install .

From Wheel

python -m build
pip install dist/qgbot-*.whl

---

Configuration

Create a config.json in the root directory.

{
  "rpc_url": "https://mainnet.infura.io/v3/...",
  "secondary_rpc_url": "https://rpc.flashbots.net",
  "wallet_address": "0xYourWallet",
  "private_key": "0xyourprivatekey",
  "simulate": true,
  "trade_volume": 0.05,
  "grid_lower_pct": 1.5,
  "grid_upper_pct": 1.5,
  "grid_size": 12,
  "target_tokens": [
    "0x6b175474e89094c44da98b954eedeac495271d0f"
  ],
  "stablecoin_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
  "min_tokens_out": 0.01,
  "trade_cooldown": 90,
  "refresh_interval": 12,
  "rebalance_threshold": 4.5,
  "slippage_pct": 0.6
}

Use config.example.json as a template.

---

Usage

Launch System

quantgridbot

Command Line Options

Flag	Description
--simulate	Enable dry-run mode
--log-json	Enable structured JSON logs
--config	Path to custom config file

---

Project Architecture

Core Execution & Strategy

File	Role
core.py	MasterController: bootstraps, threads, monitors
grid.py	Adaptive grid bot using price polling & scoring
rebalance.py	ETH/token rebalancer based on stablecoin value
executor.py	Builds + signs + sends raw Ethereum transactions
wallet.py	Handles token/ETH balances, approvals, transfers
scorer.py	Volatility scoring engine for target selection
utils.py	Low-level RLP, EIP-155, hex, and RPC utilities
db.py	SQLite3-backed trade + event logger

Terminal UI

File	Role
main.py	TUI launcher, real-time overlay, config prompt
config_loader.py	Loads, merges, and validates config JSON

---

Runtime Flow

1. Load config and initialize modules
2. Launch background threads:
   • Grid execution
   • Rebalance logic
   • Token scorer
   • RPC executor
3. Spawn TUI overlay
4. Listen for live keyboard commands
5. Execute trades when grid level is hit
6. Log all actions to SQLite and display live

---

Roadmap

• Multi-wallet round-robin support
• Token blacklist/whitelist enforcement
• REST or WebSocket TUI over local network
• Telegram/Discord bot integration for alerts
• Metrics export to Prometheus/Grafana

---

License

BSD 3-Clause License
See LICENSE for full text.

---

Quant-GridBot is engineered for real-time, volatility-adaptive, RPC-native trading automation.
Minimal overhead. Maximal control. Institutional-grade Ethereum execution.