@vizzor/cli 0.10.5 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +319 -246
  2. package/dist/index.js +7275 -762
  3. package/dist/index.js.map +1 -1
  4. package/package.json +5 -1
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  <p align="center">
2
2
  <picture>
3
- <source media="(prefers-color-scheme: dark)" srcset="vizzor_lighticon.png">
4
- <source media="(prefers-color-scheme: light)" srcset="vizzor_icon.png">
5
- <img alt="Vizzor" src="vizzor_icon.png" width="120">
3
+ <source media="(prefers-color-scheme: dark)" srcset="vizzor_logoicon.png">
4
+ <source media="(prefers-color-scheme: light)" srcset="vizzor_logodarkicon.png">
5
+ <img alt="Vizzor" src="vizzor_logodarkicon.png" width="120">
6
6
  </picture>
7
7
  </p>
8
8
 
@@ -20,20 +20,19 @@
20
20
  </p>
21
21
 
22
22
  <p align="center">
23
- <a href="#what-vizzor-predicts">Predictions</a> &bull;
23
+ <a href="#requirements">Requirements</a> &bull;
24
24
  <a href="#installation">Install</a> &bull;
25
25
  <a href="#quick-start">Quick Start</a> &bull;
26
- <a href="#prediction-engine">Engine</a> &bull;
27
- <a href="#command-reference">Commands</a> &bull;
28
- <a href="#ai-tools">AI Tools</a> &bull;
29
- <a href="#data-sources">Data Sources</a> &bull;
26
+ <a href="#usage">Usage</a> &bull;
30
27
  <a href="#agents">Agents</a> &bull;
28
+ <a href="#web-dashboard">Dashboard</a> &bull;
29
+ <a href="#api-server">API</a> &bull;
31
30
  <a href="#configuration">Config</a>
32
31
  </p>
33
32
 
34
33
  ---
35
34
 
36
- Vizzor is a crypto market prediction engine. It pulls live data from 7 APIs, runs technical analysis on raw candles, reads derivatives positioning and market sentiment, then synthesizes price predictions with actual dollar targets across multiple timeframes -- from 5 minutes to 3 months.
35
+ Vizzor is a crypto market prediction engine. It pulls live data from 7+ APIs, runs technical analysis on raw candles, reads derivatives positioning and market sentiment, then synthesizes price predictions with actual dollar targets across multiple timeframes — from 5 minutes to 3 months.
37
36
 
38
37
  Ask about any coin, token, or currency. Vizzor fetches real-time data, computes signals, and gives you a prediction with numbers, not opinions.
39
38
 
@@ -51,59 +50,74 @@ ETH at $2,112 | Bullish | Confidence: Medium-High
51
50
 
52
51
  ---
53
52
 
54
- ## What Vizzor Predicts
53
+ ## What It Does
55
54
 
56
- **Any tradable crypto asset.** BTC, ETH, SOL, meme coins, new DEX launches, tokens by contract address -- if it has a price, Vizzor can analyze it.
55
+ **Any tradable crypto asset.** BTC, ETH, SOL, meme coins, new DEX launches, tokens by contract address — if it has a price, Vizzor can analyze it.
57
56
 
58
- ### Price Predictions
57
+ - **Price predictions** — bull/bear/likely targets across 9 timeframes (5m to 3 months)
58
+ - **Microstructure analysis** — market structure, FVGs, VWAP, volume delta, liquidation map, order book depth, S/R zones, squeeze detection
59
+ - **Token security audits** — honeypot detection, tax analysis, mint/blacklist flags, rug pull indicators
60
+ - **On-chain forensics** — wallet analysis, whale tracking, holder concentration, token flow patterns
61
+ - **Derivatives positioning** — funding rates, open interest, long/short ratios from Binance Futures
62
+ - **Sentiment analysis** — Fear & Greed Index, news sentiment, buy/sell transaction ratios
63
+ - **Trending discovery** — what tokens are moving right now across DexScreener and CoinGecko
64
+ - **ICO tracking** — upcoming launches, fundraising rounds, investor data
65
+ - **Autonomous agents** — set-and-forget trading agents with paper/live execution
59
66
 
60
- Every prediction includes dollar-value targets across all timeframes:
61
-
62
- | Timeframe | Use Case |
63
- |-----------|----------|
64
- | **5 min / 15 min** | Scalping, quick entries |
65
- | **1 hour / 4 hours** | Intraday trading |
66
- | **1 day / 7 days** | Swing trades |
67
- | **2 weeks / 1 month** | Position trades |
68
- | **3 months** | Macro outlook |
69
- | **Custom time** | "predict BTC at 16:00 today" |
70
-
71
- Each timeframe shows bullish, most likely, and bearish scenarios with percentage moves. Predictions include support/resistance levels, signal confidence, and what would invalidate the forecast.
67
+ ---
72
68
 
73
- ### Market Intelligence
69
+ ## Requirements
74
70
 
75
- Beyond price targets, Vizzor provides:
71
+ ### Hardware
76
72
 
77
- - **Token security audits** -- honeypot detection, tax analysis, mint/blacklist flags, rug pull indicators
78
- - **On-chain forensics** -- wallet analysis, whale tracking, holder concentration, token flow patterns
79
- - **Derivatives positioning** -- funding rates, open interest, long/short ratios from Binance Futures
80
- - **Sentiment analysis** -- Fear & Greed Index, news sentiment, buy/sell transaction ratios
81
- - **Trending discovery** -- what tokens are moving right now across DexScreener and CoinGecko
82
- - **ICO tracking** -- upcoming launches, fundraising rounds, investor data from DeFiLlama
73
+ | Component | Minimum | Recommended |
74
+ |-----------|---------|-------------|
75
+ | **CPU** | 2 cores | 4+ cores |
76
+ | **RAM** | 2 GB | 4+ GB (8 GB if running ML sidecar) |
77
+ | **Disk** | 500 MB | 2 GB (includes SQLite cache + ML models) |
78
+ | **Network** | Stable internet | Low latency to Binance/CoinGecko APIs |
79
+ | **GPU** | Not required | Not required (ML models are CPU-based) |
83
80
 
84
- ---
85
-
86
- ## Requirements
81
+ ### Software
87
82
 
88
83
  | Dependency | Version | Notes |
89
84
  |------------|---------|-------|
90
85
  | **Node.js** | >= 20.0.0 | ES2022 target, ESM modules |
91
- | **pnpm** | >= 8.0 | Recommended (npm/yarn also work) |
86
+ | **pnpm** | >= 8.0 | Recommended package manager (npm/yarn also work) |
92
87
  | **Python** | 3.x | Required by `better-sqlite3` native build |
93
88
  | **C++ compiler** | GCC / Clang / MSVC | Required by `better-sqlite3` native build |
89
+ | **Docker** | >= 24 | Optional — for ML sidecar, PostgreSQL, web dashboard |
90
+
91
+ Works on **macOS**, **Linux**, and **Windows**.
92
+
93
+ ### API Keys
94
94
 
95
- Works on **macOS**, **Linux**, and **Windows**. No GPU required.
95
+ | Key | Required | Free Tier | Purpose |
96
+ |-----|----------|-----------|---------|
97
+ | `ANTHROPIC_API_KEY` | Yes (or use Ollama) | Pay-per-use | Claude AI — best prediction quality |
98
+ | `ETHERSCAN_API_KEY` | Recommended | Yes | Transaction history, contract source |
99
+ | `OPENAI_API_KEY` | No | Pay-per-use | GPT-4 as alternative provider |
100
+ | `GOOGLE_API_KEY` | No | Free tier | Gemini as alternative provider |
101
+ | `ALCHEMY_API_KEY` | No | Free tier | Premium RPC endpoints |
102
+ | `COINGECKO_API_KEY` | No | Free tier | Extended market data |
103
+ | `CRYPTOPANIC_API_KEY` | No | Free tier | News with sentiment |
104
+ | `DISCORD_TOKEN` | No | Free | Discord bot |
105
+ | `TELEGRAM_BOT_TOKEN` | No | Free | Telegram bot |
106
+
107
+ **No API key at all?** Use Ollama with a local model — fully offline predictions (lower quality but free).
96
108
 
97
109
  ---
98
110
 
99
111
  ## Installation
100
112
 
113
+ ### npm (recommended)
114
+
101
115
  ```bash
102
116
  npm install -g @vizzor/cli
103
117
  ```
104
118
 
105
119
  ```bash
106
- # Or run directly
120
+ # Or run directly without installing
107
121
  npx @vizzor/cli
108
122
  ```
109
123
 
@@ -117,84 +131,96 @@ pnpm build
117
131
  pnpm link --global
118
132
  ```
119
133
 
134
+ ### Docker (Full Stack)
135
+
136
+ ```bash
137
+ cp .env.example .env # Configure API keys
138
+ docker compose up -d # Starts CLI + ML sidecar + PostgreSQL + Web Dashboard
139
+ ```
140
+
120
141
  ---
121
142
 
122
143
  ## Quick Start
123
144
 
145
+ ### Option A: With Claude (best quality)
146
+
124
147
  ```bash
125
- # 1. Set your API key
126
- vizzor config set anthropicApiKey <your-key>
127
- # or: export ANTHROPIC_API_KEY=<your-key>
148
+ # 1. Set your Anthropic API key
149
+ vizzor config set anthropicApiKey sk-ant-...
150
+ # or: export ANTHROPIC_API_KEY=sk-ant-...
128
151
 
129
152
  # 2. Launch
130
153
  vizzor
131
154
  ```
132
155
 
133
- Then just ask:
156
+ ### Option B: With Ollama (free, local, offline)
157
+
158
+ ```bash
159
+ # 1. Install Ollama: https://ollama.ai
160
+ ollama pull llama3.2 # or qwen2.5:14b for better results
161
+
162
+ # 2. Configure Vizzor
163
+ vizzor config set ai.provider ollama
164
+ vizzor config set ai.model llama3.2
165
+
166
+ # 3. Launch
167
+ vizzor
168
+ ```
169
+
170
+ ### Option C: With OpenAI or Gemini
171
+
172
+ ```bash
173
+ vizzor config set ai.provider openai
174
+ vizzor config set openaiApiKey sk-...
175
+ # or
176
+ vizzor config set ai.provider gemini
177
+ vizzor config set googleApiKey AI...
178
+ ```
179
+
180
+ ### Start asking
134
181
 
135
182
  ```
136
183
  > predict BTC price next week
137
184
  > analyze $PEPE security and price outlook
138
185
  > what's trending in crypto right now
186
+ > full microstructure analysis for ETH
139
187
  > track wallet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
140
188
  > audit contract 0x1f9840a85d5aF5bf1D1762F925BDADdC4201F984
141
189
  ```
142
190
 
143
191
  ---
144
192
 
145
- ## Prediction Engine
146
-
147
- ### Multi-Signal Composite
148
-
149
- Vizzor builds predictions from 5 weighted signal dimensions:
150
-
151
- ```
152
- Technical Analysis ........... 40% RSI, MACD, Bollinger, EMA, ATR, OBV
153
- Market Sentiment ............. 20% Fear & Greed, news sentiment, buy/sell ratio
154
- Derivatives Positioning ...... 20% Funding rate, open interest, long/short
155
- Trend Momentum ............... 15% 24h/7d price action, volume trends
156
- Macro Cycle ................... 5% Fear & Greed extremes as contrarian signals
157
- ----
158
- Composite Score -100 to +100
159
- ```
160
-
161
- Signals are computed from raw data before the AI sees them. The AI presents and contextualizes the pre-computed analysis -- it doesn't invent numbers.
162
-
163
- ### Technical Analysis
164
-
165
- Computed from Binance kline data. No third-party TA APIs -- pure math on raw candles.
166
-
167
- | Indicator | Signal |
168
- |-----------|--------|
169
- | **RSI** (14) | Overbought > 70, Oversold < 30 |
170
- | **MACD** (12, 26, 9) | Crossover direction + histogram momentum |
171
- | **Bollinger Bands** (20, 2) | %B position for squeeze/breakout |
172
- | **EMA Crossover** (12/26) | Golden cross / death cross |
173
- | **ATR** (14) | Volatility regime |
174
- | **OBV** | Volume-price confirmation |
193
+ ## Usage
175
194
 
176
- ### Volatility-Scaled Projections
195
+ ### TUI (Terminal UI)
177
196
 
178
- Price targets use `hourlyVol * sqrt(hours)` scaling -- wider ranges for longer timeframes, amplified for micro-cap/meme tokens. The engine automatically detects meme coins (Pump.fun, sub-$1M market cap) and applies higher volatility multipliers.
197
+ Launch with `vizzor`. Interactive chat with live price ticker, streaming responses, and slash commands.
179
198
 
180
- ### Time-Aware Predictions
199
+ **Price Ticker:** Arrow keys to navigate, **Enter** to trigger AI prediction, **Tab** to toggle focus.
181
200
 
182
- Ask for any specific time and Vizzor computes a targeted projection:
183
-
184
- ```
185
- > predict SOL at 3:00pm # specific clock time
186
- > predict ETH in 30 minutes # relative time
187
- > predict BTC tomorrow # next day
188
- > predict DOGE end of week # end of week
189
- ```
190
-
191
- ---
192
-
193
- ## Command Reference
201
+ | Command | Description |
202
+ |---------|-------------|
203
+ | `/scan <address> [--chain <chain>]` | Token security + risk scan |
204
+ | `/track <wallet> [--chain <chain>]` | Wallet forensics |
205
+ | `/trends` | Trending tokens + top gainers/losers |
206
+ | `/audit <contract> [--chain <chain>]` | Smart contract audit |
207
+ | `/add <symbol>` | Add token to live price ticker |
208
+ | `/remove <symbol>` | Remove token from ticker |
209
+ | `/chain [<id>]` | Show/switch chain |
210
+ | `/provider` | Show current AI provider |
211
+ | `/provider <name>` | Switch to `anthropic`, `openai`, `gemini`, `ollama` |
212
+ | `/agent create <name> [options]` | Create autonomous agent |
213
+ | `/agent list` | List agents |
214
+ | `/agent start <name>` | Start agent |
215
+ | `/agent stop <name>` | Stop agent |
216
+ | `/agent status <name>` | Agent status + decisions |
217
+ | `/backtest` | Historical strategy backtest |
218
+ | `/config` | Show config |
219
+ | `/help` | Command reference |
194
220
 
195
221
  ### CLI Commands
196
222
 
197
- ```
223
+ ```bash
198
224
  vizzor # Launch interactive TUI
199
225
  vizzor scan <token> [options] # Token risk analysis
200
226
  vizzor trends [options] # Market trends + top movers
@@ -204,205 +230,218 @@ vizzor ico list [options] # ICO/IDO tracker
204
230
  vizzor config init # Initialize config
205
231
  vizzor config set <key> <value> # Set config value
206
232
  vizzor config show # Show config
233
+ vizzor wallet create|import|list|delete # Wallet management
234
+ vizzor backtest [options] # Historical strategy backtest
207
235
  vizzor bot start [options] # Start Discord/Telegram bots
208
- vizzor bot validate # Check bot token configuration
236
+ vizzor api start [--port 3100] # Start REST API server
237
+ vizzor api key create "my-app" # Create API key
209
238
  ```
210
239
 
211
- ### TUI Slash Commands
212
-
213
- | Command | Description |
214
- |---------|-------------|
215
- | `/scan <address> [--chain <chain>]` | Token security + risk scan |
216
- | `/track <wallet> [--chain <chain>]` | Wallet forensics |
217
- | `/trends` | Trending tokens + top gainers/losers |
218
- | `/audit <contract> [--chain <chain>]` | Smart contract audit |
219
- | `/add <symbol>` | Add a token to the live price ticker |
220
- | `/remove <symbol>` | Remove a token from the price ticker |
221
- | `/chain [<id>]` | Show available chains or switch chain |
222
- | `/config` | Show config with setup guidance |
223
- | `/config set <key> <value>` | Update a config value |
224
- | `/provider` | Show current AI provider |
225
- | `/provider list` | List all providers with availability |
226
- | `/provider <name>` | Switch to `anthropic`, `openai`, `gemini`, `ollama` |
227
- | `/agent create <name> [options]` | Create autonomous prediction agent |
228
- | `/agent list` | List all agents |
229
- | `/agent start <name>` | Start agent cycle |
230
- | `/agent stop <name>` | Stop agent |
231
- | `/agent status <name>` | View status + recent decisions |
232
- | `/agent delete <name>` | Delete an agent |
233
- | `/agent strategies` | List available strategies |
234
- | `/help` | Command reference |
235
- | `/clear` | Clear messages |
236
- | `/exit` | Quit |
237
-
238
- **Price Ticker:** Arrow keys to navigate, **Enter** to trigger full AI prediction for any token, **Tab** to toggle focus.
239
-
240
240
  ### Discord Bot
241
241
 
242
- | Command | Description |
243
- |---------|-------------|
244
- | `/scan <address>` | Token security + risk scan |
245
- | `/trends` | Trending tokens + market data |
246
- | `/track <wallet>` | Wallet forensics |
247
- | `/ico` | Upcoming launches and rounds |
248
- | `/audit <contract>` | Contract audit |
249
- | `/price <symbol>` | Live price check |
250
- | `/predict <symbol>` | AI prediction with signals |
251
- | `/wallet <address>` | ETH wallet balance |
252
- | `/agent_create` | Create a trading agent |
253
- | `/agent_list` | List all agents |
254
- | `/agent_start` | Start an agent |
255
- | `/agent_stop` | Stop an agent |
256
- | `/agent_status` | Agent status & decisions |
257
- | `/agent_delete` | Delete an agent |
258
- | `/help` | Show all commands |
259
- | *@mention* | AI-powered chat with live data |
260
-
261
- **Setup**: Enable the `MESSAGE_CONTENT` privileged intent in the [Discord Developer Portal](https://discord.com/developers/applications) for @mention AI chat.
262
-
263
- ### Telegram Bot
242
+ Requires `DISCORD_TOKEN`. Enable the `MESSAGE_CONTENT` privileged intent in the [Discord Developer Portal](https://discord.com/developers/applications).
264
243
 
265
244
  | Command | Description |
266
245
  |---------|-------------|
246
+ | `/predict <symbol>` | AI prediction with signals |
267
247
  | `/scan <address>` | Token security scan |
268
- | `/trends` | Trending tokens + gainers/losers |
248
+ | `/trends` | Trending tokens |
269
249
  | `/track <wallet>` | Wallet forensics |
270
- | `/ico` | Upcoming launches and rounds |
250
+ | `/price <symbol>` | Live price |
271
251
  | `/audit <contract>` | Contract audit |
272
- | `/price <symbol>` | Live price check |
273
- | `/predict <symbol>` | AI prediction with signals |
274
- | `/wallet <address>` | ETH wallet balance |
275
- | `/agent_create` | Create a trading agent |
276
- | `/agent_list` | List all agents |
277
- | `/agent_start` | Start an agent |
278
- | `/agent_stop` | Stop an agent |
279
- | `/agent_status` | Agent status & decisions |
280
- | `/agent_delete` | Delete an agent |
281
- | *Any text* | AI-powered chat with live data |
252
+ | `/ico` | Upcoming launches |
253
+ | `/agent_create` | Create agent |
254
+ | *@mention* | AI-powered chat |
282
255
 
283
- ---
256
+ ### Telegram Bot
284
257
 
285
- ## AI Tools
286
-
287
- Vizzor exposes **17+ tools** to the AI. During conversation, the AI autonomously calls whichever tools it needs to build a complete prediction.
288
-
289
- | Tool | What It Provides |
290
- |------|------------------|
291
- | `get_market_data` | Price, volume, market cap (CoinGecko) |
292
- | `search_token_dex` | Real-time DEX pair data (DexScreener) |
293
- | `get_technical_analysis` | RSI, MACD, Bollinger, EMA, ATR, OBV |
294
- | `get_prediction` | Multi-signal composite prediction |
295
- | `get_derivatives_data` | Funding rate, open interest (Binance Futures) |
296
- | `get_fear_greed` | Fear & Greed Index + 7-day history |
297
- | `get_crypto_news` | News headlines with sentiment scoring |
298
- | `get_trending` | Hot tokens across DexScreener + CoinGecko |
299
- | `get_token_info` | On-chain token data (name, supply, holders) |
300
- | `get_token_security` | GoPlus security scan (honeypot, taxes, flags) |
301
- | `analyze_wallet` | Wallet forensics (patterns, holdings, risk) |
302
- | `check_rug_indicators` | Rug pull detection suite |
303
- | `search_upcoming_icos` | ICO/IDO tracker with filters |
304
- | `get_raises` | Recent fundraising rounds |
305
- | `get_funding_history` | Project/investor funding history |
306
- | `create_agent` | Deploy autonomous prediction agent |
307
- | `list_agents` | List active agents |
308
- | `get_agent_status` | Agent status and decisions |
309
-
310
- ### AI Providers
311
-
312
- | Provider | Model | Tool Support | Notes |
313
- |----------|-------|--------------|-------|
314
- | **Anthropic** | Claude Opus / Sonnet | Full tool-use | Default. Best prediction quality |
315
- | **OpenAI** | GPT-4 Turbo | Full tool-use | Function calling |
316
- | **Google** | Gemini Pro | Full tool-use | Tool-use support |
317
- | **Ollama** | Any local model | Context injection | Pre-computed signals injected into context |
318
-
319
- For providers without tool support (Ollama), Vizzor pre-fetches all relevant data, runs signal computation, and injects pre-written analysis directly into the context. The model presents the pre-computed predictions rather than generating them from scratch.
258
+ Requires `TELEGRAM_BOT_TOKEN`.
320
259
 
321
- ```bash
322
- /provider openai
323
- /provider ollama llama3
324
- ```
260
+ Same commands as Discord (`/predict`, `/scan`, `/trends`, `/track`, `/price`, `/audit`, `/ico`, `/agent_create`). Any text message triggers AI chat.
325
261
 
326
262
  ---
327
263
 
328
- ## Data Sources
264
+ ## Agents
329
265
 
330
- | Source | Data | Auth |
331
- |--------|------|------|
332
- | **Binance** | Klines, tickers, funding rates, open interest, gainers/losers | Public |
333
- | **DexScreener** | DEX pairs, trending tokens, real-time pricing | Public |
334
- | **GoPlus** | Token security, honeypot detection, holder analysis | Public |
335
- | **DeFiLlama** | TVL, fundraising rounds, protocol metrics | Public |
336
- | **CryptoPanic** | News aggregation with sentiment | Free tier |
337
- | **Fear & Greed** | Crypto Fear & Greed Index | Public |
338
- | **Pump.fun** | Solana meme coin launches | Public |
266
+ Autonomous prediction agents that run a continuous **think → analyze → decide → act** cycle.
339
267
 
340
- All responses cached in SQLite with configurable TTL (5 min for market data, 1 hour for token info, 24 hours for contract code).
268
+ ### Agent Requirements
341
269
 
342
- ---
270
+ | Requirement | Details |
271
+ |-------------|---------|
272
+ | **AI Provider** | Any (Claude recommended for best decisions) |
273
+ | **Wallet** | Required for live trading; not needed for paper trading or alert-only |
274
+ | **RPC Endpoint** | Required for live trading (default public RPCs or Alchemy) |
275
+ | **Minimum Balance** | Agent-specific; configurable spending limits |
276
+ | **Always-on Process** | Agent runs in a loop — needs a persistent process (terminal, tmux, Docker, etc.) |
343
277
 
344
- ## Agents
345
-
346
- Autonomous prediction agents that run a continuous **think -> analyze -> decide -> act** cycle.
278
+ ### Create and Run
347
279
 
348
280
  ```bash
281
+ # Create an agent
349
282
  /agent create alpha --strategy momentum --pairs BTC,ETH,SOL --interval 60
283
+
284
+ # Start it
350
285
  /agent start alpha
286
+
287
+ # Check status
351
288
  /agent status alpha
289
+
290
+ # Stop it
291
+ /agent stop alpha
352
292
  ```
353
293
 
294
+ ### Execution Modes
295
+
296
+ | Mode | Description | Wallet Required |
297
+ |------|-------------|-----------------|
298
+ | **Alert-only** | Generates signals, no trades | No |
299
+ | **Paper trading** | Simulated trades with realistic slippage model | No |
300
+ | **Live trading** | On-chain execution via DEX router | Yes |
301
+
354
302
  ### Strategies
355
303
 
356
- | Strategy | Signals | Entry | Exit |
357
- |----------|---------|-------|------|
358
- | **Momentum** | RSI + MACD + Bollinger + Funding | RSI crosses above 30 + bullish MACD | RSI > 70 + bearish divergence |
359
- | **Trend-Following** | EMA Crossover + OBV + Fear & Greed | Golden cross + rising volume | Death cross |
304
+ | Strategy | Signals | Best For |
305
+ |----------|---------|----------|
306
+ | **Momentum** | RSI + MACD + Bollinger + Funding | Short-term reversals |
307
+ | **Trend-Following** | EMA Crossover + OBV + Fear & Greed | Swing trades |
308
+ | **ML-Adaptive** | All TA + ML regime + ChronoVisor | Adaptive, all conditions |
360
309
 
361
- > v0.3.0: Agents operate in **alert-only mode** -- they log decisions and emit signals but do not execute on-chain transactions.
310
+ ### Safety Pipeline (Live Trading)
311
+
312
+ Live trades pass through a 7-step pipeline before execution:
313
+
314
+ 1. **Validate** — check parameters, balance, spending limits
315
+ 2. **Prepare** — build transaction with DEX router quote
316
+ 3. **Simulate** — `eth_call` dry run to detect reverts
317
+ 4. **Approve** — ERC-20 token approval if needed
318
+ 5. **Execute** — submit on-chain transaction
319
+ 6. **Record** — log to portfolio + audit trail
320
+ 7. **Cleanup** — update positions, trigger alerts
321
+
322
+ Additional protections:
323
+ - Per-agent daily/weekly spending caps
324
+ - Kelly criterion position sizing
325
+ - ATR-based stop losses
326
+ - Max drawdown limits
327
+ - Global emergency kill switch (`/agent emergency-stop`)
328
+
329
+ ### Wallet Setup
330
+
331
+ ```bash
332
+ vizzor wallet create # Generate new encrypted wallet
333
+ vizzor wallet import # Import existing private key
334
+ vizzor wallet list # List managed wallets
335
+ ```
336
+
337
+ Wallets are encrypted with AES-256-GCM (scrypt N=2^18) and stored at `~/.vizzor/wallets/`.
338
+
339
+ ### Backtesting
340
+
341
+ Test strategies against historical data before going live:
342
+
343
+ ```bash
344
+ vizzor backtest --strategy momentum --pair BTCUSDT --from 2024-01-01 --to 2024-12-31
345
+ ```
346
+
347
+ Metrics: total return, win rate, profit factor, Sharpe ratio, max drawdown, equity curve.
362
348
 
363
349
  ---
364
350
 
365
- ## Supported Chains
351
+ ## Web Dashboard
352
+
353
+ Next.js 15 dashboard at `http://localhost:3001`.
354
+
355
+ ### Setup
366
356
 
367
- | Chain | Status | Security Scan |
368
- |-------|--------|---------------|
369
- | Ethereum | Live | GoPlus |
370
- | Polygon | Live | GoPlus |
371
- | Arbitrum | Live | GoPlus |
372
- | Optimism | Live | GoPlus |
373
- | Base | Live | GoPlus |
374
- | BSC | Live | GoPlus |
375
- | Avalanche | Live | GoPlus |
376
- | Solana | Live (DEX + GoPlus) | GoPlus |
357
+ ```bash
358
+ # Option 1: Docker (recommended)
359
+ docker compose up web
360
+
361
+ # Option 2: From source
362
+ cd web
363
+ pnpm install
364
+ pnpm dev
365
+ ```
366
+
367
+ Requires the API server running (`vizzor api start`).
377
368
 
378
- New chains are added by implementing the `ChainAdapter` interface.
369
+ ### Pages
370
+
371
+ - **AI Chat** — conversational interface with streaming, tool call progress, trade action cards
372
+ - **Dashboard** — market overview, Fear & Greed, sentiment, regime, trending tokens, news
373
+ - **Markets** — token analysis, wallet analyzer, on-chain intelligence
374
+ - **Agents** — create, monitor, start/stop agents with paper/live mode
375
+ - **Portfolio** — positions, trade history, P&L metrics
376
+ - **Settings** — API keys and provider configuration
379
377
 
380
378
  ---
381
379
 
382
- ## Configuration
380
+ ## API Server
383
381
 
384
- Config at `~/.vizzor/config.yaml`. Environment variables override file values.
382
+ REST API exposing all Vizzor capabilities programmatically.
383
+
384
+ ### Setup
385
385
 
386
- ### Required
386
+ ```bash
387
+ vizzor api start --port 3100 # Start server
388
+ vizzor api key create "my-app" # Create API key
389
+ ```
387
390
 
388
- | Variable | Purpose |
389
- |----------|---------|
390
- | `ANTHROPIC_API_KEY` | Claude AI -- primary prediction engine |
391
- | `ETHERSCAN_API_KEY` | Transaction history, contract source |
391
+ All endpoints require `X-API-Key` header. Rate limited to 300 req/min per key.
392
392
 
393
- ### Optional
393
+ ### Endpoints
394
394
 
395
- | Variable | Purpose |
396
- |----------|---------|
397
- | `OPENAI_API_KEY` | GPT-4 as alternative provider |
398
- | `GOOGLE_API_KEY` | Gemini as alternative provider |
399
- | `ALCHEMY_API_KEY` | Premium RPC endpoints |
400
- | `COINGECKO_API_KEY` | Extended market data |
401
- | `CRYPTOPANIC_API_KEY` | News with sentiment |
402
- | `DISCORD_TOKEN` | Discord bot |
403
- | `TELEGRAM_BOT_TOKEN` | Telegram bot |
395
+ ```
396
+ GET /health # Health check (public)
397
+ GET /docs # Swagger UI
398
+ POST /v1/chat # AI chat (SSE streaming)
399
+ POST /v1/chat/thread # Threaded chat reply
400
+ GET /v1/market/price/:symbol # Price
401
+ GET /v1/market/prices?symbols= # Batch prices
402
+ GET /v1/market/trending # Trending tokens
403
+ GET /v1/market/fear-greed # Fear & Greed Index
404
+ GET /v1/market/ml-health # ML sidecar status
405
+ GET /v1/market/trenches # Trenches scanner
406
+ GET /v1/chronovisor/:symbol # ChronoVisor prediction
407
+ POST /scan # Token security scan
408
+ POST /trends # Market trends
409
+ POST /track # Wallet forensics
410
+ POST /predict # AI prediction
411
+ POST /audit # Contract audit
412
+ POST /v1/backtest # Backtest
413
+ GET /v1/agents # List agents
414
+ POST /v1/agents # Create agent
415
+ POST /v1/agents/:name/start # Start agent
416
+ POST /v1/agents/:name/stop # Stop agent
417
+ GET /v1/portfolio/:id # Portfolio
418
+ POST /v1/agents/emergency-stop # Global kill switch
419
+ WS /ws # WebSocket real-time push
420
+ ```
404
421
 
405
- ### Full Config
422
+ ---
423
+
424
+ ## Supported Chains
425
+
426
+ | Chain | Status |
427
+ |-------|--------|
428
+ | Ethereum | Live |
429
+ | Polygon | Live |
430
+ | Arbitrum | Live |
431
+ | Optimism | Live |
432
+ | Base | Live |
433
+ | BSC | Live |
434
+ | Avalanche | Live |
435
+ | Solana | Live |
436
+ | Sui | Live |
437
+ | Aptos | Live |
438
+ | TON | Live |
439
+
440
+ ---
441
+
442
+ ## Configuration
443
+
444
+ Config at `~/.vizzor/config.yaml`. Environment variables override file values.
406
445
 
407
446
  ```yaml
408
447
  anthropicApiKey: <your-key>
@@ -431,6 +470,37 @@ cacheTtl:
431
470
  contractCode: 86400
432
471
  ```
433
472
 
473
+ ### AI Provider Comparison
474
+
475
+ | Provider | Quality | Cost | Latency | Tool Support | Offline |
476
+ |----------|---------|------|---------|--------------|---------|
477
+ | **Anthropic** (Claude) | Best | Pay-per-use | ~2-5s | Full | No |
478
+ | **OpenAI** (GPT-4) | Great | Pay-per-use | ~2-5s | Full | No |
479
+ | **Google** (Gemini) | Good | Free tier | ~2-4s | Full | No |
480
+ | **Ollama** (local) | Varies | Free | ~5-30s | Context injection | Yes |
481
+
482
+ ---
483
+
484
+ ## ML Sidecar (Optional)
485
+
486
+ Python FastAPI sidecar with 16 trained models for enhanced predictions. Falls back to heuristics when unavailable.
487
+
488
+ ### Setup
489
+
490
+ ```bash
491
+ docker compose up ml-sidecar
492
+ curl http://localhost:8000/health
493
+ ```
494
+
495
+ ### Requirements
496
+
497
+ | Component | Minimum |
498
+ |-----------|---------|
499
+ | **RAM** | 4 GB (8 GB recommended) |
500
+ | **Disk** | 1 GB for models |
501
+ | **Python** | 3.10+ |
502
+ | **GPU** | Not required |
503
+
434
504
  ---
435
505
 
436
506
  ## Development
@@ -444,7 +514,7 @@ pnpm dev # Dev mode (tsx)
444
514
  pnpm build # Build (tsup)
445
515
  pnpm lint # ESLint
446
516
  pnpm typecheck # TypeScript strict
447
- pnpm test # Vitest (164 tests, 19 suites)
517
+ pnpm test # Vitest
448
518
  pnpm test:coverage # With coverage
449
519
  ```
450
520
 
@@ -456,8 +526,11 @@ pnpm test:coverage # With coverage
456
526
  | CLI | Commander.js |
457
527
  | TUI | Ink (React for terminals) |
458
528
  | AI | Anthropic SDK, OpenAI SDK, Google GenAI, Ollama |
459
- | Blockchain | viem (EVM), plugin adapter system |
460
- | Database | better-sqlite3 with TTL cache |
529
+ | Blockchain | viem (EVM), Solana, Sui, Aptos, TON adapters |
530
+ | Dashboard | Next.js 15, React 19, Tailwind CSS 4 |
531
+ | Database | better-sqlite3 + PostgreSQL (pg) |
532
+ | ML Sidecar | Python FastAPI, scikit-learn, PyTorch |
533
+ | API | Fastify + Swagger/OpenAPI |
461
534
  | Bots | discord.js, grammY |
462
535
  | Build | tsup |
463
536
  | Test | Vitest |
@@ -466,7 +539,7 @@ pnpm test:coverage # With coverage
466
539
 
467
540
  ## License
468
541
 
469
- [BUSL-1.1](LICENSE.md) -- Business Source License 1.1
542
+ [BUSL-1.1](LICENSE.md) — Business Source License 1.1
470
543
 
471
544
  ---
472
545