<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="vizzor_logoicon.png">
    <source media="(prefers-color-scheme: light)" srcset="vizzor_logodarkicon.png">
    <img alt="Vizzor" src="vizzor_logodarkicon.png" width="120">
  </picture>
</p>

<h1 align="center">Vizzor</h1>

<p align="center">
  <strong>See the future of crypto before it happens.</strong><br>
  <em>AI-powered price predictions with real dollar targets across every chain, token, and timeframe.</em>
</p>

<p align="center">
  <a href="https://github.com/7ayLabs/vizzor/actions/workflows/ci.yml"><img src="https://github.com/7ayLabs/vizzor/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://www.npmjs.com/package/@vizzor/cli"><img src="https://img.shields.io/npm/v/@vizzor/cli" alt="npm"></a>
  <a href="LICENSE.md"><img src="https://img.shields.io/badge/License-BUSL--1.1-blue.svg" alt="License"></a>
</p>

<p align="center">
  <a href="#get-started-in-60-seconds">Get Started</a> &bull;
  <a href="#features">Features</a> &bull;
  <a href="#autonomous-agents">Agents</a> &bull;
  <a href="#web-dashboard">Dashboard</a> &bull;
  <a href="#api">API</a> &bull;
  <a href="#supported-chains">Chains</a> &bull;
  <a href="#chronovisor-engine">ChronoVisor</a> &bull;
  <a href="#configuration">Config</a>
</p>

---

Vizzor turns raw market data into actionable crypto predictions. It pulls live feeds from 15+ exchanges, runs technical analysis on real candles, reads derivatives positioning, tracks on-chain activity, and synthesizes everything into price predictions with actual dollar targets — from 5-minute scalps to 3-month outlooks.

Ask about any coin, any token, any chain. Vizzor fetches the data, computes the signals, and gives you numbers — not opinions.

```
vizzor
> predict ETH at 16:00 today

ETH at $2,112 | Bullish | Confidence: Medium-High
  At 4:00 PM:  $2,128 (+0.8%) bull / $2,104 (-0.4%) bear
  1 day:       $2,156 (+2.1%) bull / $2,068 (-2.1%) bear
  7 days:      $2,295 (+8.7%) bull / $1,985 (-6.0%) bear
  1 month:     $2,560 (+21%) bull  / $1,840 (-13%) bear
  Support: $2,005 / $1,900  |  Resistance: $2,220 / $2,340
```

---

## Why Vizzor?

Most crypto tools show you what already happened. Vizzor shows you what's likely to happen next.

- **Not a chart tool** — it's a prediction engine that synthesizes 6 independent signal types into one composite forecast
- **Not a news aggregator** — it processes sentiment, derivatives, on-chain data, and technical indicators simultaneously
- **Not a chatbot wrapper** — every prediction is backed by real market data from 15 exchanges, with traceable reasoning and confidence scores
- **Works with everything** — BTC, ETH, SOL, meme coins, new DEX launches, tokens by contract address — if it has a price, Vizzor can predict it

---

## Get Started in 60 Seconds

```bash
npm install -g @vizzor/cli
vizzor
```

That's it. Vizzor launches a guided setup wizard that walks you through:
- Choosing your AI provider (Claude, GPT-4, Gemini, or local Ollama)
- Setting up API keys
- Picking your default chain
- Optionally installing the ChronoVisor ML engine on first run
- Learning the first commands

### Start predicting

```
> predict BTC price next week
> analyze $PEPE security and price outlook
> what's trending in crypto right now
> full microstructure analysis for ETH
> track wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
> audit contract 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984
```

### Better prediction accuracy

After setup, follow these tips for the best results:
- Enable the ChronoVisor engine during setup, or run `vizzor chronovisor setup` later
- Run `/cosmos on` for stricter tracked-only qualification and fewer low-edge setups
- For intraday: focus on `BTC`, `ETH`, and `SOL` with `2h`, `3h`, `4h`, `6h` horizons
- For scalping: focus on `BTC` and `ETH` with exact short horizons like `10m`, `20m`, `45m`
- For long-range: ask for `7d`, `30d`, `90d`, or `1y` scenario ranges
- Use `/precisions` to check tracked accuracy and `/playbook` for the full operating workflow

### Alternative setups

<details>
<summary><b>Ollama (free, offline, no API key needed)</b></summary>

```bash
# 1. Install Ollama: https://ollama.ai
ollama pull llama3.2    # or qwen2.5:14b for better results

# 2. Configure Vizzor
vizzor config set ai.provider ollama
vizzor config set ai.model llama3.2

# 3. Launch
vizzor
```
</details>

<details>
<summary><b>OpenAI or Gemini</b></summary>

```bash
vizzor config set ai.provider openai
vizzor config set openaiApiKey sk-...
# or
vizzor config set ai.provider gemini
vizzor config set googleApiKey AI...
```
</details>

<details>
<summary><b>From source</b></summary>

```bash
git clone https://github.com/7ayLabs/vizzor.git
cd vizzor
pnpm install
pnpm build
pnpm link --global
```
</details>

<details>
<summary><b>Docker (full stack)</b></summary>

```bash
cp .env.example .env     # Configure API keys
docker compose up -d      # Starts CLI + ChronoVisor Engine + PostgreSQL + Web Dashboard
```
</details>

---

## Features

### Predictions & Forecasting

| Feature | What it does |
|---------|-------------|
| **Price predictions** | Bull/bear/likely targets across 9 timeframes (5m to 3 months), batch multi-horizon in a single call |
| **ChronoVisor engine** | Mathematical prediction system: Bayesian inference, certainty-factor algebra with weak signal dampening, first-order logic rules (17 base + 7 scalping), meta-reasoning, and continuous weight learning with feedback loops |
| **Alert-hit notifications** | Toast banners when price targets hit, with training feedback (accuracy, streak, weight updates), ESC-to-dismiss, auto-dismiss |
| **Prediction markets** | Integrates Gamma and Polymarket data for market-implied probabilities |
| **Polymarket edge scanning** | Compare ChronoVisor predictions vs Polymarket odds, detect mispricings, execute trades via CLOB API |

### Market Intelligence

| Feature | What it does |
|---------|-------------|
| **Multi-exchange pricing** | Aggregated prices from 15 exchanges (Binance, Coinbase, Kraken, OKX, Bybit, Gate.io, KuCoin, HTX, MEXC, Bitget, CoinGecko, CryptoCompare, DexScreener, GeckoTerminal, Jupiter) with VWAP/median aggregation and outlier detection |
| **Microstructure analysis** | Market structure, FVGs, VWAP, volume delta, liquidation map, order book depth, S/R zones, squeeze detection |
| **Derivatives positioning** | Funding rates, open interest, long/short ratios from Binance Futures |
| **Sentiment analysis** | Fear & Greed Index + news sentiment + buy/sell transaction ratios |
| **Trending discovery** | What's moving right now across DexScreener and CoinGecko |
| **ICO tracking** | Upcoming launches, fundraising rounds, investor data |

### Security & Forensics

| Feature | What it does |
|---------|-------------|
| **Token security audits** | Honeypot detection, tax analysis, mint/blacklist flags, rug pull indicators |
| **On-chain forensics** | Wallet analysis, whale tracking, holder concentration, token flow patterns |
| **Smart contract audits** | Source code analysis, vulnerability detection, risk scoring |
| **Blockchain fundamentals** | TVL, protocol revenue, developer activity, governance metrics, staking yields |

### Trading & Automation

| Feature | What it does |
|---------|-------------|
| **Autonomous agents** | Set-and-forget trading agents with paper/live execution and 5 built-in strategies |
| **DeFi integrations** | Aave V3, Lido with health monitoring and yield orchestration |
| **Backtesting** | Test strategies against historical data with full metrics (return, win rate, Sharpe, drawdown) |
| **Wallet management** | AES-256-GCM encrypted wallets with scrypt key derivation |
| **Notifications & alerts** | Price alerts for all prediction types (directional + sideways breakout), interactive alerts panel with dismiss-on-review |

### Platforms

| Platform | Description |
|----------|-------------|
| **Terminal (TUI)** | Interactive chat with live price ticker, streaming responses, and slash commands |
| **Web Dashboard** | Next.js 15 — AI chat, markets, agents, portfolio, Polymarket, notifications |
| **REST API** | Fastify + Swagger — 40+ endpoints with API key auth and rate limiting |
| **Discord Bot** | Full command suite with AI-powered chat via @mention |
| **Telegram Bot** | Full command suite with AI chat on any message |

---

## Terminal UI

Launch with `vizzor`. Interactive chat with a live price ticker, streaming AI responses, and slash commands.

**Price Ticker:** Arrow keys to navigate, **Enter** to trigger prediction, **Tab** to toggle focus.

| Command | Description |
|---------|-------------|
| `/scan <address> [--chain <chain>]` | Token security + risk scan |
| `/track <wallet> [--chain <chain>]` | Wallet forensics |
| `/trends` | Trending tokens + top gainers/losers |
| `/audit <contract> [--chain <chain>]` | Smart contract audit |
| `/add <symbol>` | Add token to live price ticker (any source: Binance, CoinGecko, DEX) |
| `/remove <symbol>` | Remove token from ticker |
| `/alerts` | Interactive alerts panel — browse predictions, price alerts, notifications |
| `/alerts clear` | Mark all notifications as read |
| `/alerts hide` / `/alerts show` | Toggle alerts banner visibility |
| `/alerts purge [id\|all]` | Delete predictions, notifications, and alert rules |
| `/alerts delete <id\|all>` | Same as purge (alias) |
| `/chain [<id>]` | Show/switch chain |
| `/provider` | Show current AI provider |
| `/provider <name>` | Switch to `anthropic`, `openai`, `gemini`, `ollama` |
| `/playbook` | Exact steps for better tracked prediction win rate |
| `/agent create <name> [options]` | Create autonomous agent |
| `/agent list` | List agents |
| `/agent start <name>` | Start agent |
| `/agent stop <name>` | Stop agent |
| `/agent status <name>` | Agent status + decisions |
| `/agent wallet <name>` | Show agent wallet balance |
| `/agent trades <name>` | Show agent trade history |
| `/backtest` | Historical strategy backtest |
| `/chronovisor` | ChronoVisor engine status |
| `/config` | Show config |
| `/help` | Command reference |

**Alerts Panel:** Type `/alerts` to open the interactive panel. Use **Up/Down** to navigate predictions and alerts, **Enter** to view full details (entry price, confidence, outcome, signal snapshot), **Escape** to close. Resolved predictions remain available after review and become visually muted as seen history. Pending predictions appear first; resolved predictions sort below them.

### CLI Commands

```bash
vizzor                              # Launch interactive TUI
vizzor setup                        # Reopen guided setup
vizzor config init                  # Initialize config
vizzor config set <key> <value>     # Set config value
vizzor config show                  # Show config
vizzor wallet create|import|list|delete  # Wallet management
vizzor serve [--port 7100]          # Start REST API server
vizzor api key create "my-app"      # Create API key
vizzor bot start [options]          # Start Discord/Telegram bots
vizzor collect start [options]      # Start OHLCV data collection
vizzor chronovisor setup            # Install ChronoVisor engine
vizzor chronovisor start            # Start engine
vizzor chronovisor stop             # Stop engine
vizzor chronovisor status           # Engine health check
vizzor predictions reset            # Reset prediction history
vizzor update                      # Update to latest version
vizzor health                      # Check config, API keys, and service connectivity
```

---

## Autonomous Agents

Set-and-forget trading agents that run a continuous **think > analyze > decide > act** cycle.

### Agent Requirements

| Requirement | Details |
|-------------|---------|
| **AI Provider** | Any supported provider (Claude recommended for best decisions) |
| **Wallet** | Required for live trading; not needed for paper trading or alert-only |
| **RPC Endpoint** | Required for live trading (default public RPCs or Alchemy) |
| **Minimum Balance** | Agent-specific; configurable spending limits |
| **Always-on Process** | Agent runs in a loop — needs a persistent process (terminal, tmux, Docker) |

### Create and Run

```bash
# Create an agent
/agent create alpha --strategy momentum --pairs BTC,ETH,SOL --interval 60

# Start it
/agent start alpha

# Check status
/agent status alpha

# Stop it
/agent stop alpha
```

### Execution Modes

| Mode | What happens | Wallet needed? |
|------|-------------|----------------|
| **Alert-only** | Generates signals, no trades | No |
| **Paper trading** | Simulated trades with realistic slippage model | No |
| **Live trading** | On-chain execution via DEX router | Yes |

### Strategies

| Strategy | Signals | Best for |
|----------|---------|----------|
| **Momentum** | RSI + MACD + Bollinger + Funding | Short-term reversals |
| **Trend-Following** | EMA Crossover + OBV + Fear & Greed | Swing trades |
| **ML-Adaptive** | All TA + ML regime + ChronoVisor | Adaptive, all conditions |
| **ChronoVisor** | 6-signal Bayesian engine + FOL rules + meta-reasoning | Multi-timeframe predictions |
| **Polymarket-Arbitrage** | ChronoVisor vs Polymarket odds | Prediction market edge trading |

### Safety Pipeline (Live Trading)

Live trades pass through a 7-step pipeline before execution:

1. **Validate** — check parameters, balance, spending limits
2. **Prepare** — build transaction with DEX router quote
3. **Simulate** — `eth_call` dry run to detect reverts
4. **Approve** — ERC-20 token approval if needed
5. **Execute** — submit on-chain transaction
6. **Record** — log to portfolio + audit trail
7. **Cleanup** — update positions, trigger alerts

Additional protections:
- Per-agent daily/weekly spending caps
- Kelly criterion position sizing
- ATR-based stop losses
- Max drawdown limits
- Global emergency kill switch (`/agent emergency-stop`)

### Wallet Setup

```bash
vizzor wallet create           # Generate new encrypted wallet
vizzor wallet import           # Import existing private key
vizzor wallet list             # List managed wallets
```

Wallets are encrypted with AES-256-GCM (scrypt N=2^18) and stored at `~/.vizzor/wallets/`.

---

## Web Dashboard

Next.js 15 dashboard with real-time market data, AI chat, and full portfolio tracking.

### Setup

```bash
# Option 1: Docker (recommended)
docker compose up web

# Option 2: From source
cd web
pnpm install
pnpm dev
```

Requires the API server running (`vizzor api start`). Available at `http://localhost:3001`.

### Pages

| Page | What you get |
|------|-------------|
| **AI Chat** | Conversational interface with streaming, tool call progress, trade action cards, conversation persistence |
| **Dashboard** | Market overview, Fear & Greed, sentiment, regime, trending tokens, news, prediction accuracy tracker |
| **Markets** | Token analysis, wallet analyzer, on-chain intelligence |
| **Agents** | Create, monitor, start/stop agents with paper/live mode, portfolio chart, trade history |
| **Portfolio** | Positions, trade history, P&L metrics |
| **Notifications** | Real-time notification panel with prediction detail modals, price alert management, desktop push notifications |
| **Polymarket** | Edge scanner comparing ChronoVisor vs market odds, opportunity cards, position tracking, trade execution |
| **Settings** | API keys and provider configuration |

---

## API

REST API exposing all Vizzor capabilities programmatically. Full Swagger documentation at `/docs`.

### Setup

```bash
vizzor api start --port 3100      # Start server
vizzor api key create "my-app"    # Create API key
```

All endpoints require `X-API-Key` header. Rate limited to 300 req/min per key.

### Endpoints

```
GET  /health                          # Health check (public)
GET  /docs                            # Swagger UI
POST /v1/chat                         # AI chat (SSE streaming)
POST /v1/chat/thread                  # Threaded chat reply
GET  /v1/conversations                # List conversations
GET  /v1/conversations/:id            # Get conversation with messages
GET  /v1/market/price/:symbol         # Price
GET  /v1/market/prices?symbols=       # Batch prices
GET  /v1/market/trending              # Trending tokens
GET  /v1/market/fear-greed            # Fear & Greed Index
GET  /v1/market/ml-health             # ChronoVisor engine status
GET  /v1/market/trenches              # Trenches scanner
GET  /v1/chronovisor/:symbol          # ChronoVisor prediction
GET  /v1/chronovisor/predictions      # List all predictions
GET  /v1/chronovisor/accuracy         # Prediction accuracy metrics
GET  /v1/polymarket/opportunities/:symbol  # Edge opportunities for symbol
GET  /v1/polymarket/positions              # Open orders + recent trades
POST /v1/polymarket/trade                  # Place trade on market
GET  /v1/notifications                # List notifications
GET  /v1/notifications/:id            # Get notification detail
POST /v1/notifications/mark-read      # Mark all as read
DELETE /v1/notifications/:id          # Delete notification
GET  /v1/notifications/rules          # List alert rules
POST /v1/notifications/rules          # Create alert rule
DELETE /v1/notifications/rules/:id    # Delete alert rule
POST /scan                            # Token security scan
POST /trends                          # Market trends
POST /track                           # Wallet forensics
POST /predict                         # AI prediction
POST /audit                           # Contract audit
POST /v1/backtest                     # Backtest
GET  /v1/agents                       # List agents
POST /v1/agents                       # Create agent
POST /v1/agents/:name/start          # Start agent
POST /v1/agents/:name/stop           # Stop agent
GET  /v1/agents/:name/wallet          # Agent wallet balance
GET  /v1/agents/:name/trades          # Agent trade history
GET  /v1/agents/:name/stats           # Agent trade statistics
GET  /v1/portfolio/:id                # Portfolio
POST /v1/agents/emergency-stop        # Global kill switch
WS   /ws                              # WebSocket real-time push
```

---

## Supported Chains

| Chain | Status |
|-------|--------|
| Ethereum | Live |
| Polygon | Live |
| Arbitrum | Live |
| Optimism | Live |
| Base | Live |
| BSC | Live |
| Avalanche | Live |
| Solana | Live |
| Sui | Live |
| Aptos | Live |
| TON | Live |

---

## ChronoVisor Engine

The ChronoVisor engine is an optional Python-based prediction accelerator with 16 trained models that enhances Vizzor's predictions with ML. When unavailable, Vizzor falls back to its rule-based heuristics automatically — no setup required to start using Vizzor.

If your tracked setups keep getting skipped, check whether ChronoVisor is actually enabled and healthy:

```bash
vizzor chronovisor status
```

### Quick setup

```bash
# Interactive wizard — detects Docker or Python, installs deps
vizzor chronovisor setup

# Start the engine
vizzor chronovisor start

# Check health
vizzor chronovisor status
```

Or via Docker:

```bash
docker compose up chronovisor-engine
curl http://localhost:7200/health
```

### Requirements

| Component | Minimum |
|-----------|---------|
| **RAM** | 4 GB (8 GB recommended) |
| **Disk** | 1 GB for models |
| **Runtime** | Docker (recommended) or Python 3.11+ |
| **GPU** | Not required — CPU-based by default |

---

## Configuration

Config at `~/.vizzor/config.yaml`. Environment variables override file values.

```yaml
anthropicApiKey: <your-key>
etherscanApiKey: <your-key>
defaultChain: ethereum

rpc:
  ethereum: https://eth-mainnet.g.alchemy.com/v2/<your-key>
  polygon: https://polygon-mainnet.g.alchemy.com/v2/<your-key>

ai:
  provider: anthropic        # anthropic | openai | gemini | ollama
  model: claude-sonnet-4-20250514
  maxTokens: 4096
  ollamaHost: http://localhost:11434

output:
  format: table
  color: true
  verbose: false

cacheTtl:
  tokenInfo: 3600
  marketData: 300
  walletData: 600
  contractCode: 86400

polymarket:
  enabled: true
  defaultSize: 10          # USD per trade
  orderType: limit
```

### AI Provider Comparison

| Provider | Quality | Cost | Latency | Tool Support | Offline |
|----------|---------|------|---------|--------------|---------|
| **Anthropic** (Claude) | Best | Pay-per-use | ~2-5s | Full | No |
| **OpenAI** (GPT-4) | Great | Pay-per-use | ~2-5s | Full | No |
| **Google** (Gemini) | Good | Free tier | ~2-4s | Full | No |
| **Ollama** (local) | Varies | Free | ~5-30s | Context injection | Yes |

---

## Requirements

### Hardware

| Component | Minimum | Recommended |
|-----------|---------|-------------|
| **CPU** | 2 cores | 4+ cores |
| **RAM** | 2 GB | 4+ GB (8 GB if running ChronoVisor engine) |
| **Disk** | 500 MB | 2 GB (includes SQLite cache + ML models) |
| **Network** | Stable internet | Low latency to Binance/CoinGecko APIs |
| **GPU** | Not required | Not required (ML models are CPU-based) |

### Software

| Dependency | Version | Notes |
|------------|---------|-------|
| **Node.js** | >= 20.0.0 | ES2022 target, ESM modules |
| **pnpm** | >= 8.0 | Recommended package manager (npm/yarn also work) |
| **Python** | 3.x | Required by `better-sqlite3` native build |
| **C++ compiler** | GCC / Clang / MSVC | Required by `better-sqlite3` native build |
| **Docker** | >= 24 | Optional — for ChronoVisor engine, PostgreSQL, web dashboard |

Works on **macOS**, **Linux**, and **Windows**.

### API Keys

| Key | Required | Free Tier | Purpose |
|-----|----------|-----------|---------|
| `ANTHROPIC_API_KEY` | Yes (or use Ollama) | Pay-per-use | Claude AI — best prediction quality |
| `ETHERSCAN_API_KEY` | Recommended | Yes | Transaction history, contract source |
| `OPENAI_API_KEY` | No | Pay-per-use | GPT-4 as alternative provider |
| `GOOGLE_API_KEY` | No | Free tier | Gemini as alternative provider |
| `ALCHEMY_API_KEY` | No | Free tier | Premium RPC endpoints |
| `COINGECKO_API_KEY` | No | Free tier | Extended market data |
| `CRYPTOPANIC_API_KEY` | No | Free tier | News with sentiment |
| `DISCORD_TOKEN` | No | Free | Discord bot |
| `TELEGRAM_BOT_TOKEN` | No | Free | Telegram bot |
| `POLYMARKET_PRIVATE_KEY` | No | N/A | Polymarket CLOB trading (edge execution) |

**No API key at all?** Use Ollama with a local model — fully offline predictions (lower quality but free).

---

## Discord & Telegram

### Discord Bot

Requires `DISCORD_TOKEN`. Enable the `MESSAGE_CONTENT` privileged intent in the [Discord Developer Portal](https://discord.com/developers/applications).

| Command | Description |
|---------|-------------|
| `/predict <symbol>` | AI prediction with signals |
| `/scan <address>` | Token security scan |
| `/trends` | Trending tokens |
| `/track <wallet>` | Wallet forensics |
| `/price <symbol>` | Live price |
| `/audit <contract>` | Contract audit |
| `/ico` | Upcoming launches |
| `/agent_create` | Create agent |
| *@mention* | AI-powered chat |

### Telegram Bot

Requires `TELEGRAM_BOT_TOKEN`.

Same commands as Discord (`/predict`, `/scan`, `/trends`, `/track`, `/price`, `/audit`, `/ico`, `/agent_create`). Any text message triggers AI chat.

---

## Development

```bash
git clone https://github.com/7ayLabs/vizzor.git
cd vizzor
pnpm install

pnpm dev              # Dev mode (tsx)
pnpm build            # Build (tsup)
pnpm lint             # ESLint
pnpm format:check     # Prettier check
pnpm typecheck        # TypeScript strict
pnpm test             # Vitest
pnpm test:coverage    # With coverage
pnpm test:integration # Integration tests (needs API keys)
```

### Tech Stack

| Layer | Tech |
|-------|------|
| Runtime | Node.js >= 20, TypeScript (strict ESM) |
| CLI | Commander.js |
| TUI | Ink (React for terminals) |
| AI | Anthropic SDK, OpenAI SDK, Google GenAI, Ollama |
| Blockchain | viem (EVM), Solana, Sui, Aptos, TON adapters |
| Dashboard | Next.js 15, React 19, Tailwind CSS 4 |
| Database | better-sqlite3 + PostgreSQL (pg) |
| ChronoVisor Engine | Python FastAPI, scikit-learn, PyTorch |
| API | Fastify + Swagger/OpenAPI |
| Bots | discord.js, grammY |
| Build | tsup |
| Test | Vitest |

---

## License

[BUSL-1.1](LICENSE.md) — Business Source License 1.1

---

<p align="center">
  <strong>Built by <a href="https://7aylabs.com">7ayLabs</a></strong>
</p>
