API Endpoints Overview

The Athena AI Smart Money API provides multiple endpoints for accessing smart money positioning data, wallet analytics, and market insights. This guide explains what each endpoint does and when to use it.

Endpoints Summary

Token Stats

Endpoint: /smart-money/token-stats Method: GET Authentication: Required (Bearer token)

What It Does

Returns smart money positioning data for all tracked tokens with extensive filtering, sorting, and analysis options.

Primary Use Cases

1. Finding trading opportunities - Identify tokens with strong LONG or SHORT consensus
2. Confirming trade ideas - Validate your analysis with smart money positioning
3. Market scanning - Discover emerging opportunities before retail
4. Risk management - Avoid tokens with conflicting or weak signals

Key Parameters

Filtering:

• position_type: Filter by LONG, SHORT, or NEUTRAL positions
• min_positions: Require minimum number of traders (quality filter)
• min_notional_usd: Filter by position size (whale tracking)
• signal_strength: Filter by confidence level (strong/moderate/weak)

Sorting:

• sort_by: Order by percentage, positions, money_flow, volatility, etc.
• sort_order: asc (ascending) or desc (descending)

Enrichment:

• include_confidence: Add confidence scores and signal strength
• include_changes: Show position changes over time windows
• include_hold_times: See how long positions are held
• include_volatility: Get volatility and stability metrics
• include_trends: Identify trend direction and strength

Pagination:

• limit: Number of results (default: 13)
• offset: Skip results for pagination

Special:

• pinned: Pin specific tokens to appear after BTC/ETH/SOL
• refresh: Bypass cache for real-time data

Example Queries

High-conviction LONG plays:

GET /smart-money/token-stats?position_type=LONG&include_confidence=true&signal_strength=strong&min_positions=10&limit=5

Whale accumulation:

GET /smart-money/token-stats?min_notional_usd=1000000&include_changes=true&change_window=24h&sort_by=money_flow&sort_order=desc

Contrarian reversals:

GET /smart-money/token-stats?position_type=SHORT&include_changes=true&change_window=24h&sort_by=position_change&sort_order=asc&include_confidence=true&signal_strength=strong

Response Structure

{
  "data": [
    {
      "token": "BTC",
      "total_positions": 18,
      "position_percentage": "67% LONG",
      "money_percentage": "89% LONG",
      "position": "LONG",
      "confidence": 87,
      "signal_strength": "strong",
      "money_flow": "+$12.5M",
      "position_change": "+8%",
      "volatility": "low",
      "trend_direction": "bullish",
      "signal_duration": "medium-term"
    }
  ],
  "meta": {
    "total_count": 44,
    "returned_count": 5
  },
  "timestamp": "2025-01-28T19:45:32.123Z"
}

Learn More

See the following guides in the sidebar:

• Parameter Chaining Guide - Advanced query combinations
• Core Concepts - Understanding the metrics
• Use Cases - Real-world trading examples

Top Traders Portfolio

Endpoint: /smart-money/top-traders-portfolio Method: GET Authentication: Required (Bearer token)

What It Does

Returns the aggregated portfolio allocation of the top 5 most consistent traders, showing their collective positioning as percentage allocations.

Primary Use Cases

1. Portfolio construction - Mirror the best traders' allocations
2. Risk management - Diversify based on professional positioning
3. Conviction analysis - See where top traders have highest exposure
4. Benchmark comparison - Compare your portfolio to the pros

Key Parameters

Options:

• all_wallets: Analyze all active Hyperliquid wallets instead of just top 5
• refresh: Bypass 4-hour cache for fresh data
• limit: Number of tokens to return (default: all)

Example Queries

Top 5 traders portfolio:

GET /smart-money/top-traders-portfolio?limit=10

All wallets analysis:

GET /smart-money/top-traders-portfolio?all_wallets=true&limit=15

Response Structure

{
  "data": [
    {
      "token": "BTC",
      "allocation_percentage": "28.5%",
      "total_positions": 4,
      "avg_position_size_usd": 2450000,
      "position_direction": "LONG"
    },
    {
      "token": "ETH",
      "allocation_percentage": "22.3%",
      "total_positions": 3,
      "avg_position_size_usd": 1820000,
      "position_direction": "LONG"
    }
  ],
  "meta": {
    "total_allocation": "100%",
    "trader_count": 5,
    "total_portfolio_value_usd": 34500000
  },
  "timestamp": "2025-01-28T19:45:32.123Z"
}

How to Use

1. Mirror allocation: Use percentages to size your own positions
2. Identify conviction: Higher allocations = higher conviction
3. Diversification: Top traders spread risk across multiple tokens
4. Rebalance trigger: When allocations shift >5%, consider rebalancing

Learn More

See the Use Cases guide in the sidebar for portfolio construction examples.

Website Data

Endpoint: /smart-money/website-data Method: GET Authentication: Required (Bearer token)

What It Does

Returns pre-formatted, simplified token data optimized for website and dashboard display. This endpoint provides cleaner, more concise data compared to /token-stats.

Primary Use Cases

1. Website integration - Display smart money data on your site
2. Dashboard creation - Build trading dashboards
3. Mobile apps - Simplified data for mobile displays
4. Quick overviews - Fast, concise market snapshot

Key Parameters

Same filtering options as /token-stats but returns simplified output format.

Response Structure

{
  "data": [
    {
      "token": "BTC",
      "position": "61% LONG",
      "total_positions": 18
    }
  ],
  "timestamp": "2025-01-28T19:45:32.123Z",
  "meta": {
    "priority_tokens": ["BTC", "ETH", "SOL"],
    "others_sorted_by": "open_interest",
    "total_returned": 3
  }
}

When to Use vs Token Stats

• Use /website-data when you need simple, display-friendly data
• Use /token-stats when you need detailed analysis with all metrics

Wallet Analytics

Endpoint: /smart-money/wallet-analytics/{address} Method: GET Authentication: Required (Bearer token)

What It Does

Provides detailed analytics for a specific wallet address, including position history, performance metrics, and trading patterns.

Primary Use Cases

1. Wallet research - Analyze specific traders before following
2. Performance tracking - Monitor your favorite traders
3. Strategy analysis - Understand how successful traders operate
4. Due diligence - Verify claims about trader performance

Path Parameters

• address: Ethereum-format wallet address (0x-prefixed, 40 hex characters)

Example Query

GET /smart-money/wallet-analytics/0x1234567890123456789012345678901234567890

Response Structure

{
  "address": "0x1234567890123456789012345678901234567890",
  "performance": {
    "total_pnl_usd": 1250000,
    "win_rate": 68.5,
    "sharpe_ratio": 2.1,
    "max_drawdown": -12.3
  },
  "current_positions": [
    {
      "token": "BTC",
      "direction": "LONG",
      "size_usd": 2500000,
      "entry_price": 42000,
      "hold_duration_hours": 48.5
    }
  ],
  "statistics": {
    "total_trades": 142,
    "avg_trade_size_usd": 850000,
    "avg_hold_time_hours": 72.3
  }
}

Error Responses

Invalid address format (400):

{
  "error": "Bad Request",
  "message": "Invalid address format. Expected 0x-prefixed 40 hex characters.",
  "code": "INVALID_ADDRESS"
}

Wallet not tracked (404):

{
  "error": "Not Found",
  "message": "Wallet address not found in tracked wallets"
}

Market Regime

Endpoint: /smart-money/market-regime Method: GET Authentication: Required (Bearer token)

What It Does

Analyzes overall market conditions and smart money behavior to classify the current market regime (bull, bear, ranging, volatile).

Primary Use Cases

1. Strategy selection - Choose strategies appropriate for current regime
2. Risk management - Adjust position sizes based on market conditions
3. Trend identification - Understand macro market direction
4. Entry timing - Wait for favorable market regimes

Response Structure

{
  "regime": "risk-on",
  "confidence": 78,
  "characteristics": {
    "long_ratio": 0.68,
    "volatility": "medium",
    "trend": "bullish",
    "momentum": "strong"
  },
  "timestamp": "2025-01-28T19:45:32.123Z"
}

Market Regimes

• risk-on: Bullish, high LONG positioning, low volatility
• risk-off: Bearish, high SHORT positioning, elevated volatility
• ranging: Neutral positioning, low volatility
• volatile: Mixed signals, high volatility, uncertain direction

Pattern Analysis

Endpoint: /smart-money/pattern-analysis Method: GET Authentication: Required (Bearer token)

What It Does

Identifies trading patterns in smart money positioning, such as accumulation, distribution, breakouts, and reversals.

Primary Use Cases

1. Pattern detection - Find setup patterns automatically
2. Signal generation - Get alerts when patterns form
3. Technical analysis - Combine with chart patterns
4. Entry confirmation - Validate technical setups with smart money patterns

Response Structure

{
  "patterns": [
    {
      "token": "BTC",
      "pattern": "accumulation",
      "confidence": 82,
      "duration_hours": 72,
      "description": "Steady increase in LONG positions over 3 days"
    },
    {
      "token": "ETH",
      "pattern": "distribution",
      "confidence": 71,
      "duration_hours": 48,
      "description": "Gradual decrease in LONG positions over 2 days"
    }
  ]
}

Detected Patterns

• accumulation: Steady increase in positions
• distribution: Gradual position reduction
• reversal: Sharp change in direction
• breakout: Sudden increase in conviction
• consolidation: Stable positioning, no major changes

Token Correlations

Endpoint: /smart-money/token-correlations Method: GET Authentication: Required (Bearer token)

What It Does

Analyzes how different tokens move together based on smart money positioning, helping identify correlated and uncorrelated pairs.

Primary Use Cases

1. Portfolio diversification - Choose uncorrelated assets
2. Hedge construction - Find negatively correlated pairs
3. Risk management - Avoid over-concentration in correlated tokens
4. Pair trading - Identify correlation breakdowns

Response Structure

{
  "correlations": [
    {
      "token_pair": "BTC-ETH",
      "correlation": 0.89,
      "strength": "very-high"
    },
    {
      "token_pair": "BTC-DOGE",
      "correlation": -0.32,
      "strength": "negative"
    }
  ]
}

Correlation Strength

• very-high: 0.8-1.0 (highly correlated)
• high: 0.6-0.79
• moderate: 0.3-0.59
• low: 0.1-0.29
• uncorrelated: -0.1 to 0.1
• negative: < -0.1 (inverse relationship)

Tracked Wallets

Endpoint: /smart-money/tracked-wallets Method: GET Authentication: Required (Bearer token)

What It Does

Returns a list of all wallet addresses currently tracked by the API, along with basic statistics for each wallet.

Primary Use Cases

1. Discovery - See which wallets we're tracking
2. Research - Find interesting wallets to analyze
3. Verification - Check if a specific wallet is tracked
4. Integration - Get wallet list for your own analysis

Response Structure

{
  "wallets": [
    {
      "address": "0x1234567890123456789012345678901234567890",
      "total_positions": 12,
      "avg_position_size_usd": 1200000,
      "active_since": "2024-01-15T00:00:00Z"
    }
  ],
  "meta": {
    "total_wallets": 61,
    "active_wallets": 58
  }
}

Demo Token Stats

Endpoint: /smart-money/demo-token-stats Method: GET Authentication: None (Public)

What It Does

Returns sample data with the exact same structure as /token-stats endpoint, perfect for testing integrations before getting an API key.

Primary Use Cases

1. Testing integration - Test your code without authentication
2. Prototyping - Build features before getting API access
3. Evaluation - See response format before committing
4. Development - Local development without rate limits

Key Features

• Same response structure as /token-stats
• Sample data that looks realistic
• Supports all query parameters
• No authentication required
• No rate limits

Example Query

GET /smart-money/demo-token-stats?limit=5

Response

Returns sample data with same structure as /token-stats. Perfect for building your application before getting a real API key.

Internal/Operational Endpoints

The following endpoints are for internal use only and require authentication:

Create Daily Summary

Endpoint: /smart-money/create-daily-summary Method: POST Authentication: Required (Bearer token) Status: 202 Accepted (async operation)

Creates a daily market summary report. Returns immediately with task ID, summary generated asynchronously.

Data Maintenance

Endpoint: /smart-money/data-maintenance Method: POST Authentication: Required (Bearer token)

Triggers background data cleanup and maintenance tasks.

Rate Limits

All authenticated endpoints share the same rate limits:

Rate Limit Headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1640000000

429 Too Many Requests:

{
  "error": "Rate Limit Exceeded",
  "message": "You have exceeded the rate limit of 100 requests per minute",
  "retry_after": 45
}

Choosing the Right Endpoint

For Trading Decisions

→ Use /token-stats with appropriate filters

For Portfolio Management

→ Use /top-traders-portfolio to mirror professionals

For Website/Dashboard

→ Use /website-data for clean, simple output

For Wallet Research

→ Use /wallet-analytics/{address} for specific traders

For Market Context

→ Use /market-regime to understand conditions

For Testing

→ Use /demo-token-stats before getting API key

Next Steps

Explore the following guides in the sidebar:

• Quick Start Guide - Make your first API call
• Parameter Chaining Guide - Master query combinations
• Use Cases - Real-world trading examples
• Core Concepts - Understand the data
• API Reference - Complete technical documentation (see Reference section)

Need Help?

• Email: support@0xathena.ai
• GitHub: Report Issues
• Status: Check API health at https://api.0xathena.ai/smart-money/test

Links: Website · GitHub · Support