Understanding Token Stats

The token-stats endpoint is the core of the Athena AI Smart Money API, providing comprehensive sentiment analysis and positioning data for cryptocurrencies.

Basic Usage

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats"

Key Features

1. Priority Tokens

BTC, ETH, and SOL always appear first in the results, as they represent the most important market indicators.

2. Pinned Tokens

Pin specific tokens to appear after priority tokens:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?pinned=XRP,VIRTUAL,kBONK"

Note: Token symbols are case-insensitive. Both kBONK and KBONK will work correctly.

3. Hold Time Metrics

Get detailed hold time analysis (slower response):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?include_hold_times=true"

Response includes:

• signal_duration: Classification (ultra-short-term, short-term, medium-term, long-term)
• avg_hold_hours: Average hold time across positions
• median_hold_hours: Median hold time across positions

4. Filtering Options

Filter by minimum positions:

?min_positions=10  # Only tokens with 10+ positions

Filter by position type:

?position_type=LONG  # Only long-biased tokens

5. Sorting Options

Sort results by various metrics:

?sort_by=positions&sort_order=desc  # Most positions first
?sort_by=money_flow                 # By money flow
?sort_by=volatility                 # By volatility

Understanding Position vs Money Percentage

• Position Percentage: Based on the count of positions (e.g., "61% LONG" means 61% of traders are long)
• Money Percentage: Based on notional value (e.g., "96% LONG" means 96% of the money is long)

When these diverge significantly, it often indicates that larger traders have a different view than smaller ones.

Performance Optimization

By default, include_hold_times=false for faster responses (~1.8s vs ~14-22s). Only enable hold times when needed.

Example: Advanced Query

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.0xathena.ai/smart-money/token-stats?min_positions=5&position_type=LONG&sort_by=money_flow&include_hold_times=true&pinned=DOGE,ARB"

This query:

• Filters for tokens with 5+ positions
• Shows only LONG-biased tokens
• Sorts by money flow
• Includes hold time metrics
• Pins DOGE and ARB to appear after BTC/ETH/SOL

Links: Website · GitHub · Support