Core Concepts

This guide explains the fundamental concepts and metrics used throughout the Athena AI Smart Money API.

Understanding Smart Money Data

What is a "Position"?

A position represents a single trade held by a professional trader on a perpetual futures platform. Each position has:

• Direction: LONG (bullish) or SHORT (bearish)
• Size: The notional value in USD
• Token: The cryptocurrency being traded (BTC, ETH, SOL, etc.)
• Entry Time: When the position was opened
• Hold Duration: How long the position has been held

Our API aggregates these individual positions across 60+ professional traders to give you collective market intelligence.

Key Metrics Explained

{
  "token": "BTC",
  "position_percentage": "61% LONG",
  "money_percentage": "96% LONG"
}

// Strong bullish consensus
{
  "position_percentage": "75% LONG",
  "money_percentage": "82% LONG",
  "position": "LONG"
}

// Bearish consensus
{
  "position_percentage": "65% SHORT",
  "money_percentage": "71% SHORT",
  "position": "SHORT"
}

// Mixed signals
{
  "position_percentage": "52% LONG",
  "money_percentage": "48% SHORT",
  "position": "NEUTRAL"
}

Hold Time Metrics

Understanding how long positions are typically held helps identify signal duration and trading styles.

Signal Duration Classifications

The API classifies positions based on median hold time:

Hold Time Fields

When include_hold_times=true is specified, you'll receive:

{
  "token": "ETH",
  "signal_duration": "medium-term",
  "avg_hold_hours": 122.5,
  "median_hold_hours": 96.3
}

Field Definitions:

• signal_duration: Classification based on median hold time
• avg_hold_hours: Mean hold time across all positions (can be skewed by outliers)
• median_hold_hours: Middle value of all hold times (more robust to outliers)

Interpretation Example:

• Medium-term (96.3h median): Traders are holding for 4+ days on average
• This suggests conviction in a multi-day trend rather than quick flips
• Median < average (96.3 < 122.5) indicates some very long-term positions pulling the average up

Confidence and Signal Strength

The API provides confidence scores to assess signal quality. For parameter specifications, see the API Reference.

Understanding Confidence

Confidence scores (0-100) indicate signal reliability based on:

• Sample size: More trader positions = higher confidence
• Agreement: Unanimous positioning = higher confidence
• Position sizes: Larger institutional positions weighted more
• Consistency: Stable positioning over time increases confidence

How to Use Confidence in Trading

High Confidence (80-100):

• Strong conviction from multiple large positions
• Safe for larger position sizes
• Best risk/reward setups

Moderate Confidence (60-79):

• Good trader agreement
• Suitable for normal position sizing
• Balanced risk profile

Low Confidence (< 60):

• Mixed signals or limited data
• Use smaller positions or avoid
• Higher uncertainty

Signal Strength

Signal strength provides quick filtering based on confidence thresholds. Enable with ?include_confidence=true&signal_strength=strong to see only high-conviction opportunities.

See the Use Cases guide in the sidebar for trading strategies by confidence level.

Position Size Filtering

The API supports filtering by position size and trader count for quality control. See the API Reference for complete parameter specifications.

Minimum Notional Value

Filter positions by USD value using min_notional_usd to focus on institutional-sized trades:

Use Cases:

• Whale tracking: ?min_notional_usd=1000000 shows only 7-figure positions
• Institutional flow: ?min_notional_usd=500000 filters out retail noise
• Quality over quantity: Higher minimums reduce noise from small positions

Minimum Position Count

Require minimum traders with positions using min_positions for quality signals:

Recommended Values:

• Strict quality: 10+ positions ensures strong data
• Balanced: 5-8 positions balances quality and coverage
• Discovery: 1-3 positions finds emerging opportunities

Time-Based Analysis

Position Changes Over Time

Enable include_changes=true with a change_window to track positioning shifts. For full parameter details, see the API Reference.

{
  "token": "SOL",
  "position_percentage": "70% LONG",
  "position_change": "+15%",
  "change_window": "24h"
}

Available Windows: 1h, 6h, 24h, 7d

Interpretation:

• Positive change: More traders going LONG (or closing SHORTs)
• Negative change: More traders going SHORT (or closing LONGs)
• Near zero: Stable positioning, no major shifts

Usage Example:

# Track 24-hour momentum
?include_changes=true&change_window=24h&sort_by=position_change&sort_order=desc

Money Flow Analysis

Understanding Money Flow

When include_changes=true is specified, money flow shows capital movement:

{
  "token": "ETH",
  "money_flow": "+$12.5M",
  "change_window": "24h"
}

What This Means:

• Positive flow (+$12.5M): $12.5M more capital entered LONG positions (or exited SHORT)
• Negative flow (-$8.2M): $8.2M more capital entered SHORT positions (or exited LONG)
• Near zero: Capital relatively stable, no major institutional moves

Why It Matters:

• Money flow tracks actual capital, not just trader count
• Large positive flow indicates institutional accumulation
• Large negative flow suggests distribution or profit-taking
• More predictive than position count for price movement

Money Flow Sorting

Sort by money flow to find where capital is moving fastest:

# Strongest capital inflows
?include_changes=true&change_window=24h&sort_by=money_flow&sort_order=desc

# Strongest capital outflows
?include_changes=true&change_window=24h&sort_by=money_flow&sort_order=asc

Volatility and Risk Metrics

Position Volatility

When include_volatility=true is specified:

{
  "token": "AVAX",
  "position_volatility_24h": 26,
  "volatility_trend": "increasing"
}

Volatility Score (0-100):

• 0-10: Very low - Stable positioning, minimal changes
• 11-20: Low - Moderate stability, some fluctuation
• 21-30: Medium - Average volatility, regular changes
• 31-40: High - Significant uncertainty, frequent changes
• 41+: Very high - Extreme volatility, rapid position shifts

Volatility Trend:

• increasing: Position volatility is rising
• decreasing: Position volatility is declining
• stable: Volatility remains consistent

Use Cases:

• Risk management: Filter out high volatility (31+) tokens
• Opportunity hunting: Medium volatility (21-30) can signal upcoming moves
• Stable plays: Low volatility (0-20) for conservative strategies

Volatility-Based Sorting

# Most stable positions
?include_volatility=true&sort_by=volatility&sort_order=asc

# Most volatile (potential breakouts)
?include_volatility=true&sort_by=volatility&sort_order=desc

Trend Analysis

Trend Direction and Strength

When include_trends=true is specified:

{
  "token": "BTC",
  "trend_direction": "bullish",
  "trend_strength": 0.78
}

Trend Directions:

• bullish: Sustained increase in LONG positioning
• bearish: Sustained increase in SHORT positioning
• neutral: No clear directional trend
• reversal: Recent change in direction

Trend Strength (0-1):

• 0.8-1.0: Very strong trend
• 0.6-0.79: Strong trend
• 0.4-0.59: Moderate trend
• 0.2-0.39: Weak trend
• 0-0.19: No clear trend

Interpretation Example:

{
  "trend_direction": "bullish",
  "trend_strength": 0.78
}

This indicates smart money has been steadily accumulating LONG positions with strong conviction (0.78/1.0).

Pinned Tokens

Priority Token Ordering

By default, BTC, ETH, and SOL appear first in all responses. You can pin additional tokens to appear after these priority tokens:

# Pin specific tokens after BTC/ETH/SOL
?pinned=XRP,VIRTUAL,DOGE

# Response order: BTC, ETH, SOL, XRP, VIRTUAL, DOGE, [other tokens...]

Features:

• Case-insensitive matching (e.g., kbonk, KBONK, kBONK all match)
• Original token case preserved in response
• Invalid tokens are silently ignored
• Pinned tokens shown in response metadata

Use Cases:

• Portfolio tracking: Pin your holdings to monitor them first
• Watchlist focus: Pin tokens you're researching
• Custom dashboards: Create consistent token ordering for your application

Caching and Performance

Cache Behavior

All endpoints use intelligent caching for optimal performance:

Default Cache:

• TTL: 15 minutes for most endpoints
• Cache Key: Based on unique parameter combinations
• Shared: Same query from different users hits same cache

Cache Refresh:

# Force fresh data (bypasses cache)
?refresh=true

# Use cached data (default)
# Don't specify refresh parameter

When to Use Refresh:

• Real-time trading decisions requiring latest data
• After major market events
• When testing API changes

Performance Impact:

• Cached response: ~200-500ms
• Fresh data: ~1-3s (without hold times)
• Fresh with hold times: ~10-20s

Query Performance Optimization

Fast Queries (<2s):

• Use default parameters
• Don't include hold times
• Use cached data
• Limit to 5-10 results

Balanced Queries (3-5s):

• Add confidence or changes
• Limit to 10-25 results
• Use cached data

Comprehensive Queries (10-20s):

• Include hold times
• Include all optional metrics
• Use refresh=true
• Fetch 50+ results

Parameter Dependencies

Some parameters require others to work properly:

Required Dependencies

Error Example:

# ❌ This will return 400 Bad Request
?signal_strength=strong
# Missing: include_confidence=true

# ✅ Correct usage
?include_confidence=true&signal_strength=strong

Data Quality and Filtering

Token Coverage

• 50+ Cryptocurrencies tracked across major exchanges
• 60+ Professional Traders consistently profitable
• $100M+ in Positions real institutional-scale capital

Quality Filters

Recommended combinations for high-quality signals:

# Institutional-grade signals
?min_positions=10&min_notional_usd=500000&include_confidence=true&signal_strength=strong

# Balanced quality and coverage
?min_positions=5&include_confidence=true&signal_strength=moderate

# Discovery mode (all signals)
?min_positions=1

Next Steps

Now that you understand the core concepts, explore the following guides in the sidebar:

• Common Use Cases - Real-world trading scenarios
• Parameter Chaining Guide - Advanced query combinations
• API Reference - Complete endpoint documentation (see Reference section)
• Quick Start - Make your first API call

Need Help?

• Email: support@0xathena.ai
• GitHub: Report Issues
• Documentation: You're reading it! Bookmark this guide for reference.

Links: Website · GitHub · Support