Use Case

Whale positioning as a bot input

The Smart Money API tracks large-wallet positioning and folds the consensus into whale_score, a sub-score inside every confirmation. Rather than scraping wallets yourself, call /v1/confirm and read whale_score plus the "Whales: ..." reason as decision support in your bot.

Who this is for

Developers building crypto bots who want whale-consensus context without running their own on-chain and exchange tracking pipeline. The whale_score sub-score summarises which way tracked large wallets are leaning for a symbol and direction. Smart Money API is decision support — it does not place orders for you; your bot stays in control of execution.

Prerequisites

  • Python 3.9+ with pip install requests.
  • Your own strategy that proposes a candidate direction (long or short).
  • A Smart Money API key (free tier covers BTC).

Get your API key

Every request authenticates with the X-API-Key header. To get a key:

  1. 1Create a free account, then open your dashboard.
  2. 2Copy the API key shown under API Access. The free tier covers BTC at 20 requests/day — enough to test this guide end to end.
  3. 3Need more symbols or higher limits? Compare tiers on the pricing page.

Keep the key secret — store it in an environment variable, never commit it to source control.

Get free API key

Setup

  1. 1Install the library: pip install requests.
  2. 2Export your key: export SMA_API_KEY="sm_your_key_here".
  3. 3When your strategy proposes a direction, call /v1/confirm and read whale_score — the whale-consensus sub-score — alongside the "Whales: ..." entry in reasons.
  4. 4Use a strong, aligned whale_score with a CONFIRM action as supporting input; size by size_mult and apply your own risk rules.

Working example

This script calls GET /v1/confirm?symbol=BTC&direction=long and inspects the whale sub-score and the whale reason to use whale positioning as a bot input.

whale_input.py
import os
import requests

API_KEY = os.environ["SMA_API_KEY"]            # never hard-code
SMA_BASE = "https://api.smartmoneyapi.com"

def confirm(symbol: str, direction: str) -> dict:
    """Ask Smart Money API for market-context confirmation."""
    r = requests.get(
        f"{SMA_BASE}/v1/confirm",
        params={"symbol": symbol, "direction": direction, "source": "whale-bot"},
        headers={"X-API-Key": API_KEY},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

# Your strategy proposes a candidate direction
sig = confirm("BTC", "long")

# whale_score summarises tracked large-wallet positioning (0-1)
whale = sig["whale_score"]
whale_reason = next((r for r in sig["reasons"] if r.startswith("Whales")), None)
print("action", sig["action"], "whale_score", whale)
print("  ", whale_reason)                      # e.g. "Whales: 67% long consensus"

# Use whale positioning as decision support
if sig["action"] == "CONFIRM" and whale >= 0.6:
    qty = 0.01 * sig["size_mult"]              # scale by suggested multiplier
    print(f"Whales lean with the move -> would place long {qty} BTC")
elif sig["action"] == "REDUCE":
    print("Whale consensus is mixed -> trade smaller or wait")
else:  # SKIP or weak whale_score
    print("Whale positioning does not back this trade -> stand aside")

Expected response

A successful call to /v1/confirm returns JSON like this:

200 OK · application/json
{
  "ts": 1710940821,
  "symbol": "BTC",
  "direction": "long",
  "composite": 0.74,
  "confidence": "HIGH",
  "action": "CONFIRM",
  "size_mult": 1.5,
  "deriv_score": 0.81,
  "onchain_score": 0.68,
  "whale_score": 0.73,
  "reasons": [
    "Funding rate positive across all venues",
    "LSR favors longs: 1.42",
    "Whales: 67% long consensus",
    "MVRV above 1.0 — on-chain bullish"
  ]
}

whale_score is the whale-consensus sub-score built from tracked large-wallet positioning, composite ranges from -1.0 (strong contra) to +1.0 (strong confirm), confidence is HIGH or MEDIUM, and size_mult is a 0.0–1.5 suggested size multiplier. See the full field reference in the API docs.

How to act on the response

CONFIRM

Whale consensus leans with your direction. Proceed with your own entry and risk rules, optionally scaling size by size_mult.

REDUCE

Signals are mixed. Consider a smaller position, tighter stops, or waiting for a cleaner setup.

SKIP

Whale positioning does not support this trade. Stand aside and re-check on the next candidate.

Ready to build?

Grab a free key and make your first confirmation call in under a minute.

Get free API key Read the docs View pricing

Not financial advice. Crypto trading involves risk.