🐋 Hyperliquid Whale Tracker v3.3

Enterprise-grade scraper for tracking whale traders on Hyperliquid DEX. Get AI-powered trading signals, copy-trading coefficients, and comprehensive portfolio analytics with data quality validation.

💰 Pay-Per-Event Pricing

This Actor uses transparent pay-per-event pricing. You only pay for what you use:

Event	Price	Description
scraper-start	$0.03	Charged once when Actor starts
scraper-stop	$0.03	Charged once when Actor completes
wallet-processed	$0.01	Per wallet scraped and analyzed
position-scraped	$0.01	Per open trading position found

💵 Cost Examples

Mode	Configuration	Est. Events	Est. Cost
Analytics	50 winners + 50 losers	~100 wallets, ~100 positions	~$2.06
Analytics	100 winners + 100 losers	~200 wallets, ~200 positions	~$4.06
Tracking	10 wallets	~10 wallets, ~20 positions	~$0.36
Leaderboard	Top 100	~100 wallets, ~100 positions	~$2.06

Note: You can set a maximum budget per run to prevent unexpected costs.

✨ Features

• Winners vs Losers Analysis - Compare trading strategies of top performers vs underperformers
• AI-Powered Signals - Divergence-based trading signals with confidence levels
• Copy-Trading Coefficients - Smart multipliers for position sizing
• Portfolio Metrics - Sharpe ratio, max drawdown, ROI tracking
• Data Quality Validation - Reliability scores and warning flags
• Real-time Positions - Track open positions across all traders
• Multiple Export Formats - JSON dataset output

🚀 Use Cases

Use Case	Mode	Description
Market Sentiment	analytics	Analyze 100+ winners vs losers to determine market bias
Wallet Monitoring	tracking	Track specific whale wallets in real-time
Top Traders	leaderboard	Get ranked list of verified profitable traders
Copy Trading	analytics	Use coefficients to adjust position sizes
Research	analytics	Export data for backtesting and analysis

📊 Output Schema

Trader Object

{
  "type": "trader",
  "address": "0x...",
  "category": "WINNER",
  "accountValue": 125000.50,
  "totalPnl": 12500.00,
  "positions": [
    {
      "coin": "BTC",
      "side": "LONG",
      "size": 1.5,
      "entryPrice": 95000,
      "unrealizedPnl": 2500
    }
  ],
  "metrics": {
    "roi": 156.7,
    "monthROI": 12.5,
    "weekROI": 3.2,
    "roiSource": "leaderboard",
    "sharpeRatio": 2.45,
    "maxDrawdown": 15.3,
    "avgDrawdown": 8.2
  },
  "dataQuality": {
    "isReliable": true,
    "reliabilityScore": 85,
    "warnings": []
  },
  "scrapedAt": "2024-01-06T12:00:00.000Z"
}

Analytics Output (KEY-VALUE: OUTPUT)

{
  "type": "analytics",
  "marketBias": {
    "sentiment": "BULLISH",
    "winnersLong": 65,
    "losersLong": 45,
    "bias": 20
  },
  "coefficients": {
    "longCoefficient": 1.0,
    "shortCoefficient": 0.8,
    "recommendation": "FAVOR_LONGS"
  },
  "signals": [
    {
      "symbol": "BTC",
      "signal": "STRONG_LONG",
      "score": 85,
      "confidence": "HIGH"
    }
  ],
  "roiStats": {
    "fromLeaderboard": 152,
    "fromFallback": 23,
    "noData": 25
  },
  "billing": {
    "isPayPerEvent": true,
    "walletsCharged": 200,
    "positionsCharged": 199,
    "totalCost": 4.05
  }
}

🔍 Data Quality System

The scraper validates data integrity and flags potential issues:

Warning Code	Severity	Meaning
LOW_SNAPSHOTS	Medium	Less than 14 data points
EXTREME_DRAWDOWN	High	100% drawdown detected
SHARPE_ROI_MISMATCH	Medium	Metrics contradict
NEGATIVE_SHARPE	Low	Poor risk-adjusted returns
NO_ROI_DATA	Medium	ROI unavailable
ZERO_BALANCE	High	Empty account

Reliability Score

• 100: Perfect data quality
• 70-99: Minor warnings, usable
• 40-69: Use with caution
• 0-39: Unreliable data

❓ FAQ

Why is Max Drawdown = 100%?

This occurs when a trader either:

1. Lost all funds at some point (liquidation)
2. Withdrew everything and re-deposited later

The historical 100% DD remains in the data even after recovery.

Why is Sharpe negative when ROI is +1000%?

ROI and Sharpe measure different time periods:

Metric	Period
ROI	Lifetime (all-time)
Sharpe	Recent 30-90 days

A trader can have +1000% lifetime ROI but negative recent Sharpe if they were profitable historically but are currently losing.

What is roiSource?

Value	Description
leaderboard	Official Hyperliquid leaderboard (most accurate)
portfolio_fallback	Calculated from PnL history
none	Could not determine ROI

📈 Signal Interpretation

Signal	Score	Meaning
STRONG_LONG	+67 to +100	Winners strongly favor longs
LONG	+34 to +66	Moderate long bias
NEUTRAL	-33 to +33	No clear direction
SHORT	-34 to -66	Moderate short bias
STRONG_SHORT	-67 to -100	Winners strongly favor shorts

💡 Copy Trading Coefficients

Use coefficients to adjust your position sizes:

// If recommendation is FAVOR_SHORTS:
// longCoefficient = 0.8, shortCoefficient = 1.0

const adjustedLongSize = baseSize * longCoefficient;  // Reduce longs
const adjustedShortSize = baseSize * shortCoefficient; // Keep shorts full

🔧 Input Parameters

Parameter	Type	Default	Description
mode	string	analytics	Operation mode: analytics, tracking, leaderboard
winnersCount	integer	50	Winners to analyze (1-200)
losersCount	integer	50	Losers to analyze (1-200)
wallets	string	-	Comma-separated addresses for tracking mode
leaderboardLimit	integer	100	Top traders count (10-500)
includePositions	boolean	true	Include open positions
calculateMetrics	boolean	true	Calculate advanced metrics
whaleHuntApiKey	string	-	Optional custom API key

📁 Output Locations

Storage	Contents
Dataset	Individual trader records (array of trader objects)
Key-Value Store	OUTPUT key with full results including analytics/signals

🛡️ Best Practices

// Filter reliable traders only
const reliableTraders = traders.filter(t => 
  t.dataQuality.isReliable && 
  t.portfolioSnapshots >= 30 &&
  t.accountValue > 1000
);

// Check warnings before using metrics
if (trader.dataQuality.warnings.includes('SHARPE_ROI_MISMATCH')) {
  console.log('⚠️ Metrics may be inconsistent');
}

🔗 Data Sources

• WhaleHunt.io - Winner/Loser classification
• Hyperliquid API - Portfolio data, positions
• Hyperliquid Leaderboard - Official ROI metrics

📝 Example Input

Analytics Mode

{
  "mode": "analytics",
  "winnersCount": 100,
  "losersCount": 100,
  "includePositions": true,
  "calculateMetrics": true
}

Tracking Mode

{
  "mode": "tracking",
  "wallets": "0x55879718b38cac09065e64c7f18419b5c5f14e31,0xf19a8f29096ced385abb7c4930548121c97c8c40"
}

Leaderboard Mode

{
  "mode": "leaderboard",
  "leaderboardLimit": 100
}

📚 Version History

v3.3.0 (Current)

• ✅ Pay-Per-Event monetization
• ✅ Data quality validation system
• ✅ Copy-trading coefficients
• ✅ ROI fallback calculation
• ✅ Full Apify SDK integration

🤝 Support

• Issues: Use the Issues tab on Apify
• Website: WhaleHunt.io
• API Docs: Hyperliquid API

⚖️ Disclaimer

This tool is for informational purposes only. Trading cryptocurrencies carries significant risk. Past performance does not guarantee future results. Always do your own research before making trading decisions.

---

Made with 🐋 by WhaleHunt.io