🐋 Stellar Whale Tracker

Track smart wallets on Stellar. Know what sophisticated money is doing before everyone else.

---

What This Is

A real-time intelligence tool that monitors Stellar wallets making early, profitable moves into RWA tokens and Stellar assets. Built to surface smart money activity on Stellar's growing ecosystem.

---

What It Does

• Wallet Scoring — scores Stellar wallets based on profitability, timing, and RWA asset diversity
• Real-time Monitoring — watches flagged smart wallets for new moves via Horizon API
• Alert System — notifies when a smart wallet enters a new position
• Dashboard — clean interface showing tracked wallets, recent moves, and accumulation patterns

---

Why Stellar Specifically

Most whale trackers are built for Ethereum or Solana. Stellar is different:

• Most large wallets are anchors, exchanges, or remittance corridors
• Smart money on Stellar = wallets that move early into new RWA tokens
• As Stellar's RWA ecosystem grows (BENJI, tokenized equities, commodities), early movers generate outsized returns
• Nobody is tracking this. Yet.

---

Architecture

whale-tracker/
├── scorer/          # Wallet scoring engine (Rust)
├── monitor/         # Real-time transaction monitor (Go)
├── api/             # REST API for dashboard and StellarTrade integration
├── dashboard/       # Frontend dashboard (React)
├── scripts/         # Data seeding and utility scripts
└── docs/            # Technical documentation

---

Tech Stack

Layer	Technology	Why
Scoring Engine	Rust	Performance, type safety
Monitor	Go	Concurrency, lightweight goroutines for real-time watching
Data Source	Stellar Horizon API	Full transaction history, asset holdings, SDEX trades
API	Node.js / TypeScript	Fast iteration, broad SDK support
Dashboard	React / Next.js	Component-based, fast UI
Database	PostgreSQL	Wallet scores, history, alerts

---

Smart Wallet Definition

A wallet is flagged as a "smart wallet" on Stellar if it consistently:

1. Enters new RWA asset positions early — before significant price appreciation
2. Executes large SDEX trades profitably over time
3. Holds diversified RWA positions suggesting deliberate strategy
4. Shows accumulation patterns ahead of broader market moves

---

Scoring Model (v1)

Each wallet receives a score from 0 to 100 based on:

Factor	Weight	Description
Entry timing	30%	How early relative to price movement
Profitability	30%	Realized and unrealized P&L on tracked positions
Asset diversity	20%	Range of RWA assets held
Transaction volume	20%	Consistent activity at meaningful size

---

Roadmap

Phase 1 — Foundation

• Horizon API integration
• Historical transaction ingestion
• Basic wallet scoring engine (v1)
• PostgreSQL schema

Phase 2 — Real-time Monitor

• Live transaction stream via Horizon SSE
• Smart wallet alert triggers
• Webhook notification system

Phase 3 — Dashboard

• Wallet leaderboard
• Individual wallet profile pages
• Asset accumulation charts
• Alert subscription UI

Phase 4 — StellarTrade Integration

• REST API for StellarTrade to query smart wallet activity
• "Smart wallets are buying this" signal on trade interface
• Copy trade feature (watch and mirror wallet moves)

---

Getting Started

Prerequisites

• Rust (latest stable)
• Go 1.21+
• Node.js 18+
• PostgreSQL 14+

Setup

# Clone the repo
git clone https://github.com/DDefiBoy/whale-tracker.git
cd whale-tracker

# Install dependencies
cd api && npm install
cd ../dashboard && npm install

# Set up environment
cp .env.example .env
# Edit .env with your Horizon API endpoint and DB credentials

# Run database migrations
npm run migrate

# Start the monitor
cd monitor && go run main.go

# Start the API
cd api && npm run dev

# Start the dashboard
cd dashboard && npm run dev

---

Environment Variables

# Stellar
HORIZON_URL=https://horizon.stellar.org
STELLAR_NETWORK=mainnet

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/whale_tracker

# Alerts
WEBHOOK_URL=your_webhook_url
ALERT_THRESHOLD=50000        # USD value to trigger alert

# Scoring
SCORE_REFRESH_INTERVAL=3600  # seconds between score recalculations
MIN_WALLET_AGE_DAYS=30       # minimum wallet age to be scored
MIN_TRANSACTION_COUNT=10     # minimum transactions to be scored

---

Integration with StellarTrade

This tracker exposes a simple API that StellarTrade queries to surface smart money intelligence:

GET /api/wallets/top          — top scored wallets
GET /api/wallets/:address     — individual wallet profile
GET /api/assets/:code/whales  — smart wallets holding a specific asset
GET /api/alerts/recent        — recent smart wallet moves

---

Contributing

This repo is part of the StellarTrade ecosystem. Contributions welcome.

1. Fork the repo
2. Create a feature branch
3. Submit a PR with a clear description of what you changed and why

---

License

MIT

---

Built for the Stellar ecosystem. Powered by Horizon API.