Binance Agent

SQLite-first crypto decision agent with live market capture, AI analysis, and a modern dashboard

---

Overview

Binance Agent collects live Binance market data, builds technical indicators and multi-timeframe snapshots, sends structured payloads to an OpenAI-compatible model, and stores runtime data in SQLite.

The system now uses:

• SQLite as the source of truth for settings, snapshots, AI usage, AI decisions, events, notifications, and live snapshots
• backup mirror tables inside the same SQLite database for recovery and inspection
• a live AI Decision stream in the web UI with a scrollable recent-history panel
• a FastAPI backend plus a React dashboard for day-to-day operation

This project is a decision assistant, not an execution bot. It does not place trades.

---

Screenshots

Main Dashboard

Market View

AI Decision Stream

Settings

Logs

---

What It Does

• Collects closed 1m Binance candles through the websocket collector
• Builds rolling and confirmed 5m, 10m, and 20m structures
• Computes indicators such as RSI, ATR, trend, support/resistance, breakout state, and volatility regime
• Sends a structured JSON payload to an OpenAI-compatible API
• Streams the AI response into the dashboard live
• Persists settings, snapshots, events, decisions, usage, notifications, and live snapshots in SQLite
• Mirrors runtime records into backup tables with the *_bkp suffix
• Supports Telegram notifications when a decision is marked should_notify=true
• Exposes FastAPI endpoints for dashboard, config, analysis, and maintenance

---

Architecture

Binance REST API
        |
        v
WebSocket Collector -> MarketService -> LiveSnapshot
        |                             |
        |                             +-> SQLite live_snapshots / live_snapshots_bkp
        v
Snapshot Builder -> AI Payload Builder -> OpenAI-compatible model
        |                                      |
        |                                      +-> ai_decision / ai_decision_bkp
        |                                      +-> ai_usage / ai_usage_bkp
        v
FastAPI backend -> React dashboard -> live AI Decision stream
        |
        +-> events / events_bkp
        +-> snapshots / snapshots_bkp
        +-> notifications / notifications_bkp
        +-> settings

---

Storage Model

Primary tables:

• settings
• snapshots
• ai_decision
• ai_usage
• events
• notifications
• live_snapshots

Backup mirror tables:

• snapshots_bkp
• ai_decision_bkp
• ai_usage_bkp
• events_bkp
• notifications_bkp
• live_snapshots_bkp

The backup tables live in the same SQLite file and mirror the primary inserts.

---

Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+ for the UI
• An OpenAI-compatible API key or base URL

1. Install

pip install -r requirements.txt
cd ui
npm install
cd ..

2. Configure

Create .env from .env.example and set at least:

OPENAI_API_KEY=your_key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=your_model_name
BINANCE_SYMBOL=BTCUSDT
BINANCE_INTERVAL=5m
BINANCE_MODE=manual
BINANCE_USE_SQLITE=true
BINANCE_SQLITE_PATH=data/binance_agent.sqlite3

3. Run

python binance_event_bot.py

To run the API only:

python binance_event_bot.py --api

To run the web UI:

cd ui
npm run dev

---

Runtime Modes

Mode	Behavior
manual	Runs on demand and through the dashboard
live	Streams market data continuously and updates the dashboard
continuous	Repeats snapshot collection and analysis on a delay
static	Runs a one-shot snapshot and analysis cycle

---

AI Decision Stream

The dashboard now shows the AI response as a live stream.

The AI panel:

• streams the response chunk by chunk
• keeps the last 5 responses visible in a scrollable history area
• switches to the analysis tab automatically when a run starts

This is wired through the backend streaming endpoint and the dashboard event flow.

---

AI Decision Contract

The model is expected to return structured JSON like this:

{
  "decision_id": "uuid-or-stable-id",
  "action": "BUY",
  "bias": "uptrend",
  "confidence": 0.81,
  "position_action": "enter",
  "next_state": "in_long",
  "symbol": "BTCUSDT",
  "primary_timeframe": "10m",
  "entry_trigger": "Confirmed breakout and retest with volume support.",
  "invalidation": "Exit if confirmed 5m closes back inside the broken range.",
  "wait_reason": "",
  "one_line_summary": "Confirmed breakout with aligned trend.",
  "rationale": "Multi-timeframe structure supports an entry.",
  "risk_level": "medium",
  "cooldown_seconds": 600,
  "should_notify": true,
  "report": {
    "reason": "Directional edge is present.",
    "best_timeframe": "10m",
    "support": 74890.0,
    "resistance": 75240.0,
    "current_price": 75190.0,
    "trade_direction": "higher",
    "risk_note": "Avoid if follow-through fails.",
    "regime": "trend_follow",
    "breakout_status": "confirmed_breakout",
    "pullback_status": "clean_retest",
    "volume_confirmation": "confirmed",
    "no_trade_filters": []
  }
}

---

API Endpoints

Endpoint	Method	Purpose
/health	GET	Health check
/config	GET	Runtime config
/settings	GET / PUT	Persisted settings
/snapshot	GET	Latest market snapshot
/state	GET	Current position state
/dashboard	GET	Combined dashboard payload
/decisions/recent	GET	Recent decision history
/events/recent	GET	Recent events
/errors/recent	GET	Recent errors
/snapshots/recent	GET	Recent snapshots
/notifications/recent	GET	Recent notifications
/ai/usage	GET	AI usage logs
/ai/decisions	GET	AI decision records
/agent/run	POST	Trigger analysis
/agent/stream	POST	Stream live AI output
/refresh	POST	Refresh current symbol data
/maintenance/clear	POST	Clear runtime data

---

Setup Notes

• SQLite is now the default persistence layer.
• The app also writes backup rows to *_bkp tables inside the same database.
• The old JSONL helpers are legacy and are no longer the runtime source of truth.

---

Project Layout

binance_event_bot.py
binance_agent/
ui/
data/
samples-img/
README.md
README-SETUP.md

---

License

MIT License.