Use Case

A liquidation-risk filter for crowded trades

Crowded, over-extended positioning is exactly the setup that gets liquidated in a squeeze. That crowding shows up in the derivatives and whale sub-scores the Smart Money API already computes. Call /v1/confirm and treat a REDUCE or SKIP action — or a negative composite — as a liquidation-risk filter that keeps you out of crowded trades.

Who this is for

Developers running leveraged crypto bots who want an independent check against piling into an already-crowded trade. When funding is stretched, the long/short ratio is lopsided, and whale consensus leans the same way the crowd does, the composite weakens or turns negative for that 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. 3Before entering, call /v1/confirm for your candidate direction and read the action and composite.
  4. 4Treat REDUCE, SKIP, or a negative composite as elevated liquidation risk and skip or shrink the trade.

Working example

This script calls GET /v1/confirm?symbol=BTC&direction=long and uses the action and composite as a liquidation-risk filter before sizing a leveraged entry.

liquidation_filter.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": "liq-filter"},
        headers={"X-API-Key": API_KEY},
        timeout=10,
    )
    r.raise_for_status()
    return r.json()

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

action = sig["action"]
composite = sig["composite"]                   # -1.0 contra .. +1.0 confirm
print("action", action, "composite", composite, "deriv", sig["deriv_score"])

# Use the response as a liquidation-risk filter
if action in ("REDUCE", "SKIP") or composite < 0:
    print("Crowded / contra positioning -> elevated liquidation risk, stand aside")
else:  # CONFIRM with a positive composite
    qty = 0.01 * sig["size_mult"]              # scale by suggested multiplier
    print(f"Positioning is not crowded against you -> would place long {qty} BTC")

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"
  ]
}

composite ranges from -1.0 (strong contra) to +1.0 (strong confirm), action is CONFIRM, REDUCE or SKIP, and a low deriv_score together with a contra composite is the crowding signal you filter on. See the full field reference in the API docs.

How to act on the response

CONFIRM

Positioning is not crowded against you. Proceed with your own entry and risk rules, optionally scaling size by size_mult.

REDUCE

Positioning is getting crowded. Consider a smaller position, tighter stops, or waiting for a cleaner setup.

SKIP

Crowding and contra positioning flag elevated liquidation risk. 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.