Cookbook

API Cookbook

Practical, copy-paste recipes for the most common ways to wire the Smart Money trade-confirmation API into a bot. Every recipe calls GET /v1/confirm and acts on action, confidence, and size_multiplier. Send your key in the X-API-Key header — see the full docs.

Need a key first? Sign up free, copy it from your dashboard, and replace sm_your_key below.

Recipe 1

Confirm before entry (Python)

The canonical loop. Before your strategy opens a position, ask the API whether market structure agrees. Only enter when action == "CONFIRM".

Python

import requests

API_KEY = "sm_your_key"
BASE = "https://api.smartmoneyapi.com/v1"

def confirm(symbol, direction):
    r = requests.get(
        f"{BASE}/confirm",
        params={"symbol": symbol, "direction": direction},
        headers={"X-API-Key": API_KEY},
        timeout=5,
    )
    r.raise_for_status()
    return r.json()

sig = confirm("BTC", "long")
if sig["action"] == "CONFIRM":
    place_order("BTC", "long")   # your execution
else:
    print("skip:", sig["reasons"])

Response
{
  "symbol": "BTC",
  "direction": "long",
  "action": "CONFIRM",
  "confidence": "HIGH",
  "composite": 0.74,
  "size_mult": 1.5,
  "reasons": ["Funding positive across venues", "Whales 67% long"]
}

Recipe 2

Gate a Freqtrade signal

Override confirm_trade_entry so Freqtrade only takes entries the API confirms. Fail open on API errors so a timeout never blocks all trading.

Python — Freqtrade

import requests
from freqtrade.strategy import IStrategy

class SmartMoneyStrategy(IStrategy):
    SM_KEY = "sm_your_key"
    SM_BASE = "https://api.smartmoneyapi.com/v1"

    def confirm_trade_entry(self, pair, order_type, amount, rate,
                            time_in_force, current_time, entry_tag, **kwargs):
        symbol = pair.split("/")[0]
        if symbol not in ("BTC", "ETH", "SOL"):
            return True
        try:
            r = requests.get(
                f"{self.SM_BASE}/confirm",
                params={"symbol": symbol, "direction": "long"},
                headers={"X-API-Key": self.SM_KEY},
                timeout=3,
            ).json()
            return r.get("action") == "CONFIRM"
        except Exception:
            return True   # fail open on API error

Recipe 3

Size by size_multiplier

Let conviction set position size. Multiply your base size by size_mult (0.0–1.5) so HIGH-confidence trades get more capital and weak ones get less.

Python

BASE_SIZE_USD = 1000

sig = confirm("ETH", "long")
mult = sig.get("size_mult", 0.0)
size = BASE_SIZE_USD * mult

if size > 0:
    place_order("ETH", "long", size_usd=size)
    print(f"entered ${size:.0f} (mult {mult})")

A size_mult of 0.0 means do not enter — same outcome as a SKIP. Treat anything below your own floor as a skip.

Recipe 4

Skip on SKIP / reduce on REDUCE

Handle all three actions explicitly. CONFIRM enters full size, REDUCE enters at the (smaller) multiplier, SKIP stands aside.

Python

sig = confirm(symbol, direction)
action = sig["action"]

if action == "CONFIRM":
    place_order(symbol, direction, BASE_SIZE_USD * sig["size_mult"])
elif action == "REDUCE":
    # structure is mixed — enter smaller, tighten stop
    place_order(symbol, direction, BASE_SIZE_USD * sig["size_mult"])
else:  # SKIP
    log(f"skip {symbol} {direction}: {sig['reasons']}")

Recipe 5

Handle 402 / 429

A 402 means the symbol or endpoint needs a higher plan; a 429 means you hit a rate limit. Treat 429/5xx as transient (back off), 402/401/403 as terminal (fix plan or key).

Python

import time, requests

def confirm_safe(symbol, direction, retries=3):
    for attempt in range(retries):
        r = requests.get(
            f"{BASE}/confirm",
            params={"symbol": symbol, "direction": direction},
            headers={"X-API-Key": API_KEY}, timeout=5,
        )
        if r.status_code == 200:
            return r.json()
        if r.status_code in (401, 402, 403):
            raise RuntimeError(r.json())   # terminal: fix key/plan
        if r.status_code == 429:
            reset = int(r.headers.get("X-RateLimit-Reset", 2))
            time.sleep(min(reset, 2 ** attempt))
            continue
        time.sleep(2 ** attempt)        # 5xx / transient
    return None

Recipe 6

Use with a coding agent

Hand Claude Code, Codex, or Cursor the machine-readable references and let it wire the integration. Point it at /llms.txt for the overview and the OpenAPI spec for exact shapes.

Prompt

# Paste into Claude Code / Cursor / Codex
Read https://smartmoneyapi.com/llms.txt and the OpenAPI spec at
github.com/tashiardit/smartmoneyapi-docs, then add a pre-trade
check to my bot: call GET /v1/confirm with my X-API-Key, and skip
any entry unless action == "CONFIRM". Scale size by size_multiplier.

Resources: /llms.txt · OpenAPI spec · Python client.

Ready to gate your first trade?

Grab a free key and read the full endpoint reference.

Get a free API key Full docs

Decision support, not execution advice. Not financial advice. Cryptocurrency trading involves substantial risk of loss.