API Documentation — Smart Money API

Authentication

All requests require an API key passed as the X-API-Key HTTP header.

HTTP Header
X-API-Key: sm_your_api_key_here

Your API key is available from the dashboard after signing up. Keep your key secret — do not expose it in client-side code or public repositories.

Google Sign-In (Firebase Auth)

Users can authenticate using their Google account via Firebase Authentication. After a successful Google sign-in on the client, exchange the Firebase ID token for a linked API session. The system automatically syncs your Google identity with the API key system.

Available to: Free Trader Pro

POST /auth/google

Request Body

Field	Type	Description
id_tokenrequired	string	Firebase ID token obtained after Google sign-in on the client

Example Response

JSON

{
  "api_key": "sm_your_linked_key",
  "uid": "firebase_uid_abc123",
  "email": "user@example.com",
  "plan": "trader",
  "synced": true
}

User profile data — email, plan, usage history, preferences — is stored in Firestore and linked to your Google account. A full data export or account deletion can be requested at any time via the dashboard Privacy Settings.

Rate Limits

Plan	Calls/Day	Burst Limit	Data Delay
Free	10	2/min	60 seconds
Trader	200	20/min	Real-time
Pro	2,000	100/min	Real-time

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Base URL

https://api.smartmoneyapi.com/v1

All endpoints below are relative to this base URL. All responses are JSON with Content-Type: application/json.

Endpoints

GET /confirm

The core endpoint. Returns a composite confidence score and action recommendation for a given trade direction. Call this before entering any position.

Parameters

Parameter	Type	Description
symbolrequired	string	Asset symbol. One of: `BTC`, `ETH`, `SOL` (Trader+)
directionrequired	string	Trade direction: `long` or `short`
sourceoptional	string	Label for your signal source (logged for analytics). Max 32 chars.

Example Request

cURL

curl -H "X-API-Key: sm_your_key" \
  "https://api.smartmoneyapi.com/v1/confirm?symbol=BTC&direction=long"

Example Response

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

Response Fields

Field	Type	Description
ts	integer	Unix timestamp of the calculation
symbol	string	Asset symbol (BTC/ETH/SOL)
direction	string	Requested direction (long/short)
composite	float	Composite score from -1.0 (extreme contra) to +1.0 (strong confirm)
confidence	string	`HIGH` / `MEDIUM` / `LOW` / `VETO`
action	string	Recommended action: CONFIRM / REDUCE / SKIP / VETO
size_mult	float	Suggested position size multiplier (0.0 – 1.5)
deriv_score	float	Derivatives sub-score (-1 to 1)
onchain_score	float	On-chain sub-score (-1 to 1)
whale_score	float	Whale consensus sub-score (-1 to 1)
reasons	array	Human-readable explanation strings for the score

GET /snapshot

Returns a full market snapshot including all sub-scores, raw metrics, and indicator values for a given symbol. Useful for dashboards and logging.

Requires: Trader Pro

GET /onchain

Returns raw on-chain metrics: MVRV, SOPR, exchange net flow, realized cap ratio, and cycle position classification.

Requires: Trader Pro

GET /whales

Returns whale wallet consensus data: long/short split, total notional exposure, top 10 positions (Pro only), and wallet count.

Requires: Trader Pro

GET /signals

Returns a stream of the most recent HIGH/VETO signals across all monitored assets. Useful for opportunity scanning.

Requires: Pro

GET /export

Download historical signal data as CSV for backtesting. Parameters: symbol, from (unix ts), to (unix ts).

Requires: Pro

GET /health

System health check. Returns data freshness for each source and overall API status. No authentication required.

JSON Response
{
  "status": "ok",
  "uptime_s": 1209600,
  "sources": {
    "bybit": { "lag_s": 42, "ok": true },
    "binance": { "lag_s": 38, "ok": true },
    "hyperliquid": { "lag_s": 61, "ok": true },
    "onchain": { "lag_s": 290, "ok": true }
  }
}

GET /usage

Returns your current API usage statistics: calls today, monthly totals, quota limits, and reset times.

GET /webhooks

Manage webhook delivery endpoints. Register a URL to receive real-time push notifications when a HIGH or VETO signal fires across your monitored assets.

Requires: Trader Pro

Intelligence

GET /analysis

Requires: Pro

Returns AI-powered market regime classification with signal conflict detection. Analyzes cross-signal agreement, identifies divergences between derivatives, on-chain, and whale data, and produces a natural-language summary with forward-looking risk factors and a time-horizoned recommendation.

Parameters

Parameter	Type	Description
symbolrequired	string	Asset symbol: `BTC`, `ETH`, or `SOL`

Example Response

JSON

{
  "ts": 1710940821,
  "symbol": "BTC",
  "regime": "late_cycle_divergence",
  "regime_label": "Late Cycle — Signal Divergence",
  "summary": "BTC is in a late bull cycle phase with on-chain strength conflicting with derivatives overextension. Whales are reducing exposure while retail LSR climbs.",
  "signal_conflicts": [
    "Whale score bearish while onchain score bullish",
    "Funding rate at 3-month high — potential squeeze risk"
  ],
  "risk_factors": ["Elevated funding", "OI divergence", "Whale reduction"],
  "recommendation": "Reduce long exposure, tighten stops. Avoid new longs above current price.",
  "time_horizon": "4h–12h"
}

Pro plan required. This endpoint consumes 3 API calls per request due to AI processing overhead.

GET /liquidations

Requires: Trader Pro

Returns estimated liquidation levels across exchanges and cascade risk assessment. Identifies clustered stop-hunt zones where forced liquidations are likely to accelerate a price move in either direction.

Parameters

Parameter	Type	Description
symbolrequired	string	Asset symbol: `BTC`, `ETH`, or `SOL`

Example Response

JSON

{
  "symbol": "BTC",
  "cascade_risk": "HIGH",
  "nearest_long_liq_pct": -3.2,
  "nearest_short_liq_pct": 4.1,
  "long_levels": [
    { "price": 93100, "size_usd": 48200000, "avg_leverage": 12, "distance_pct": -3.2 },
    { "price": 89500, "size_usd": 91000000, "avg_leverage": 20, "distance_pct": -6.9 }
  ],
  "short_levels": [
    { "price": 100400, "size_usd": 33500000, "avg_leverage": 10, "distance_pct": 4.1 }
  ]
}

Trader plan: Returns cascade_risk and nearest distance percentages only. Pro plan: Full detailed levels with size and average leverage breakdown.

GET /smart-stop

Requires: Trader Pro

Calculates intelligent stop-loss levels based on the current liquidation heatmap, volatility bands, and market structure. Returns tiered stop recommendations and take-profit suggestions calibrated to your entry price and risk tolerance.

Parameters

Parameter	Type	Description
symbolrequired	string	Asset symbol: `BTC`, `ETH`, or `SOL`
directionrequired	string	Position direction: `long` or `short`
entry_priceoptional	float	Your entry price. Defaults to current market price if omitted.
risk_pctoptional	float	Maximum acceptable risk as % of account. Default: `2.0`

Example Response

JSON

{
  "symbol": "BTC",
  "direction": "long",
  "entry_price": 96420,
  "stops": {
    "tight": { "price": 95100, "note": "Below 1h structure. Best for scalps." },
    "recommended": { "price": 93800, "note": "Below major liq cluster at $94K. Standard swing stop." },
    "wide": { "price": 91200, "note": "Below 4h demand zone. Position trade stop." }
  },
  "avoid_zones": [
    { "low": 94200, "high": 94800, "reason": "Dense liquidation cluster — high slippage risk" }
  ],
  "take_profit_suggestions": [
    { "tp1": 98500, "tp2": 101000, "tp3": 104200 }
  ]
}

Trader plan: Returns the recommended stop only. Pro plan: All three stop tiers, avoid_zones, and full take-profit suggestions.

GET /funding-arb

Requires: Trader Pro

Identifies cross-exchange funding rate arbitrage opportunities in real time. Returns ranked opportunities with estimated annualized yield, optimal exchange pair, and the required hedge action to capture the spread.

Parameters

Parameter	Type	Description
min_spreadoptional	float	Minimum funding rate spread to include (as decimal). Default: `0.01`
symboloptional	string	Filter to a specific asset. Omit to scan all supported assets.

Example Response

JSON

{
  "ts": 1710940821,
  "opportunities": [
    {
      "symbol": "BTC",
      "spread": 0.032,
      "apr": 84.2,
      "long_exchange": "hyperliquid",
      "short_exchange": "bybit",
      "action": "Long HYPE / Short BYBIT",
      "estimated_profit_8h_usd": 26.4
    }
  ]
}

Trader plan: Top 1 opportunity only, no historical spread data. Pro plan: All current opportunities with 24h spread history per exchange pair.

GET /flows

Requires: Pro

Returns cross-asset capital flow data showing rotation patterns between BTC, ETH, and SOL across multiple time windows. Useful for identifying which asset is accumulating capital and which is being distributed at any given moment.

Example Response

JSON

{
  "ts": 1710940821,
  "flows": {
    "BTC": { "1h": 142000000, "4h": 380000000, "12h": -90000000, "24h": 220000000 },
    "ETH": { "1h": -38000000, "4h": -110000000, "12h": 55000000, "24h": -80000000 },
    "SOL": { "1h": 12000000, "4h": 29000000, "12h": 18000000, "24h": 44000000 }
  },
  "rotations_detected": [
    "Capital rotating from ETH to BTC over 4h window",
    "SOL accumulation consistent across all windows"
  ]
}

Pro plan required. Flow values are USD net inflow (positive) or outflow (negative) per time window.

GET /whale-events

Requires: Trader Pro

Returns significant whale position changes — opens, closes, and direction flips — detected across tracked wallets and on-chain addresses within the specified look-back window.

Parameters

Parameter	Type	Description
symboloptional	string	Filter by asset. Omit for all monitored assets.
significanceoptional	string	Filter by event significance: `high`, `medium`, or `all`. Default: `all`
hoursoptional	integer	Look-back window in hours. Default: `24`

Example Response

JSON

{
  "symbol": "BTC",
  "summary": {
    "flips_to_long": 3,
    "flips_to_short": 1,
    "new_opens": 7,
    "closes": 2
  },
  "events": [
    {
      "type": "flip_long",
      "wallet": "0xWhale...a4f2",
      "direction": "long",
      "size_usd": 4200000,
      "ts": 1710938400
    }
  ]
}

Trader plan: Returns the summary object only. Pro plan: Full events feed with wallet identifiers, sizes, and timestamps.

GET /regimes/history

Requires: Pro

Returns historical regime classification data for a given asset. Use this to backtest how specific regime types have performed historically, how long each regime type typically lasts, and how regime transitions unfold over time.

Parameters

Parameter	Type	Description
symboloptional	string	Asset symbol. Default: `BTC`
regimeoptional	string	Filter to a specific regime type, e.g. `late_cycle_divergence`. Omit for all regimes.
daysoptional	integer	Look-back window in days. Default: `30`. Maximum: `365`

Example Response

JSON

{
  "symbol": "BTC",
  "current_regime": "late_cycle_divergence",
  "regime_summary": {
    "late_cycle_divergence": { "occurrences": 4, "avg_duration_h": 38, "avg_return_pct": -2.1 },
    "accumulation": { "occurrences": 6, "avg_duration_h": 72, "avg_return_pct": 5.4 },
    "breakout": { "occurrences": 3, "avg_duration_h": 18, "avg_return_pct": 9.2 }
  },
  "transitions": [
    { "from": "accumulation", "to": "breakout", "ts": 1710850000 },
    { "from": "breakout", "to": "late_cycle_divergence", "ts": 1710915000 }
  ]
}

Pro plan required. Combine with /analysis to validate strategy assumptions against historical regime performance data.

GET /exchange-health

Available to: Free Trader Pro

Returns real-time health status for all monitored exchanges including per-exchange latency, error rates, and data staleness indicators. No authentication required — publicly accessible endpoint.

Example Response

JSON

{
  "overall_status": "ok",
  "ts": 1710940821,
  "exchanges": {
    "bybit": { "status": "ok", "latency_ms": 42, "error_rate_1h": 0.0, "last_data_age_s": 18 },
    "binance": { "status": "ok", "latency_ms": 38, "error_rate_1h": 0.0, "last_data_age_s": 22 },
    "hyperliquid": { "status": "degraded", "latency_ms": 310, "error_rate_1h": 0.04, "last_data_age_s": 95 },
    "okx": { "status": "ok", "latency_ms": 55, "error_rate_1h": 0.0, "last_data_age_s": 30 }
  }
}

Personalization

GET /preferences

Requires: Trader Pro

Returns your current personalization settings including default trade parameters, risk profile, watchlist, and notification preferences.

PUT /v1/preferences

Update preferences by sending a JSON body with any subset of the fields below. Omitted fields retain their current values.

Preference Fields

Field	Type	Description
default_trade_size_usd	float	Default position size in USD for Kelly and smart-stop calculations
risk_tolerance	string	`conservative`, `moderate`, or `aggressive`
default_risk_pct	float	Default risk per trade as % of account. Used by `/smart-stop` when `risk_pct` is omitted
watchlist	array	Ordered list of asset symbols, e.g. `["BTC","ETH","SOL"]`
notification_email	string	Email address for alert delivery
timezone	string	IANA timezone string, e.g. `America/New_York`

PUT — Example Body

{
  "default_trade_size_usd": 5000,
  "risk_tolerance": "moderate",
  "default_risk_pct": 1.5,
  "watchlist": ["BTC", "ETH", "SOL"]
}

GET /watchlist

Requires: Trader Pro

Returns a confirmation status snapshot and key risk metrics for all symbols in your configured watchlist. Provides a multi-asset overview without calling /confirm separately for each symbol.

Example Response

JSON

{
  "ts": 1710940821,
  "watchlist": [
    {
      "symbol": "BTC",
      "confidence": "HIGH",
      "action": "CONFIRM",
      "regime": "accumulation",
      "cascade_risk": "LOW"
    },
    {
      "symbol": "ETH",
      "confidence": "MEDIUM",
      "action": "REDUCE",
      "regime": "late_cycle_divergence",
      "cascade_risk": "HIGH"
    },
    {
      "symbol": "SOL",
      "confidence": "HIGH",
      "action": "CONFIRM",
      "regime": "breakout",
      "cascade_risk": "MEDIUM"
    }
  ]
}

POST /alerts/conditions

Requires: Pro

Create custom alert rules that trigger when a specified metric crosses a threshold. Alerts are delivered via webhook, email, or the dashboard notification feed depending on your preferences.

GET /v1/alerts/conditions

Returns a list of all your configured alert conditions with their IDs, definitions, and current status.

DELETE /v1/alerts/conditions/{id}

Permanently removes an alert condition by its ID.

GET /v1/alerts/history

Returns recent alert trigger events with timestamps, matched conditions, and the metric value at the time of trigger.

Create Alert — Request Body

Field	Type	Description
namerequired	string	Human-readable label for this alert (max 64 chars)
metricrequired	string	The metric to monitor. See available metrics table below.
symboloptional	string	Asset context. Required for symbol-scoped metrics such as `funding_rate`.
operatorrequired	string	Comparison operator: `gt`, `lt`, `gte`, `lte`, `eq`
thresholdrequired	float	Numeric value to compare the metric against

Available Metrics

Metric	Description
funding_rate	Current 8h funding rate for symbol (as decimal)
global_lsr	Global long/short ratio for symbol
long_pct	Percentage of accounts net long for symbol
mvrv	Market Value to Realized Value ratio (BTC only)
sopr	Spent Output Profit Ratio (BTC only)
whale_long_pct	Percentage of tracked whale wallets holding long positions for symbol
composite_long	Composite score for symbol queried in long direction
composite_short	Composite score for symbol queried in short direction
cascade_risk_score	Liquidation cascade risk as numeric score (0.0 – 1.0)
open_interest_usd	Total open interest in USD for symbol

POST — Example Body

{
  "name": "BTC funding rate spike",
  "metric": "funding_rate",
  "symbol": "BTC",
  "operator": "gt",
  "threshold": 0.05
}

GET /kelly

Requires: Pro

Returns Kelly Criterion position sizing recommendations calibrated to historical signal performance for the given symbol, confidence level, and direction. Grounds position size in empirical win rates to avoid over-leveraging.

Parameters

Parameter	Type	Description
symbolrequired	string	Asset symbol: `BTC`, `ETH`, or `SOL`
confidenceoptional	string	Signal confidence level to model: `HIGH`, `MEDIUM`, or `LOW`. Default: `HIGH`
directionoptional	string	Trade direction: `long` or `short`. Default: `long`
account_sizeoptional	float	Account size in USD for computing `suggested_size_usd`. Default: `10000`

Example Response

JSON

{
  "symbol": "BTC",
  "confidence": "HIGH",
  "direction": "long",
  "win_rate": 0.68,
  "avg_reward_risk_ratio": 2.1,
  "kelly_fraction": 0.36,
  "half_kelly": 0.18,
  "suggested_size_usd": 1800,
  "samples": 142,
  "note": "Half-Kelly recommended for live trading to account for estimation error."
}

Pro plan required. Calculations are based on a rolling 90-day sample of historical signals matching the requested symbol, confidence, and direction parameters.

GET /performance

Available to: Free Trader Pro

Returns historical accuracy statistics for signals issued by the API, broken down by confidence level. Useful for understanding signal reliability before committing capital.

Parameters

Parameter	Type	Description
symboloptional	string	Filter by asset. Omit for aggregate statistics across all symbols.
daysoptional	integer	Look-back window in days. Default: `30`

Example Response

JSON

{
  "symbol": "BTC",
  "period_days": 30,
  "by_confidence": {
    "HIGH": { "win_rate": 0.71, "samples": 58, "avg_return_pct": 3.4 },
    "MEDIUM": { "win_rate": 0.54, "samples": 84, "avg_return_pct": 1.2 },
    "LOW": { "win_rate": 0.46, "samples": 31, "avg_return_pct": -0.4 },
    "VETO": { "correct_avoidance_rate": 0.78, "samples": 23 }
  }
}

Error Codes

Status	Code	Description
400	invalid_params	Missing or invalid query parameters
401	unauthorized	Missing or invalid API key
403	plan_restriction	Endpoint not available on your current plan
429	rate_limit_exceeded	Daily or burst limit reached
500	internal_error	Server error — check /health for source status
503	data_stale	Data source unavailable; returned with last known data

Code Examples

Python

import requests

r = requests.get(
  "https://api.smartmoneyapi.com/v1/confirm",
  params={"symbol": "BTC", "direction": "long"},
  headers={"X-API-Key": "sm_your_key"}
)
data = r.json()

print(data["confidence"])  # HIGH / MEDIUM / LOW / VETO
print(data["size_mult"]) # 1.5 / 1.0 / 0.5 / 0.0

Python

import requests

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

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

# In your trading loop:
signal = confirm_trade("BTC", "long")
if signal["confidence"] == "VETO":
  print("Skipping — contra-signal detected")
else:
  size = base_size * signal["size_mult"]
  place_order(symbol, direction, size)

JavaScript / Node.js

JavaScript

const API_KEY = 'sm_your_key';

async function confirmTrade(symbol, direction) {
  const params = new URLSearchParams({ symbol, direction });
  const res = await fetch(
    `https://api.smartmoneyapi.com/v1/confirm?${params}`,
    { headers: { 'X-API-Key': API_KEY } }
  );
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
}

// Usage
confirmTrade('BTC', 'long').then(data => {
  console.log(data.confidence, data.size_mult);
});

cURL

Shell

# Confirm a long trade
curl -X GET \
  -H "X-API-Key: sm_your_key" \
  "https://api.smartmoneyapi.com/v1/confirm?symbol=BTC&direction=long"

# Get whale data
curl -X GET \
  -H "X-API-Key: sm_your_key" \
  "https://api.smartmoneyapi.com/v1/whales?symbol=BTC"

# Check usage
curl -X GET \
  -H "X-API-Key: sm_your_key" \
  "https://api.smartmoneyapi.com/v1/usage"

Freqtrade Integration

Add Smart Money confirmation to any Freqtrade strategy by overriding the confirm_trade_entry method.

Python — Freqtrade Strategy

import requests
from freqtrade.strategy import IStrategy

class SmartMoneyStrategy(IStrategy):
  SM_API_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  # Skip check for unsupported
    try:
      r = requests.get(
        f"{self.SM_BASE}/confirm",
        params={"symbol": symbol, "direction": "long"},
        headers={"X-API-Key": self.SM_API_KEY},
        timeout=3
      ).json()
      return r.get("confidence") != "VETO"
    except:
      return True  # Fail open on API error

CCXT + Smart Money

Python — CCXT

import ccxt, requests

exchange = ccxt.bybit({
  "apiKey": "YOUR_BYBIT_KEY",
  "secret": "YOUR_BYBIT_SECRET"
})

SM_KEY = "sm_your_key"

def smart_trade(symbol, side, amount):
  # Check confirmation first
  conf = requests.get(
    "https://api.smartmoneyapi.com/v1/confirm",
    params={"symbol": symbol, "direction": side},
    headers={"X-API-Key": SM_KEY}
  ).json()

  if conf["confidence"] == "VETO":
    print(f"VETO on {symbol} {side}. Skipping.")
    return None

  adj_amount = amount * conf["size_mult"]
  order = exchange.create_market_order(
    f"{symbol}/USDT", side, adj_amount
  )
  print(f"Order placed: {adj_amount} {symbol} {side}")
  return order