Coinversaa + Freqtrade: Smart Money Signals

A reference implementation showing how to use the Coinversaa API as a signal source in Freqtrade strategies.

Coinversaa indexes Hyperliquid clearinghouse data in real time — 710K+ wallets classified into behavioral cohorts, 1.8B+ trades with full lifecycle tracking. This example pulls those signals into a Freqtrade strategy so your bot can see what the smartest traders are doing before making a decision.

This is a reference implementation. The strategy logic is intentionally simple to demonstrate API integration. You should modify the entry/exit logic, thresholds, and risk management for your own use case.

Setup

1. Get a Coinversaa API key

1. Go to coinversaa.ai/developers
2. Sign in and create a free API key (3 keys, 100 requests/min, no credit card)
3. Copy your key — you'll need it in step 3

2. Test the API client (optional)

cd coinversaa-freqtrade-example
python -m venv .venv
source .venv/bin/activate
pip install requests python-dotenv
cp .env.example .env
# Edit .env and paste your API key
python test_client.py

This calls each endpoint once and confirms your key works.

3. Install the strategy

Copy both files into your Freqtrade user_data/strategies directory:

cp coinversaa_client.py /path/to/freqtrade/user_data/strategies/
cp coinversaa_smart_money_strategy.py /path/to/freqtrade/user_data/strategies/

Install the requests dependency (usually already included with Freqtrade):

pip install requests

4. Configure your API key

Either set it as an environment variable:

export COINVERSAA_API_KEY=your-api-key-here

Or add it to your Freqtrade config file (config.json):

{
    "strategy": "CoinversaaSmartMoneyStrategy",
    "strategy_params": {
        "coinversaa_api_key": "your-api-key-here"
    }
}

The strategy checks strategy_params first, then falls back to the COINVERSAA_API_KEY env var.

5. Run

freqtrade trade --strategy CoinversaaSmartMoneyStrategy --config config.json

Or dry-run first:

freqtrade trade --strategy CoinversaaSmartMoneyStrategy --config config.json --dry-run

Signals explained

Smart Money Bias (get_smart_money_bias)

Returns the long/short positioning of each trader cohort for a given coin. Coinversaa classifies 710K+ wallets into PnL tiers based on realized trading performance:

Tier	Description
money_printer	Top performers — consistently profitable
smart_money	Strong positive PnL
grinder	Modest positive returns
humble_earner	Small but positive PnL
exit_liquidity	Slightly negative — often the other side of smart money trades
semi_rekt	Significant losses
full_rekt	Large drawdowns
giga_rekt	Catastrophic losses

Each tier returns a netBias score from -1 (fully short) to +1 (fully long) and a biasLabel ("long", "short", or "neutral"). The strategy uses the money_printer and smart_money tiers as the primary signal.

Whale Positions (get_whale_positions)

Returns current open positions held by whale-tier traders (by account size). Each position includes the coin, side, entry price, notional value, leverage, unrealized PnL, and the trader's cohort classification.

The strategy monitors whale short exposure on a given coin — if large traders are building short positions, it avoids opening new longs.

Liquidation Clusters (get_liquidation_clusters)

Returns a price-bucketed heatmap showing where liquidation levels are concentrated. Each bucket includes the count and notional value of long and short positions at risk.

The strategy uses this in a custom stoploss: if there's a large cluster of long liquidations just below the current price, it tightens the stop to avoid getting caught in a liquidation cascade.

Cohort Summary (get_cohort_summary)

Aggregate statistics for all cohorts — wallet count, total PnL, average win rate, volume. Useful for understanding the overall market participant landscape. Not used in the example strategy but available in the client.

Files

File	Description
coinversaa_client.py	Standalone API client — drop into any Python project
coinversaa_smart_money_strategy.py	Freqtrade strategy using the client
test_client.py	Quick script to verify your API key and endpoints
.env.example	Template for your API key

Backtesting

This strategy uses live API signals (current cohort bias, current whale positions). These signals don't exist for historical candles, so freqtrade backtesting will run with empty/neutral signals — entries won't fire.

How to forward-test instead:

freqtrade trade --strategy CoinversaaSmartMoneyStrategy --config config.json --dry-run

Dry-run mode uses live data with paper trades. This is the recommended way to evaluate the strategy before going live.

For historical analysis, the Coinversaa API provides:

• get_cohort_history(tier_type, tier, days) — daily cohort performance up to 365 days back
• Long/short ratio history (/live/long-short/history?coin=BTC&hours=168)
• Trader trade history by date range (/pulse/trader/:address/trades-in-range)

You could build a historical signal dataset from these endpoints and load it as a custom data feed in Freqtrade using DataProvider. This is outside the scope of this reference implementation.

Adapting for your strategy

Some ideas for extending this:

• Combine with technical indicators — use smart money bias as confirmation for your existing TA signals
• Filter pairs — only trade coins where money_printer cohort has strong conviction (high absolute netBias)
• Track whale position changes — compare whale exposure across candles to detect accumulation or distribution
• Cohort divergence — enter when money_printer and giga_rekt tiers disagree (smart money vs. retail)
• Liquidation magnet — trade toward large liquidation clusters (price tends to gravitate toward liquidity)

API rate limits

Free tier: 100 requests/min across 3 API keys. The strategy caches signals for 60 seconds by default (CACHE_TTL_SECONDS), which keeps you well within limits even with multiple pairs.

Links

• Coinversaa API — get your API key
• Coinversaa MCP Server — use with Claude, Cursor, or any MCP client
• Freqtrade docs — strategy development guide