Athena AI Smart Money APIAPI Reference

Common Use Cases

This guide demonstrates real-world applications of the Athena AI Smart Money API with practical examples for different trading strategies and use cases.

Table of Contents

  1. Day Trading & Scalping
  2. Swing Trading & Position Management
  3. Whale Tracking & Institutional Flow
  4. Contrarian Reversals
  5. Risk Management
  6. Portfolio Construction
  7. Market Research & Analysis
  8. Automated Trading Bots

Day Trading & Scalping

Use Case: Find High-Momentum Intraday Opportunities

Goal: Identify tokens with strong smart money momentum over the past hour for quick scalping trades.

Query:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?position_type=LONG&include_changes=true&change_window=1h&sort_by=money_flow&sort_order=desc&limit=5&include_confidence=true&signal_strength=strong"

What This Does:

  • position_type=LONG: Focus on bullish setups
  • include_changes=true&change_window=1h: Show 1-hour momentum
  • sort_by=money_flow&sort_order=desc: Biggest capital inflows first
  • include_confidence=true&signal_strength=strong: Only high-conviction signals
  • limit=5: Top 5 opportunities

Sample Response:

{
  "data": [
    {
      "token": "SOL",
      "total_positions": 15,
      "position_percentage": "80% LONG",
      "money_percentage": "92% LONG",
      "position": "LONG",
      "money_flow": "+$8.2M",
      "position_change": "+12%",
      "confidence": 88,
      "signal_strength": "strong",
      "change_window": "1h"
    }
  ]
}

How to Trade This:

  1. SOL shows +$8.2M capital inflow in 1 hour (strong institutional buying)
  2. 88 confidence score indicates high conviction
  3. 80% of positions are LONG (strong consensus)
  4. Enter LONG position with tight stop-loss for scalping
  5. Monitor for reversal signals every 30-60 minutes

Pro Tip: For day trading, combine smart money signals with technical support/resistance levels for optimal entries.

Swing Trading & Position Management

Use Case: Find Multi-Day Swing Trade Setups

Goal: Identify tokens where smart money is holding positions for several days, indicating conviction in a sustained trend.

Query:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?min_positions=10&include_hold_times=true&include_confidence=true&signal_strength=strong&position_type=LONG&limit=10"

What This Does:

  • min_positions=10: High-quality signals with many traders
  • include_hold_times=true: See how long positions are held
  • signal_strength=strong: Only high-conviction plays
  • position_type=LONG: Bullish setups

Sample Response:

{
  "data": [
    {
      "token": "ETH",
      "total_positions": 24,
      "position_percentage": "71% LONG",
      "money_percentage": "85% LONG",
      "position": "LONG",
      "signal_duration": "medium-term",
      "avg_hold_hours": 122.5,
      "median_hold_hours": 96.3,
      "confidence": 82,
      "signal_strength": "strong"
    }
  ]
}

How to Trade This:

  1. ETH has 24 positions with 71% LONG consensus
  2. Medium-term signal duration (96h median = 4 days)
  3. Smart money is holding for days, not hours (conviction)
  4. Enter LONG position with 3-7 day target
  5. Use wider stop-loss suitable for swing trading

Whale Tracking & Institutional Flow

Use Case: Track Million-Dollar+ Whale Positions

Goal: Monitor only the largest institutional positions to see where "big money" is moving.

Query:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?min_notional_usd=1000000&include_changes=true&change_window=24h&sort_by=money_flow&sort_order=desc&limit=10"

What This Does:

  • min_notional_usd=1000000: Only positions worth $1M+ (whale-sized)
  • include_changes=true&change_window=24h: 24-hour whale activity
  • sort_by=money_flow: Show where most whale capital is flowing

Sample Response:

{
  "data": [
    {
      "token": "BTC",
      "total_positions": 8,
      "position_percentage": "75% LONG",
      "money_percentage": "94% LONG",
      "position": "LONG",
      "money_flow": "+$24.8M",
      "position_change": "+8%",
      "change_window": "24h"
    }
  ]
}

How to Trade This:

  1. BTC has 8 whale positions (all $1M+ each)
  2. 94% of whale capital is LONG (extreme conviction)
  3. +$24.8M net whale buying in 24 hours
  4. Follow whale flow: Enter LONG position
  5. Whales rarely wrong on multi-day timeframes

Why This Works:

  • Whale positions move markets
  • $1M+ positions held by professionals, not retail
  • Institutional flow is most predictive metric

Important: Whale positions typically have longer timeframes than retail. Don't expect immediate price action - whales think in days and weeks, not hours.

Contrarian Reversals

Use Case: Find Potential Reversal Opportunities

Goal: Identify tokens where smart money positioning is shifting dramatically, suggesting a potential trend reversal.

Query:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?position_type=SHORT&min_positions=8&include_confidence=true&signal_strength=strong&include_changes=true&change_window=24h&sort_by=position_change&sort_order=asc&limit=10"

What This Does:

  • position_type=SHORT: Currently bearish positioning
  • sort_by=position_change&sort_order=asc: Biggest decreases (reversal signal)
  • signal_strength=strong: Only high-conviction signals
  • Note: signal_strength requires include_confidence=true
  • Note: sort_by=position_change requires include_changes=true

Sample Response:

{
  "data": [
    {
      "token": "AVAX",
      "total_positions": 12,
      "position_percentage": "58% SHORT",
      "money_percentage": "62% SHORT",
      "position": "SHORT",
      "position_change": "-18%",
      "confidence": 76,
      "signal_strength": "strong",
      "change_window": "24h"
    }
  ]
}

How to Trade This:

  1. AVAX currently 58% SHORT (bearish)
  2. BUT position change is -18% (large decrease in SHORT consensus)
  3. This means smart money is closing SHORTs or opening LONGs
  4. Potential reversal from bearish to bullish
  5. Enter LONG position betting on reversal continuation

Why This Works:

  • Smart money often leads reversals before retail
  • Large position changes indicate conviction shift
  • Contrarian to current positioning but aligned with emerging flow

Risk Management

Use Case: Avoid High-Volatility, Low-Confidence Plays

Goal: Filter out risky, uncertain positions and focus only on stable, high-confidence opportunities.

Query:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?min_positions=10&include_confidence=true&signal_strength=strong&include_volatility=true&sort_by=volatility&sort_order=asc&limit=10"

What This Does:

  • min_positions=10: Require many positions (quality filter)
  • signal_strength=strong: Only high-confidence signals
  • include_volatility=true&sort_by=volatility&sort_order=asc: Lowest volatility first
  • Focus on stable, predictable positioning

Sample Response:

{
  "data": [
    {
      "token": "BTC",
      "total_positions": 18,
      "position_percentage": "67% LONG",
      "money_percentage": "89% LONG",
      "position": "LONG",
      "confidence": 91,
      "signal_strength": "strong",
      "volatility": "low",
      "volatility_score": 0.32
    }
  ]
}

How to Trade This:

  1. BTC has 18 positions with 91 confidence (very high quality)
  2. Low volatility (0.32) means stable positioning
  3. Smart money is aligned and not flip-flopping
  4. Safe, conservative LONG setup with reduced risk
  5. Ideal for larger position sizes or lower risk tolerance

Risk Management Rules:

  • Never trade: volatility: "very-high" or confidence < 50
  • Reduce size: volatility: "high" or confidence 50-69
  • Normal size: volatility: "medium" or confidence 70-79
  • Larger size: volatility: "low" or confidence 80+

Portfolio Construction

Use Case: Build a Balanced Smart Money Portfolio

Goal: Create a portfolio allocation based on top traders' collective positioning across multiple tokens.

Query 1: Get Top Traders Portfolio

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/top-traders-portfolio?limit=10"

Sample Response:

{
  "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"
    },
    {
      "token": "SOL",
      "allocation_percentage": "15.8%",
      "total_positions": 5,
      "avg_position_size_usd": 980000,
      "position_direction": "LONG"
    }
  ]
}

How to Build Portfolio:

  1. Top 5 traders allocate 28.5% to BTC, 22.3% to ETH, 15.8% to SOL
  2. Mirror their portfolio: If you have $10,000 to invest:
    • BTC: $2,850 (28.5%)
    • ETH: $2,230 (22.3%)
    • SOL: $1,580 (15.8%)
    • Continue for remaining tokens
  3. Rebalance weekly or when allocations shift significantly

Query 2: Validate with Confidence Scores

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?pinned=BTC,ETH,SOL&include_confidence=true&signal_strength=strong&limit=10"

This confirms each allocation has strong smart money conviction.

Market Research & Analysis

Use Case: Understand Market-Wide Sentiment

Goal: Get a comprehensive view of smart money positioning across all tracked tokens.

Query:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?min_positions=5&include_confidence=true&include_changes=true&change_window=24h&include_trends=true&limit=50"

What This Does:

  • min_positions=5: Quality filter
  • include_confidence=true: See conviction levels
  • include_changes=true&change_window=24h: Daily shifts
  • include_trends=true: Identify trend patterns
  • limit=50: Comprehensive market view

Sample Response:

{
  "data": [
    {
      "token": "BTC",
      "position": "LONG",
      "confidence": 87,
      "position_change": "+5%",
      "trend_direction": "bullish",
      "trend_strength": 0.78
    },
    {
      "token": "ETH",
      "position": "LONG",
      "confidence": 82,
      "position_change": "+3%",
      "trend_direction": "bullish",
      "trend_strength": 0.71
    },
    {
      "token": "DOGE",
      "position": "SHORT",
      "confidence": 65,
      "position_change": "-8%",
      "trend_direction": "bearish",
      "trend_strength": 0.54
    }
  ],
  "meta": {
    "total_count": 48,
    "returned_count": 50
  }
}

Market Analysis:

  1. Count LONG vs SHORT positions: 32 LONG, 16 SHORT = 67% bullish market
  2. Average confidence: 74 = moderate-to-high conviction
  3. Trend directions: Mostly bullish, few bearish outliers
  4. Position changes: +3.2% average = accumulation phase
  5. Conclusion: Smart money is bullish on crypto broadly

Use for:

  • Market timing (enter when smart money turns bullish)
  • Sector rotation (identify which tokens getting attention)
  • Risk-on vs risk-off (LONG dominance = risk-on)
  • Portfolio hedging (SHORT positions as hedge ideas)

Automated Trading Bots

Use Case: Build a Trading Bot with Smart Money Signals

Goal: Automate trade entries based on smart money positioning changes.

Example Strategy: Momentum Following Bot

Step 1: Poll API Every 15 Minutes

const POLL_INTERVAL = 15 * 60 * 1000; // 15 minutes

setInterval(async () => {
  const response = await fetch(
    'https://api.0xathena.ai/smart-money/token-stats?position_type=LONG&include_changes=true&change_window=1h&sort_by=money_flow&sort_order=desc&limit=5&include_confidence=true&signal_strength=strong',
    {
      headers: {
        Authorization: 'Bearer YOUR_API_KEY',
      },
    }
  );

  const data = await response.json();
  processSignals(data);
}, POLL_INTERVAL);

Step 2: Define Entry Rules

function processSignals(data) {
  data.data.forEach((token) => {
    // Entry conditions
    const shouldEnter =
      token.position === 'LONG' &&
      token.confidence >= 80 &&
      parseFloat(token.money_flow) > 5000000 && // $5M+ inflow
      parseFloat(token.position_change) > 10; // 10%+ increase

    if (shouldEnter && !hasPosition(token.token)) {
      enterLongPosition(token.token, calculatePositionSize(token));
    }
  });
}

Step 3: Define Exit Rules

function checkExits() {
  activePositions.forEach(async (position) => {
    const response = await fetch(
      `https://api.0xathena.ai/smart-money/token-stats?token=${position.token}&include_changes=true&change_window=1h`,
      {
        headers: { Authorization: 'Bearer YOUR_API_KEY' },
      }
    );

    const data = await response.json();
    const tokenData = data.data[0];

    // Exit conditions
    const shouldExit =
      tokenData.position === 'SHORT' || // Smart money flipped
      tokenData.confidence < 50 || // Low confidence
      parseFloat(tokenData.money_flow) < -3000000; // $3M+ outflow

    if (shouldExit) {
      closeLongPosition(position.token);
    }
  });
}

Step 4: Position Sizing Based on Confidence

function calculatePositionSize(token) {
  const baseSize = 1000; // $1000 base position

  if (token.confidence >= 90) return baseSize * 2.0; // 2x for very high confidence
  if (token.confidence >= 80) return baseSize * 1.5; // 1.5x for high confidence
  if (token.confidence >= 70) return baseSize * 1.0; // 1x for good confidence

  return baseSize * 0.5; // 0.5x for moderate confidence
}

Bot Performance Considerations:

  • Use cached data (15-min cache) to avoid rate limits
  • Monitor rate limit headers: X-RateLimit-Remaining
  • Implement exponential backoff on 429 errors
  • Log all signals and trades for backtesting
  • Start with paper trading before live capital

Advanced Combinations

Use Case: Multi-Factor Analysis

Goal: Combine multiple signals for highest-conviction opportunities.

Query:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?min_positions=10&min_notional_usd=500000&include_confidence=true&signal_strength=strong&include_volatility=true&include_changes=true&change_window=24h&include_trends=true&include_hold_times=true&limit=5"

What This Does:

  • min_positions=10: Many traders (quality)
  • min_notional_usd=500000: Large positions (institutional)
  • signal_strength=strong: High confidence (conviction)
  • include_volatility=true: Check stability (risk)
  • include_changes=true: See momentum (timing)
  • include_trends=true: Identify trend (direction)
  • include_hold_times=true: Understand duration (strategy)

Sample Response:

{
  "data": [
    {
      "token": "BTC",
      "total_positions": 18,
      "position_percentage": "72% LONG",
      "money_percentage": "91% LONG",
      "position": "LONG",
      "confidence": 89,
      "signal_strength": "strong",
      "volatility": "low",
      "volatility_score": 0.28,
      "position_change": "+8%",
      "money_flow": "+$18.5M",
      "trend_direction": "bullish",
      "trend_strength": 0.82,
      "signal_duration": "medium-term",
      "median_hold_hours": 108.2
    }
  ]
}

Perfect Setup Checklist:

  • ✅ 18 positions (high quality)
  • ✅ 89 confidence (very high conviction)
  • ✅ Low volatility (stable, predictable)
  • ✅ +$18.5M money flow (strong buying)
  • ✅ Bullish trend with 0.82 strength (clear direction)
  • ✅ Medium-term duration (multi-day hold)

This is a "dream setup" - all factors aligned for high probability trade.

Integration Examples

JavaScript/Node.js Application 

import fetch from 'node-fetch';

class SmartMoneyAPI {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.0xathena.ai/smart-money';
  }

  async getTokenStats(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    const url = `${this.baseUrl}/token-stats?${queryString}`;

    const response = await fetch(url, {
      headers: {
        Authorization: `Bearer ${this.apiKey}`,
      },
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }

    return await response.json();
  }

  async getWhalePositions() {
    return this.getTokenStats({
      min_notional_usd: 1000000,
      include_changes: true,
      change_window: '24h',
      sort_by: 'money_flow',
      sort_order: 'desc',
      limit: 10,
    });
  }

  async getHighConfidenceLongs() {
    return this.getTokenStats({
      position_type: 'LONG',
      include_confidence: true,
      signal_strength: 'strong',
      min_positions: 10,
      limit: 5,
    });
  }
}

// Usage
const api = new SmartMoneyAPI(process.env.ATHENA_API_KEY);

const whales = await api.getWhalePositions();
console.log('Whale positions:', whales.data);

const highConviction = await api.getHighConfidenceLongs();
console.log('High conviction longs:', highConviction.data);

Python Trading Bot 

import requests
import time
import os

class SmartMoneyTrader:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = 'https://api.0xathena.ai/smart-money'
        self.headers = {'Authorization': f'Bearer {api_key}'}

    def get_token_stats(self, **params):
        url = f'{self.base_url}/token-stats'
        response = requests.get(url, headers=self.headers, params=params)
        response.raise_for_status()
        return response.json()

    def find_momentum_plays(self):
        return self.get_token_stats(
            position_type='LONG',
            include_changes=True,
            change_window='1h',
            sort_by='money_flow',
            sort_order='desc',
            include_confidence=True,
            signal_strength='strong',
            limit=5
        )

    def run_bot(self, poll_interval=900):  # 15 minutes
        while True:
            try:
                signals = self.find_momentum_plays()

                for token in signals['data']:
                    if self.should_enter(token):
                        self.enter_position(token)

                self.check_exits()

            except Exception as e:
                print(f'Error: {e}')

            time.sleep(poll_interval)

    def should_enter(self, token):
        return (
            token['confidence'] >= 80 and
            float(token['money_flow'].replace('$', '').replace('M', '')) > 5 and
            float(token['position_change'].replace('%', '')) > 10
        )

    def enter_position(self, token):
        print(f'Entering LONG {token["token"]} - Confidence: {token["confidence"]}')
        # Add your exchange API integration here

    def check_exits(self):
        # Check active positions and exit if conditions met
        pass

# Usage
trader = SmartMoneyTrader(os.getenv('ATHENA_API_KEY'))
trader.run_bot()

Best Practices

1. Always Validate Signals

Don't trade blindly on API data. Combine smart money signals with:

  • Technical analysis (support/resistance)
  • Fundamental analysis (project quality)
  • Market conditions (overall trend)
  • Your own research

2. Use Appropriate Position Sizing

  • High confidence (80+): Normal or larger size
  • Moderate confidence (60-79): Reduced size
  • Low confidence (<60): Minimal size or avoid

3. Respect Rate Limits

  • Use cached data when possible
  • Implement exponential backoff on errors
  • Monitor X-RateLimit-Remaining header
  • Don't poll faster than necessary

4. Combine Multiple Metrics

Single metrics can be misleading. Always look at:

  • Position percentage AND money percentage
  • Confidence score AND position count
  • Current positioning AND recent changes
  • Volatility AND trend strength

5. Monitor Performance

  • Track win rate for different query combinations
  • Measure profit/loss per signal type
  • Optimize parameters based on results
  • Backtest strategies before live trading

Next Steps

Explore the following guides in the sidebar:

  • Core Concepts - Understand the metrics in depth
  • Parameter Chaining Guide - Master advanced queries
  • API Reference - Complete endpoint documentation (see Reference section)
  • Authentication - Get your API key and set up

Need Help?

Disclaimer: The information provided by Athena AI is for informational purposes only and should not be considered financial advice. Cryptocurrency investments carry significant risk. Always conduct your own research and consult with qualified financial advisors before making investment decisions. Athena AI is not responsible for any losses incurred from using this information.

Links: Website · GitHub · Support

© 2025 Athena AI. All rights reserved.