|MIRAGE
The Anti-Adversarial Copy-Trading
Intelligence Layer for BNB Chain.
|THE PROBLEM
Hundreds of thousands of retail traders copy “smart money wallets” on Four.meme every day. They lose — because most of those wallets are not smart money. They are adversarial bots built to farm copy-traders via bundle coordination, sniper positioning, wash trading, and social manipulation.
Existing tools (GMGN, Axiom, BullX) rank wallets by PnL — the exact metric adversarial bots are engineered to optimize. No tool on BNB Chain reasons about whether a “smart money” wallet is itself adversarial.
|THE SOLUTION
Mirage does not display wallets — it reasons about them. For every Four.meme wallet and token, three specialized LLM agents (Coin, Wallet, Timing) evaluate structured on-chain features, produce a Trust Verdict (Copy / Avoid / Uncertain), and return a natural-language reasoning trace the user can read, audit, and disagree with.
Every other tool tells you who's winning. Mirage tells you who's cheating.
|PRODUCT
Dashboard: paste any address, get an instant verdict with full reasoning
Wallet verdict: trust score, counter-argument, and three agent analyses
Agent reasoning: each agent scores independently with cited evidence
Exit watchdog: subscribe to receive Telegram alerts when a wallet starts distributing
|KEY DIFFERENTIATORS
|ARCHITECTURE
|VERDICT FLOW
1. User pastes 0x address
2. Auto-detect: wallet vs ERC-20 token contract (Moralis)
3. Fetch on-chain data (txs, transfers, metadata)
4. Extract 7 structured features (bundle coeff, timing entropy, ...)
5. Build evidence pool (block numbers, tx hashes, wallets)
6. Three AI agents reason in parallel
7. Aggregator produces verdict + counter-argument
8. Verdict persisted to MongoDB (ground truth loop)
9. Response: COPY / AVOID / UNCERTAIN + Trust Score 0-100
10. For tokens: analyze top 8 early buyers in parallel
|API REFERENCE
Base URL: http://localhost:8000 — Interactive Swagger UI ↗
Smart router. Auto-detects whether the address is a wallet or ERC-20 token and runs the appropriate pipeline. This is what the dashboard and Telegram bot call.
Request
{ "address": "0x...", "window_minutes": 8 }Response
{ "kind": "wallet"|"token", "verdict": {...} }Three AI agents (Coin, Wallet, Timing) reason about a BNB wallet. Returns verdict, trust score, counter-argument, reasoning traces with evidence citations, and extracted features.
Request
{ "wallet_address": "0x...", "token_address": "0x..." (optional) }Response
{ wallet_address, verdict, trust_score, counter_argument, reasoning_trace[], features, verdict_id }Fetches early buyers of a Four.meme token, analyzes each in parallel, and produces a token-level verdict with bundle contamination score, graduation probability, and ranked buyer table.
Request
{ "token_address": "0x...", "window_minutes": 8 }Response
{ token_address, verdict, trust_score, bundle_contamination_pct, graduation_probability, ranked_buyers[], metadata, total_early_buyers }Subscribe a Telegram chat ID to receive exit-signal watchdog alerts when a wallet starts distributing tokens. The watchdog polls every 60 seconds and detects net outflows, multi-token sells, and transfers to fresh wallets.
{ "chat_id": 123456789, "wallet_address": "0x..." }Remove an existing exit-alert subscription.
Retrieve verdict history from MongoDB. Filter by kind (wallet/token) and limit. Shows verdict_id, address, score, resolved status, and final outcome.
Verdict-vs-outcome hit rate. Shows total verdicts, resolved count, correct count, and accuracy percentage — the feedback loop that makes the system improve over time.
Component status: cache, chain data (Moralis), store (MongoDB), Telegram push, and labeled adversarial set size.
Manual triggers for the adversarial labeling pipeline and outcome resolver. In production these run on cron; exposed as endpoints for hackathon demos.
|REASONING AGENTS
Each agent receives the same structured features and evidence pool but reasons from a different adversarial lens. All claims must cite a block number, tx hash, or wallet address from the evidence pool — hallucinations are stripped by a post-processor.
Coin Agent
Token safety, creator history, tokenomics signals
Wallet Agent
Funding sources, cluster behavior, co-buyer overlap
Timing Agent
Block-timing entropy, transaction cadence
Aggregator
Synthesizes all three agent scores into final verdict
|FEATURE PIPELINE
Structured signals extracted from on-chain data before LLM reasoning. These are what the agents reason about — not raw transactions.
| Feature | Description |
|---|---|
| bundle_coefficient | Fraction of txs sharing a block with another tx (0-1). High = coordinated bundle bot. |
| timing_entropy | Shannon entropy of inter-tx intervals. Low = automated cadence. |
| max_co_buyer_jaccard | Max Jaccard overlap between buyer sets. High = coordinated cluster. |
| graph_distance_to_adversarial | Hops to a known-adversarial wallet via funding chain. 0 = is adversarial, 999 = no connection. |
| cross_token_alpha_variance | PnL variance across tokens. Low = farm bot with engineered returns. |
| funding_ancestor_depth | Length of funding chain back to a CEX or null source. |
| distinct_tokens_traded | Number of unique tokens the wallet has interacted with. |
|TOKEN ANALYSIS
When Mirage detects a token contract, it runs a deeper pipeline:
|FEEDBACK LOOP
Mirage doesn't just predict — it verifies. The system continuously improves by checking its own verdicts against reality.
|EXIT WATCHDOG
Subscribe to any wallet via the dashboard or Telegram bot. The watchdog runs every 60 seconds and alerts you when it detects distribution behavior:
Alerts are pushed via the Telegram Bot API directly. The bot process does not need to be running — the engine sends alerts independently.
|TELEGRAM BOT
Inline buttons: expand full reasoning, view counter-argument, subscribe to exit alerts, share screenshot.
|ENVIRONMENT VARIABLES
# LLM Provider
DEEPSEEK_API_KEY # DeepSeek API key
LLM_MODEL # deepseek-chat (default)
LLM_BASE_URL # https://api.deepseek.com/v1
# On-Chain Data
MORALIS_API_KEY # BSC chain data (free tier)
# Datastore
MONGODB_URI # Verdict store + feature cache
MONGODB_DB # Database name (default: mirage)
# Alerts
TELEGRAM_BOT_TOKEN # Exit-watchdog push alerts
|TECH STACK
| Layer | Choice |
|---|---|
| Data ingestion | Moralis Web3 API (BSC) |
| Feature store | MongoDB Atlas + 30-day TTL cache |
| Orchestration | LangGraph (Python) |
| LLM inference | DeepSeek via OpenAI-compatible API |
| Telegram bot | grammY (TypeScript) |
| Web | Next.js 16 + Tailwind CSS 4 |
| API | FastAPI + uvicorn |