Parameter Chaining Guide

Overview

The Athena AI Smart Money API supports parameter chaining - combining multiple query parameters to create powerful, targeted queries. This guide demonstrates how to chain parameters effectively for different trading strategies and use cases.

Table of Contents

1. Basic Concepts
2. Common Trading Strategies
3. Performance Optimization
4. Advanced Combinations
5. Best Practices

Basic Concepts

How Parameter Chaining Works

Parameters are combined using the & separator in the URL query string. The API applies filters and transformations in this order:

1. Filtering (position_type, min_positions, timeframe, etc.)
2. Sorting (sort_by, sort_order)
3. Pagination (limit, offset)
4. Enhancement (include_hold_times, include_changes, etc.)

Example Structure

GET /smart-money/token-stats?param1=value1&param2=value2&param3=value3

Common Trading Strategies

1. Day Trading Setup

Goal: Find fresh, high-conviction LONG positions with recent momentum

?position_type=LONG
&timeframe=24h
&include_changes=true
&change_window=6h
&sort_by=money_flow
&sort_order=desc
&min_positions=5
&limit=10

What this does:

• Filters to LONG positions only
• Only positions from last 24 hours
• Shows 6-hour money flow changes
• Sorts by biggest money inflows
• Requires at least 5 positions (quality filter)
• Returns top 10 results

2. Swing Trading Setup

Goal: Identify medium-term conviction plays with stable positioning

?include_hold_times=true
&min_hold_time=168
&position_type=LONG
&include_volatility=true
&sort_by=volatility
&sort_order=asc
&min_positions=8
&limit=15

What this does:

• Enables hold time calculations
• Filters to positions held ≥1 week (168 hours)
• LONG positions only
• Shows volatility metrics
• Sorts by lowest volatility (most stable)
• Quality filter: 8+ positions
• Top 15 stable, long-term LONGS

3. Whale Watching

Goal: Track large capital deployments and whale behavior

?position_size_bucket=whale
&include_distribution=true
&include_changes=true
&change_window=24h
&sort_by=money_flow
&sort_order=desc
&timeframe=7d
&limit=20

What this does:

• Only $1M+ positions (whales)
• Shows position size distribution breakdown
• Tracks 24-hour changes
• Sorts by biggest daily money flows
• Positions from last week
• Top 20 whale plays

4. Contrarian Strategy

Goal: Find strong SHORT positions against the crowd

?position_type=SHORT
&min_positions=10
&include_confidence=true
&signal_strength=strong
&sort_by=percentage
&sort_order=desc
&include_changes=true
&change_window=24h

What this does:

• SHORT positions only
• High liquidity (10+ positions)
• Adds confidence scoring
• Only strong signals (80+ confidence)
• Sorts by strongest SHORT bias
• Shows 24h position changes

5. Scalping Signals

Goal: Ultra-short-term positions with recent momentum

?timeframe=1h
&max_hold_time=6
&include_changes=true
&change_window=1h
&sort_by=position_change
&sort_order=desc
&position_type=LONG
&include_hold_times=true
&limit=5

What this does:

• Only positions from last hour
• Maximum 6-hour hold time (fresh entries)
• Hourly change tracking
• Sorts by fastest position growth
• LONG bias only
• Top 5 momentum plays

6. Risk-Managed Entries

Goal: High-confidence, low-volatility LONG setups

?position_type=LONG
&include_confidence=true
&signal_strength=strong
&include_volatility=true
&sort_by=volatility
&sort_order=asc
&min_positions=10
&include_distribution=true
&limit=10

What this does:

• LONG positions only
• Adds confidence metrics
• Only strong signals (80+ confidence)
• Shows volatility data
• Sorts by most stable (lowest volatility)
• High liquidity (10+ positions)
• Shows whale vs retail distribution
• Top 10 low-risk LONG setups

Performance Optimization

Fast Queries (< 2 seconds)

Optimized for speed:

?limit=10
&sort_by=default
&min_positions=5
&position_type=LONG

Why it's fast:

• Small result set (limit=10)
• No hold time calculations
• No V2 enhancements
• Simple sorting

Slower Queries (10-20 seconds)

Rich data, slower response:

?include_hold_times=true
&include_changes=true
&include_distribution=true
&include_confidence=true
&include_volatility=true
&sort_by=median_hold_time
&limit=50

Why it's slower:

• Hold time calculations (~12-20s)
• Multiple V2 enhancements
• Large result set
• Complex sorting

Balanced Approach

Good data with reasonable speed (~3-5s):

?position_type=LONG
&include_changes=true
&change_window=24h
&include_confidence=true
&sort_by=money_flow
&min_positions=5
&limit=15

Performance tips:

• Use include_hold_times=false (default)
• Keep limit under 20
• Enable only needed V2 features
• Use refresh=false (default) for caching

Advanced Combinations

Multi-Factor Quality Filtering

Find only the highest-quality signals:

?position_type=LONG
&min_positions=15
&signal_strength=strong
&include_confidence=true
&position_size_bucket=large
&include_volatility=true
&sort_by=volatility
&sort_order=asc
&limit=5

Quality factors:

• High liquidity (15+ positions)
• Strong confidence (80+)
• Large positions ($100K-$1M)
• Low volatility (stable)

Momentum + Conviction

Positions with both momentum AND conviction:

?include_hold_times=true
&min_hold_time=72
&include_changes=true
&change_window=24h
&sort_by=money_flow
&sort_order=desc
&position_type=LONG
&min_positions=8
&include_confidence=true

What this finds:

• Held ≥3 days (conviction)
• With 24h money inflows (momentum)
• Sorted by biggest flows
• High confidence
• Good liquidity

Whale vs Retail Divergence

Compare whale and retail positioning:

Query 1 - Whales:

?position_size_bucket=whale
&position_type=LONG
&sort_by=positions
&include_distribution=true

Query 2 - Retail:

?position_size_bucket=small
&position_type=SHORT
&sort_by=positions
&include_distribution=true

Analysis:

• If whales are LONG and retail is SHORT = bullish divergence
• If both aligned = no edge
• Distribution shows concentration

Time-Based Position Analysis

Track position evolution over different timeframes:

Ultra-recent (1h):

?timeframe=1h&include_changes=true&change_window=1h&sort_by=position_change

Intraday (6h):

?timeframe=6h&include_changes=true&change_window=6h&sort_by=money_flow

Daily (24h):

?timeframe=24h&include_changes=true&change_window=24h&sort_by=percentage

Compare results to see:

• Momentum building (increasing across timeframes)
• Momentum fading (decreasing across timeframes)
• Fresh reversals (opposite directions)

Best Practices

1. Start Simple, Add Complexity

Step 1 - Basic query:

?position_type=LONG&limit=10

Step 2 - Add quality filter:

?position_type=LONG&min_positions=5&limit=10

Step 3 - Add sorting:

?position_type=LONG&min_positions=5&sort_by=percentage&sort_order=desc&limit=10

Step 4 - Add enhancements:

?position_type=LONG&min_positions=5&sort_by=percentage&sort_order=desc&include_confidence=true&limit=10

2. Use Appropriate Limits

• Watchlist/alerts: limit=5-10 (fast, focused)
• Analysis/research: limit=20-30 (comprehensive)
• Data export: limit=50-100 (complete, paginated)

3. Match Parameters to Strategy

4. Understand Parameter Dependencies

Required dependencies:

• sort_by=money_flow requires include_changes=true
• sort_by=position_change requires include_changes=true
• sort_by=volatility requires include_volatility=true
• sort_by=hold_time requires include_hold_times=true
• signal_strength requires include_confidence=true
• min_hold_time/max_hold_time require include_hold_times=true

5. Optimize for Performance

Fast combinations:

Basic filters + simple sorting + no enhancements
Example: position_type + min_positions + sort_by=default

Balanced combinations:

Basic filters + one enhancement + moderate limit
Example: position_type + include_changes + limit=15

Comprehensive (slower):

All filters + all enhancements + hold times
Example: All include_* parameters + hold time filters

6. Cache Strategically

• Development/testing: refresh=true (fresh data)
• Production/dashboards: refresh=false (default, use cache)
• Critical trades: refresh=true (latest data)
• Background updates: refresh=false (reduce load)

Real-World Examples

Example 1: Morning Market Scan

Goal: Check overnight smart money moves

?timeframe=24h
&include_changes=true
&change_window=24h
&sort_by=money_flow
&sort_order=desc
&limit=20
&min_positions=5

Example 2: Whale Alert System

Goal: Monitor large position changes in real-time

?position_size_bucket=whale
&timeframe=1h
&include_changes=true
&change_window=1h
&sort_by=position_change
&sort_order=desc
&refresh=true
&limit=10

Example 3: Contrarian Reversal Finder

Goal: Find potential reversals (strong positions against trend)

?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

Note:

• signal_strength requires include_confidence=true
• sort_by=position_change requires include_changes=true

Example 4: Conviction Trade Scanner

Goal: Long-term, high-conviction positions

?include_hold_times=true
&min_hold_time=336
&include_volatility=true
&sort_by=volatility
&sort_order=asc
&include_confidence=true
&signal_strength=strong
&position_size_bucket=large
&limit=10

Quick Reference: Parameter Categories

Filtering Parameters

• position_type - LONG/SHORT/NEUTRAL
• min_positions - Quality filter
• timeframe - Time window
• min_hold_time - Conviction filter
• max_hold_time - Freshness filter
• min_position_value - Size threshold
• position_size_bucket - whale/large/medium/small
• signal_strength - strong/moderate/weak

Sorting Parameters

• sort_by - Field to sort
• sort_order - asc/desc

Pagination Parameters

• limit - Results per page
• offset - Skip results

Enhancement Parameters

• include_hold_times - Hold time metrics
• include_changes - Position deltas
• include_distribution - Size breakdown
• include_confidence - Confidence scores
• include_volatility - Volatility metrics

Special Parameters

• pinned - Pin specific tokens
• refresh - Bypass cache
• change_window - Change timeframe (1h/6h/24h)

Support

For questions or feature requests:

• Email: support@0xathena.ai
• Documentation: https://docs.0xathena.ai

Links: Website · GitHub · Support

Last Updated: October 6, 2025