AI-Analy Web3

Explainable Web3 market intelligence in a single Python file — ranked token signals, market-phase labels, and an AI analyst memo from local or hosted LLMs.

AI-Analy Web3 is a lightweight AI market intelligence toolkit for Web3 builders. It scores token market signals from a snapshot, labels each asset with a market phase, and generates an AI analyst memo using either an offline mock engine, a local Ollama model, OpenRouter, or any OpenAI-compatible API.

It is written as a small, inspectable core layer that could sit behind a Web3 dashboard, market-maker assistant, Telegram bot, Discord alert bot, or research notebook. It does not try to be a trading oracle — it demonstrates the backbone of an explainable market analysis pipeline: raw market snapshot in, ranked signal intelligence out.

Features

• Transparent signal scoring — a readable, weighted scoring model over momentum, volume expansion, holder growth, social attention, and liquidity depth. Every weight is visible in main.py, nothing is a black box.
• Market-phase classification — each asset is labeled breakout-watch, accumulation, neutral, or risk-off from fixed, documented thresholds.
• Four interchangeable AI providers — mock (offline, deterministic, no keys), ollama (local inference), openrouter (hosted model routing), and openai (direct chat completions) behind one tiny adapter layer.
• Structured JSON output — --json emits machine-readable signals, ready to pipe into dashboards, bots, or alerting systems.
• Zero dependencies — pure Python standard library (argparse, csv, json, urllib, dataclasses). No pip install, no virtualenv required.
• Offline by default — the mock provider runs the full pipeline with no network access and no API keys.
• Graceful failure — provider/network errors raise a typed ProviderError, print a clean message to stderr, and exit non-zero instead of dumping a traceback.

Architecture

flowchart LR
    A["Market snapshot CSV"] --> B["AI-Analy Web3 CLI"]
    B --> C["Signal scoring engine"]
    C --> D["Ranked assets"]
    D --> E{"AI provider"}
    E -->|mock| F["Offline analyst memo"]
    E -->|ollama| G["Local LLM memo"]
    E -->|openrouter| H["Cloud model routing"]
    E -->|openai| I["OpenAI chat completion"]
    F --> J["Market intelligence report"]
    G --> J
    H --> J
    I --> J

Loading

How the scoring works

Each asset in the snapshot is scored 0–100 by a deliberately readable formula (see score_asset in main.py):

momentum     = change_24h × 0.85 + volume_change × 0.18 + holder_change × 0.95
attention    = min(social_mentions / 450, 16)
liquidity    = liquidity_score × 0.22
risk_penalty = max(0, 55 − liquidity_score) × 0.35   # punishes thin liquidity

score = clamp(34 + momentum + attention + liquidity − risk_penalty, 0, 100)

The score then maps to a market phase:

Score	Phase	Meaning
≥ 74	breakout-watch	strong momentum and attention
≥ 62	accumulation	healthy signal with room to develop
≥ 48	neutral	mixed or baseline market behavior
< 48	risk-off	weak signal or liquidity pressure

Finally, the ranked signals are serialized into a prompt and routed to the selected AI provider, which writes a concise analyst memo focused on momentum, liquidity, narrative strength, and execution risk.

Getting Started

Prerequisites

• Python 3.8+ — nothing else. The toolkit uses only the standard library.
• Optionally: a running Ollama instance, an OpenRouter key, or an OpenAI key for real LLM memos.

Quick start

Run fully offline with the built-in mock memo:

python3 main.py

Emit structured JSON instead of a text report:

python3 main.py --json

Run with a local model via Ollama:

ollama serve
ollama pull llama3.2
python3 main.py --provider ollama --model llama3.2

Run with OpenRouter:

export OPENROUTER_API_KEY="your-key"
python3 main.py --provider openrouter --model openai/gpt-4o-mini

Run with OpenAI:

export OPENAI_API_KEY="your-key"
python3 main.py --provider openai --model gpt-4o-mini

CLI reference

Flag	Default	Description
--provider	mock	AI backend: mock, ollama, openrouter, or openai
--model	per-provider	Model name (llama3.2 for Ollama, gpt-4o-mini / openai/gpt-4o-mini for OpenAI/OpenRouter)
--limit	5	Number of ranked assets to include in the report
--json	off	Print structured JSON instead of the human-readable report

Example Output

Text report (python3 main.py):

AI-Analy Web3
Web3 Market Intelligence Snapshot

1. FET | score=87.68 | phase=breakout-watch
   autonomous AI economy | 24h=14.6% | volume=48.5%
2. DESAI | score=84.02 | phase=breakout-watch
   AI agent infrastructure | 24h=18.4% | volume=42.0%
3. SOL | score=80.39 | phase=breakout-watch
   high-throughput consumer apps | 24h=6.1% | volume=18.2%

AI Memo (mock)
FET is the strongest current signal with a 87.68 breakout-watch score...

Structured JSON (python3 main.py --json):

{
  "engine": "ai-analy-web3",
  "signals": [
    {
      "asset": "FET",
      "score": 87.68,
      "phase": "breakout-watch",
      "price_usd": 2.36,
      "change_24h": 14.6,
      "volume_change": 48.5,
      "liquidity_score": 66.0,
      "narrative": "autonomous AI economy"
    }
  ]
}

Data Format

The pipeline reads data/web3_market_snapshot.csv. Each row is one asset:

Column	Type	Used for
asset	string	ticker symbol
price_usd	float	reporting
change_24h	float	momentum (highest single weight with holder growth)
volume_change	float	momentum
social_mentions	int	attention (capped contribution)
liquidity_score	float	liquidity bonus + thin-liquidity risk penalty
holder_change	float	momentum / holder growth
narrative	string	Web3 narrative category in the memo

Swap in your own snapshot — anything that fills these columns works, which makes it straightforward to wire up live sources later: CoinGecko or DexScreener prices, DEX liquidity and volume feeds, holder concentration metrics, funding rates and open interest, or social sentiment from Telegram, Discord, and X.

Project Structure

ai-analy-web3/
├── main.py                          # entire pipeline: data model, scoring, phases, provider adapters, CLI
├── data/
│   └── web3_market_snapshot.csv     # sample market snapshot (8 assets)
├── CHANGELOG.md
├── NOTES.md                         # working notes
└── README.md

Why This Project Exists

Most Web3 AI demos stop at a chatbot prompt. Real market tools need a more useful core:

• normalize noisy token data
• rank market signals consistently
• explain why a token is moving
• separate momentum from liquidity risk
• support local AI for private research
• support hosted models when teams want better reasoning

AI-Analy Web3 keeps the logic inspectable. The scoring model is readable, the provider layer is small, and the default mode runs offline without keys.

Roadmap

• Live market data ingestion
• Backtesting for signal stability
• Plugin API for custom risk modules
• Historical market regime memory
• RAG over token docs and governance proposals
• Report export to Markdown, JSON, or Telegram alerts
• Dashboard for market-maker and community teams

Disclaimer

AI-Analy Web3 is a research and developer tool. It does not provide financial advice, trading recommendations, or guarantees about market behavior.

Tested locally on macOS / Ubuntu.

License

Released under the MIT License.