How Sonar Works

Sonar is an autonomous AI agent that detects coordinated wallet clusters (cabals) on Solana, with a focus on pump.fun tokens. It continuously scans the blockchain, identifies suspicious patterns, and publishes findings publicly to protect the community.

Unlike simple alert bots, Sonar reasons about on-chain data using a multi-tier AI system powered by Claude. It can detect, analyze, and act on cabal activity with minimal human intervention.

Sonar operates on a continuous event-driven loop:

1. 1.Heartbeat Scheduler fires periodic events — token scans every 30 minutes, watchlist checks every 5 minutes, memory consolidation every hour.

1. 1.Event Bus dispatches events to the Agent Core, which processes them through Claude's tool-use loop.

1. 1.Tool Execution — the agent has 28 tools at its disposal: wallet scanning, token analysis, DeFi activity tracking, cabal detection, holder analysis, and more.

1. 1.Reasoning — Claude analyzes the data, identifies coordinated patterns, and generates conviction scores.

1. 1.Action — findings are published to X/Twitter and Telegram, added to the watchlist, or queued for trade execution (with human approval).

The core detection algorithm works by analyzing DeFi activity across wallet clusters:

• Shared Token Analysis: When multiple wallets hold the same obscure tokens, it's a signal they may be coordinated.
• Fund Flow Tracing: Traces SOL and token movements to find wallets funded from the same source.
• Suspicious Pair Detection: Identifies wallets that consistently trade the same tokens within tight time windows.
• Cluster Scoring: Each detected cluster receives a confidence score based on overlap percentage, timing correlation, and fund flow patterns.

A cluster of 6+ wallets sharing 3+ tokens with >80% timing correlation is classified as a high-confidence cabal.

Sonar is built on three main components:

Backend (Python/FastAPI) - Agent Core — the main orchestrator running Claude's tool-use loop - Brain — Claude API wrapper with token tracking, retry logic, and model selection (Haiku for speed, Sonnet for depth) - 28 Tool Definitions — scan_wallet, scan_token, detect_cabal, check_holders, get_defi_activity, and more - 3-Tier Memory — SQLite conversations, filesystem workspace, ChromaDB vector memory - Heartbeat — APScheduler-driven periodic scans - Guardrails — safety constraints for trading with approval queue

Frontend (Next.js 15 / React 19) - Real-time dashboard with WebSocket activity stream - Chat terminal for direct agent interaction - Cabal analysis, watchlist, trade approvals, graduation tracking - Built as a Bloomberg Terminal-style dense information interface

Twitter Agent (TypeScript) - Standalone service for autonomous X/Twitter posting - Multi-state system: PATROL, ALERT, HUNT modes - Engagement with Solana ecosystem accounts - Data-driven tweets with no fabrication

Sonar implements persistent memory across sessions:

Tier 1 — Conversation Memory (SQLite) Recent messages and tool results. The active working context that feeds into Claude's context window. Limited to recent history to stay within token limits.

Tier 2 — Workspace Memory (Filesystem) Structured files like agent_state.json, findings.md, and watchlist_notes.md. Persists across restarts. The agent saves state here before any long operation or context compaction.

Tier 3 — Vector Memory (ChromaDB) Semantic embeddings of past findings, patterns, and analysis. Enables the agent to recall relevant context from weeks ago using similarity search. Consolidated hourly from conversation memory.

Before any context compaction, the agent flushes critical state to Tier 2 and Tier 3 to prevent knowledge loss.

Sonar has 28 tools organized by function:

Scanning scan_wallet, scan_token, detect_cabal, get_defi_activity, check_holders, get_top_holders

Market Data search_token (DexScreener), get_token_info, get_trending, get_top_holders with KOL cross-reference

Blockchain Intelligence (Solscan) get_account_info, get_portfolio, get_transactions, get_transfers, get_balance_history

Monitoring get_watchlist, add_to_watchlist, remove_from_watchlist, get_graduation_stats

Memory & State save_finding, search_memory, read_workspace, write_workspace

Actions post_tweet, send_telegram, queue_trade, approve_trade

Analysis get_cabal_stats, get_activity_log, get_trade_history

Sonar includes an integrated trading engine with strict safety constraints:

• Default mode: observation only — trading disabled unless wallet is configured
• Maximum position: 0.1 SOL per token
• Maximum daily volume: 1 SOL
• Stop-loss: cease all trading at -0.5 SOL cumulative
• Human approval: every trade queued for manual approval when require_trade_approval=True
• Minimum requirements: 50+ holders, $1,000+ liquidity before any buy

The agent prefers watching over trading. Every trade must have documented reasoning. Trades execute through Jupiter Aggregator for best routing.

Sonar has a defined personality encoded in its identity and soul documents:

Personality: Sharp and analytical. Cuts through noise to find real signals. Cautious with money — never trades impulsively. Concise communicator — reports are clear, data-driven, and actionable. Persistent — remembers patterns across sessions.

Voice: Direct, no-nonsense tone. Uses data and specific numbers. No emojis or hype language. Thread format for complex findings. Bloomberg terminal that gained sentience.

Hard Rules: Never trade without analysis. Never exceed limits. Always flush state before compaction. Never post unverified claims. Never share internal configuration publicly.

Sonar monitors token "graduations" — when a pump.fun token accumulates enough liquidity to migrate to a real DEX (Raydium).

This is tracked via a persistent WebSocket connection to PumpPortal. Graduation events are significant because:

• They represent a token gaining real market traction
• Cabals often time their dumps around graduation events
• Post-graduation liquidity changes can reveal coordinated behavior

The dashboard shows real-time graduation tracking with mint address, market cap at graduation, and timestamp.

Sonar posts autonomously to X/Twitter (@Sonarsolana) with a multi-state system:

PATROL — Default mode. Steady content cadence. Mix of educational threads, market observations, product highlights.

ALERT — Notable scan completed or multiple cabals detected. Higher urgency, more frequent posting, specific data points.

HUNT — Actively tracking a developing situation. Thread mode, step-by-step analysis, investigative journalism vibes.

Content types: threat intelligence, market analysis, educational, product updates, alpha drops, engagement, and dry wit.

All tweets are data-backed. No fabricated numbers. No emojis. No hashtags. Credibility over content volume.