API Documentation — Smart Money API

Design principles

Four ideas shape every endpoint and every score this API returns. They are also the honest boundaries of what it does — and does not — promise.

Strategy-first, not signal-first. This is not a buy/sell signal feed. You bring the strategy and the entry; the API tells you whether the surrounding market structure — derivatives positioning, funding, open interest, liquidations, on-chain flow, and whale consensus — agrees with the trade you already want to take.

Confidence-scored, not binary prediction. Every answer carries a graded confidence (HIGH / MEDIUM / LOW) and a composite from -1.0 to +1.0. There are no guarantees and no oracle calls — you get a calibrated read on agreement, with the reasons behind it, so you can size proportionally to conviction.

Decision support, not execution advice. The API returns a CONFIRM / REDUCE / SKIP recommendation and a size multiplier for your logic to act on. It never places orders, and nothing here is financial advice. You remain responsible for risk, sizing, and execution.

Living metrics, not fixed guarantees. Win rates, regime statistics, and accuracy figures are computed from a rolling sample and move as markets move. We publish them honestly, including when they are mediocre. Treat every metric as a current observation, not a promise about the future.

Who this API is for

This API is built for crypto bot, algo, and AI-agent developers who already have a long/short signal — from a TA strategy, an ML model, a Freqtrade pipeline, a TradingView alert, or an LLM agent — and want a fast, pre-trade CONFIRM / REDUCE / SKIP decision before committing capital.

A typical loop: your strategy fires "go long BTC" → you call GET /v1/confirm?symbol=BTC&direction=long → you confirm, reduce, or skip the entry and scale size by size_mult. One call, single low-latency JSON response, no extra infrastructure.

It is not a standalone signal generator, a charting product, or an execution venue. If you have no signal of your own to gate, start with the performance page to see how the score has behaved before wiring it into a live bot.

Getting access

1 — Sign up. Create a free account at signup (email/password or Google). No credit card required for the free tier.

2 — Open your dashboard. Your dashboard shows your API key, current plan, and live usage against your daily quota.

3 — Copy your API key. Keys are prefixed sm_. Pass it as the X-API-Key header on every request (see Authentication). Upgrade any time on the pricing page to raise limits and unlock more symbols and endpoints.

Spec, SDK & Cookbook

Everything you need to integrate quickly, whether you write the code yourself or hand it to a coding agent.

Resource	What it is
Cookbook	Copy-paste recipes for the most common integrations — confirm before entry, gate a Freqtrade signal, size by multiplier, handle 402/429, and wire it into a coding agent.
OpenAPI spec	Machine-readable OpenAPI definition of every endpoint. Import into Postman/Insomnia, generate clients, or feed to an LLM. At `github.com/tashiardit/smartmoneyapi-docs`.
Python client	Official Python client library at `github.com/tashiardit/smartmoneyapi-python`.
/llms.txt	An LLM-friendly plain-text summary of the API. Point Claude, Codex, or Cursor at it (see Coding Agents).

Quickstart in 2 minutes

Step 1 — Base URL. Every endpoint lives under:

Base URL
https://api.smartmoneyapi.com

Step 2 — Get your API key. Sign up for free (no credit card required) and copy your key from the dashboard. Pass it as the X-API-Key header on every request.

Step 3 — Your first call. Paste this into your terminal and replace sm_your_key with the key from your dashboard:

cURL

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

Expected 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", "Whales: 67% long consensus"]
}

When confidence is HIGH or MEDIUM and action is CONFIRM, scale your position size by size_mult. That is the entire integration loop. See Response Fields for the full field reference.

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.

WebSocket auth is different. Never put your key in a WebSocket URL. Real-time streams use short-lived, single-use tickets: POST your key to /v1/ws/ticket with the X-API-Key header, then connect with the returned ticket. See WebSocket authentication (tickets).

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	50	2/min	60 seconds
Trader	1,000	20/min	Real-time
Pro	5,000	60/min	Real-time
Enterprise	100,000	400/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.

Errors

Errors use standard HTTP status codes and a consistent JSON body. Always branch on the status code, not on response text. The three you will hit most often:

Status	Code	Meaning & what to do
401	unauthorized	Missing or invalid API key. Check the `X-API-Key` header is present and correct.
402	payment_required	The endpoint or symbol needs a higher plan than your key has (e.g. a free key calling the WebSocket firehose). Upgrade or fall back to a public endpoint.
429	rate_limit_exceeded	Daily or burst limit reached. Back off and retry after `X-RateLimit-Reset`; do not hammer.

Every error returns the same shape:

JSON
{
  "error": "rate_limit_exceeded",
  "message": "Daily limit of 50 calls reached. Resets at 00:00 UTC.",
  "status": 429
}

For the complete list of status codes (400 / 403 / 500 / 503 and more), see Error Codes. A robust integration treats 5xx and 429 as transient (retry with backoff) and 401/402/403 as terminal (fix the key or plan).

Security best practices

Send the key in the header, never the URL. Always pass X-API-Key as an HTTP header. Keys in query strings (?key=) get logged by proxies, load balancers, and browser history — the legacy ?key= auth is no longer accepted on WebSocket endpoints for exactly this reason.

Keep keys server-side. Never embed an API key in client-side JavaScript, a mobile app bundle, or a public repository. Load it from an environment variable or secret manager. If a key leaks, rotate it.

Rotate keys periodically. Regenerate your key from the dashboard on a schedule and immediately if you suspect exposure. The old key stops working the moment a new one is issued.

Use tickets for browser sockets. For real-time streams from the browser, exchange your key for a single-use ticket rather than connecting with the raw key — see WebSocket authentication (tickets).

Using with coding agents / LLMs

Building with Claude Code, Codex, Cursor, or any LLM coding agent? You can hand the agent everything it needs to wire up this API correctly in one shot. Two machine-readable references are published:

Resource	URL
LLM summary	`https://smartmoneyapi.com/llms.txt`
OpenAPI spec	`github.com/tashiardit/smartmoneyapi-docs`

Point your agent at the /llms.txt file (the llms.txt convention) for a concise overview, then the OpenAPI spec for exact request/response shapes. A one-line prompt that works well:

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 that calls GET /v1/confirm and skips entries
unless action is CONFIRM.

See the Cookbook for a worked coding-agent recipe.

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.

Coverage, in plain terms. /confirm currently scores BTC, ETH and SOL — the symbols with enough resolved history to confirm honestly. The derivatives screener separately monitors ~519 derivatives markets for funding, OI and liquidation data, and whale tracking covers 600+ wallets. Pro unlocks the full screener, exports and broader market coverage; /confirm symbol support is expanded as each market accumulates a reliable track record.

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_FULL",
  "size_mult": 1.5,
  "deriv_score": 0.81,
  "onchain_score": 0.68,
  "whale_score": 0.73,
  "x_score": 0.0,
  "factors": {
    "derivatives": { "score": 0.81, "weight": 0.40, "weighted": 0.324 },
    "onchain": { "score": 0.68, "weight": 0.35, "weighted": 0.238, "source": "coinmetrics", "available": true },
    "whale": { "score": 0.73, "weight": 0.25, "staleness_factor": 1.0, "weighted": 0.183 }
  },
  "adjustments": { "agreement": 0.0, "trend": 0.0, "news_macro": 0.0 },
  "weights": { "derivatives": 0.40, "onchain": 0.35, "whale_intel": 0.25 },
  "coverage": { "derivatives": true, "whale": true, "onchain": true },
  "reasons": [
    "Funding rate positive across all venues",
    "LSR favors longs: 1.42",
    "Whales: 67% long consensus",
    "MVRV above 1.0 — on-chain bullish"
  ]
}

Transparent by design. Every response carries a factors object showing each leg's score × weight = weighted contribution, an adjustments object for post-filter tweaks, the weights used, and a coverage map. The on-chain leg uses real free Coin Metrics data (MVRV / exchange-flow / active-address) when no Glassnode key is set. This is a multi-factor confluence score — decision support, not a guaranteed win-rate.

Untracked symbols are honest. A symbol outside the tracked derivatives/whale universe returns an explicit "confidence":"NO_DATA" / "action":"NO_DATA_SKIP" with "unsupported":true — never a fabricated LOW.

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 confluence score from -1.0 (extreme contra) to +1.0 (strong confirm). Not a win-rate.
base_composite	float	Composite before post-filter adjustments were applied
confidence	string	`HIGH` / `MEDIUM` / `LOW` / `VETO` / `NO_DATA`
action	string	`CONFIRM_FULL` / `CONFIRM_REDUCED` / `CONFIRM_MINIMAL` / `VETO_SKIP` / `NO_DATA_SKIP`
size_mult	float	Suggested position size multiplier (e.g. 0.0 – 1.5)
unsupported	bool	`true` when the symbol is outside coverage (paired with NO_DATA)
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)
x_score	float	X/social-sentiment sub-score (-1 to 1); 0 when unused
factors	object	Per-leg breakdown: `score × weight = weighted` for derivatives / onchain / whale / x_sentiment (onchain includes `source`)
adjustments	object	Signed post-filter tweaks (agreement, trend, rsi_1h, news_macro, momentum, time_of_day, streak_decay)
weights	object	Weight set actually used for this evaluation
coverage	object	`{derivatives, whale, onchain}` — which legs had real data
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 /v1/derivatives/*

Cross-exchange derivatives screener across 500+ symbols: funding-rate heatmap, open-interest rankings, and long/short-ratio signal detection. Top 10 rows are public; the full screener requires Trader or Pro. Endpoints: /v1/derivatives/screener, /v1/derivatives/funding, /v1/derivatives/oi, /v1/derivatives/signals.

GET /v1/options/*

Deribit-sourced BTC & ETH options analytics (public, no auth): put/call ratio, max pain, and open interest by strike. Endpoints: /v1/options/summary, /v1/options/pcr, /v1/options/oi.

GET /v1/etf/*

Spot BTC & ETH ETF daily net flows and per-fund breakdown (public). Endpoints: /v1/etf/flows, /v1/etf/funds.

GET /v1/historical/*

Historical funding, open interest, long/short ratio (Binance), and OHLCV (CoinGecko) for backtesting. Endpoints: /v1/historical/funding, /v1/historical/oi, /v1/historical/lsr, /v1/historical/ohlcv.

GET /v1/dex/*

DexScreener-powered trending pairs, token search, and pair details (public, no auth). Endpoints: /v1/dex/trending, /v1/dex/search, /v1/dex/token, /v1/dex/pair.

GET /v1/news/*

News intelligence: policy/geopolitical/crypto news classified into impact categories, plus Fear & Greed (public, no auth). Endpoints: /v1/news/trump, /v1/news/general, /v1/news/impact, /v1/news/fear-greed.

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/MEDIUM signals across all monitored assets. Useful for opportunity scanning.

Requires: Pro

GET /v1/strategies/*

Transparent, read-only track record for the automated trading strategies that execute on top of Smart Money signals — including the deriv40 SmartMoney Copytrade strategy (account=9). All endpoints take a ?account=<id> query parameter and return JSON. No authentication required (public track record).

Endpoints

GET /v1/strategies/stats?account=9 — headline metrics: total_trades, win_rate, profit_factor, total_pnl_usdt, account_growth_percent, initial_equity, current_equity, max_drawdown_portfolio, max_drawdown_trade.
GET /v1/strategies/equity?account=9 — equity curve for charting: { initial_equity, curve: [{ time, equity }] }.
GET /v1/strategies/trades?account=9&limit=500 — closed-trade ledger: array (or {trades:[…]}) of symbol, direction, entry_price, exit_price, pnl_usdt, pnl_percent, pnl_percent_net.
GET /v1/strategies/active?account=9 — currently open positions: array (or {positions:[…]}) of symbol, side/direction, entry_price, unrealized_pnl.
GET /v1/strategies/signals — signal-type breakdown feeding the strategies (count / wins / win_rate / avg_pnl per signal type).

Past performance is not indicative of future results. Figures are backfilled over a single ~3-month regime plus live trades and are shown pre-fee where noted.

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.

POST /webhooks

Requires: Pro

Register an HTTPS URL to receive real-time signed event pushes when a signal fires across your monitored assets. Deliveries carry an X-SmartMoney-Event header and an HMAC-SHA256 signature in X-SmartMoney-Signature, and retry up to 3× with backoff.

Request Body

Field	Type	Description
urlrequired	string	HTTPS endpoint to POST events to (must start with `https://`)
eventsrequired	array	Event names, e.g. `["HIGH","MEDIUM","VETO"]` or `["*"]`
symbolsrequired	array	Symbols to filter, e.g. `["BTC","ETH"]` or `["*"]`
secretrequired	string	Your signing secret, ≥ 16 chars (stored hashed)

Verifying the signature

The HMAC key is the SHA-256 hex digest of your registered secret. Compute the HMAC-SHA256 of the raw request body with that key and compare (constant-time) against X-SmartMoney-Signature. See the Webhook Implementation guide.

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 two complementary views: (1) leverage-projected levels — an estimate of where liquidation clusters sit; and (2) a realized_heatmap — the REAL executed forced-liquidation intensity (price × time), aggregated live from public exchange WebSocket feeds: Binance, OKX, Bybit, Bitget, BitMEX. The heatmap is present when the stream has data for the symbol (absent in a very calm market or just after startup).

Parameters

Parameter	Type	Description
symboloptional	string	Asset symbol (default `BTC`). Real heatmap covers actively-traded perp symbols.

Example Response

JSON

{
  "symbol": "BTC",
  "cascade_risk": "HIGH",
  "nearest_long_liq_pct": -3.2,
  "nearest_short_liq_pct": 4.1,
  "levels": { "long_levels": [ … ], "short_levels": [ … ] },
  // REAL executed liquidations — live from 5 exchanges
  "realized_heatmap": {
    "window_minutes": 240, "price_min": 91000.0, "price_max": 99000.0,
    "clusters": [ { "price": 93250.0, "notional": 4820000.0, "count": 37, "dominant_side": "long" } ],
    "by_side": { "long": 6100000.0, "short": 2400000.0 },
    "totals": { "total_notional": 8500000.0, "count": 214 },
    "exchanges": { "binance": 120, "okx": 40, "bybit": 34, "bitget": 12, "bitmex": 8 }
  }
}

Trader plan: cascade_risk, nearest distances, and realized totals/by-side. Pro plan: full projected levels plus the full realized_heatmap (matrices, per-price clusters, per-exchange counts). The projected estimate answers "where are the stops"; the realized heatmap shows "what actually got liquidated."

GET /liquidations/heatmap

Available to: Free No authentication required (per-IP throttled)

Public price-level liquidation heatmap. Returns a Coinglass-style price × time matrix of REAL executed forced liquidations, bucketed by the price at which each liquidation printed — aggregated live from public exchange WebSocket feeds: Binance, OKX, Bybit, Bitget, BitMEX. The clusters array is the practical output: price buckets ranked by liquidated notional, each tagged with its dominant side. Data depends on the live stream — a very quiet symbol or a just-restarted gateway returns the well-formed empty structure plus an honest note. Levels shown are only ever real liquidations, never estimated.

Parameters

Parameter	Type	Description
symboloptional	string	Asset symbol (default `BTC`).
window_minutesoptional	int	Look-back window in minutes (default `240`, clamped to 5–1440).
price_bucketsoptional	int	Number of price buckets (default `50`, clamped to 5–100).

Example Response

JSON

{
  "symbol": "BTC", "window_minutes": 240, "price_buckets": 50,
  "price_min": 91000.0, "price_max": 99000.0, "price_bucket_size": 160.0,
  "price_levels": [ 91080.0, 91240.0, … ], "time_buckets": [ … ],
  "matrix": [ [ … ] ], "long_matrix": [ [ … ] ], "short_matrix": [ [ … ] ],
  "clusters": [
    { "price": 93250.0, "notional": 4820000.0, "long_notional": 4100000.0,
      "short_notional": 720000.0, "count": 37, "dominant_side": "long" }
  ],
  "by_side": { "long": 6100000.0, "short": 2400000.0 },
  "totals": { "long_liq_notional": 6100000.0, "short_liq_notional": 2400000.0, "total_notional": 8500000.0, "count": 214 },
  "exchanges": { "binance": 120, "okx": 40, "bybit": 34, "bitget": 12, "bitmex": 8 },
  "generated_at": 1710940200, "public": true
}

Honest note: this endpoint reflects only what the live stream has captured. When a symbol is quiet or the stream just started, totals.count is 0, clusters is empty, and a note field explains why. It is a record of executed liquidations — not a prediction. For the projected "where are the stops" estimate, use the authenticated /liquidations endpoint.

GET /liquidations/onchain

Requires: Trader Pro

Executed on-chain DeFi lending liquidations captured directly from our own local BSC + Avalanche full nodes — independent of any trading bot. Covers Venus/Cream and Moolah on BSC, and AAVE V3/V2, Benqi, BankerJoe, Granary and Vinium on Avalanche. Pro tier additionally returns at_risk positions (bot-dependent, may be absent).

Parameters

Parameter	Type	Description
chainoptional	string	`bsc` or `avax`. Omit for all chains.
limitoptional	integer	Max rows (default 100, max 500). Newest-first.

Example Response

JSON

{
  "chain": "bsc", "count": 2,
  "liquidations": [
    { "chain": "bsc", "protocol": "Venus", "borrower": "0x2be6…8dfa",
      "debt_symbol": "DAI", "repay_usd": 426.15,
      "collateral_symbol": "WBNB", "tx_hash": "0x718c…7c0e", "block": 89170816, "ts": 1710940200 }
  ],
  "summary": {
    "window_hours": 24, "enabled": true,
    "by_protocol": { "bsc:Venus": { "count": 61, "repay_usd_known": 148230.55 } },
    "nodes": { "bsc": { "reachable": true, "head_block": 89173010, "events_total": 61 } }
  }
}

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.

Free public variant No auth

A no-key public endpoint returns the top 10 opportunities with a live cross-exchange screener, ideal for embedding or quick checks. It drops per-symbol spread history and heavy fields and is served from a 120-second cache. When no cross-exchange funding spreads exist in the freshness window it returns an empty opportunities array with a note — never fabricated data.

GET (no auth)

GET /v1/derivatives/funding-arb

JSON

{
  "opportunities": [
    {
      "symbol": "OGN",
      "spread_pct": 0.297667,
      "annualized_apr": 325.95,
      "long_exchange": "bybit",
      "short_exchange": "hyperliquid",
      "estimated_profit_per_10k": 29.77,
      "risk_notes": "Low spread — ensure fees do not consume the arbitrage margin."
    }
  ],
  "scanned_symbols": 222,
  "ts": 1783268753,
  "public": true,
  "limited": true
}

Free, no API key. Top 10 opportunities only, capped and cached (120 s). Live screener page: funding-arb.html.

GET /smart-money/flow

Requires: Trader Pro

A quality-weighted whale directional index per symbol, scored -100 (whale money leaning short) to +100 (leaning long). Built from thousands of tracked Hyperliquid whale wallets — each weighted by its own historical win-rate and PnL and decayed by recency. This is a positioning index, not a buy/sell signal or price prediction. Symbols with few contributing wallets are labelled thin and scored honestly. Live page: smart-money-flow.html.

Parameters

Parameter	Type	Description
symboloptional	string	Single symbol (e.g. `BTC`). Omit to get all tracked symbols ranked by \|score\|.
window_hoursoptional	int	Scoring window, clamped to `1..168`. Default `24`.

Example Response

JSON

{
  "symbols": [
    {
      "symbol": "SPX",
      "score": -90.93,
      "direction": "strong_short",
      "n_wallets": 26,
      "long_usd": 184200.0, "short_usd": 2410000.0,
      "quality_weighted": true,
      "sample_quality": "rich",
      "top_contributors": [ { "wallet": "0x31ca…974b", "direction": "short", "value_usd": 5338.25, "weight": 0.4948 } ]
    }
  ],
  "window_hours": 24,
  "quality_weighted": true,
  "ts": 1783270000,
  "note": "Quality-weighted whale directional positioning index (-100..+100). Not a price prediction or buy/sell signal."
}

Trader plan: Top 12 symbols, contributor detail withheld. Pro plan: All symbols with per-symbol top_contributors. Wallet weights are bounded to [0.25,1.0]; PnL is an unrealised proxy from the latest position snapshots.

GET /v1/whales/crowding

Available to: Free No authentication required — anonymous gets top 10 symbols, Trader+ gets the full list

Combined whale positioning & crowding context per symbol, merged across Hyperliquid + GMX v2 + Jupiter Perps. Returns gross/net notional, directional skew, wallet & venue counts, position concentration (top-3 share + HHI), a weighted-average leverage, and liquidation-proximity buckets ($ notional sitting within 5% and 10% of its estimated liquidation price, split long/short). This is context, not a directional signal. Fields that are not derivable are null and render as — — e.g. lev_wavg/crowding_index when no position carries leverage. Liquidation distances are an isolated-margin estimate (pct_to_liq ≈ 1/lev + upnl/notional − mmr, mmr = 0.01), not exchange-reported liquidation prices.

Parameters

Parameter	Type	Description
min_notionaloptional	float	Minimum combined gross notional (USD) for a symbol to be included. Default: `1000000`.

Example Request

GET (no auth)

curl "https://api.smartmoneyapi.com/v1/whales/crowding?min_notional=1000000"

Example Response

JSON

{
  "ok": true, "ts": 1783423500, "min_notional": 1000000, "n_symbols": 92,
  "symbols": [
    {
      "symbol": "BTC",
      "gross_usd": 2447900000.0, "net_usd": -51000000.0, "skew": -0.021,
      "n_whales": 414, "n_venues": 3,
      "venues": {
        "hl": { "gross": 1900000000.0, "net": -40000000.0, "n_whales": 272 },
        "gmx": { "gross": 320000000.0, "net": -6000000.0, "n_whales": 59 },
        "jupiter": { "gross": 227900000.0, "net": -5000000.0, "n_whales": 83 }
      },
      "conc_top3": 0.159, "hhi": 0.011, "lev_wavg": 19.1,
      "liq_within_5pct": { "long": 621700000.0, "short": 665600000.0 },
      "liq_within_10pct": { "long": 840000000.0, "short": 910000000.0 },
      "crowding_index": 0.003
    }
  ],
  "caveats": [ "Liquidation distances are isolated-margin estimates, not exchange-reported." ]
}

Honest note: skew is net/gross ∈ [-1,1]; crowding_index = |skew|·conc_top3·min(lev/20,1). Only venues actually present appear in venues. Positions with no leverage are excluded from the liq buckets rather than assumed. Anonymous callers receive the top 10 symbols by gross (with gated: true); Trader+ receive the full list.

GET /v1/options/gex

Available to: Free No authentication required (per-IP throttled)

Dealer gamma exposure (GEX) analytics for BTC & ETH, computed live from the public Deribit options chain (no auth). Returns net dealer GEX per strike (SpotGamma dealer-short convention), the gamma-flip level (strike where cumulative net GEX crosses zero), the IV term structure (ATM implied vol by days-to-expiry), and a front-expiry IV skew (25Δ-proxy risk reversal). GEX regime is positive (dealers long gamma → vol-suppressing) or negative (vol-amplifying). Fully self-contained — recomputed on every call, no stored-DB dependency.

Parameters

Parameter	Type	Description
symboloptional	string	`BTC` or `ETH` only. Default: `BTC`.

Example Request

GET (no auth)

curl "https://api.smartmoneyapi.com/v1/options/gex?symbol=BTC"

Example Response

JSON

{
  "symbol": "BTC", "available": true, "spot": 63203.0,
  "net_gex": 18240000.0, "regime": "positive",
  "gamma_flip": 64919.82, "gamma_flip_pct": 2.72,
  "call_gex": 31200000.0, "put_gex": -12960000.0,
  "by_strike": [
    { "strike": 60000, "net_gex": -2100000.0 },
    { "strike": 65000, "net_gex": 4800000.0 }
  ],
  "term_structure": [
    { "expiry": "8JUL26", "dte": 0.76, "atm_iv": 62.1 },
    { "expiry": "27MAR26", "dte": 14.2, "atm_iv": 58.4 }
  ],
  "skew": {
    "expiry": "8JUL26", "dte": 0.76,
    "put_iv": 69.69, "atm_iv": 62.1, "call_iv": 55.34,
    "risk_reversal": 14.35, "bias": "downside_fear"
  }
}

Honest note: Deribit contract multiplier is 1 (coin-denominated OI). On any fetch failure the endpoint returns available: false with empty panels — never fabricated GEX. IV skew uses a fixed ±10% strike proxy for 25Δ (true 25-delta requires solving delta per strike); adequate for display, documented as an approximation.

GET /v1/liquidations/simulate

Available to: Free No authentication required (per-IP throttled)

Interactive liquidation cascade stress-test. Given a hypothetical price move, returns the estimated leveraged positions that would get liquidated, forced volume by price level / side / exchange, and a cascade-depth readout. A downward move liquidates longs whose liq-price sits at/above the target; an upward move liquidates shorts whose liq-price sits at/below it. Two independent methods are merged: exact liquidation prices from tracked Hyperliquid whales' real leverage/entry, plus statistical OI-band clusters per exchange (crowd leverage inferred from funding). Everything is clearly labelled estimated: true — it cannot know per-account margin, cross vs isolated, added margin, or ADL.

Parameters

Parameter	Type	Description
symboloptional	string	Asset symbol. Default: `BTC`.
move_pctoptional	float	Hypothetical price move as a percent (negative = down, positive = up). Default: `-5`.

Example Request

GET (no auth)

curl "https://api.smartmoneyapi.com/v1/liquidations/simulate?symbol=BTC&move_pct=-5"

Example Response

JSON

{
  "ok": true, "estimated": true, "symbol": "BTC",
  "ref_price": 63000.0, "move_pct": -5.0, "target_price": 59850.0,
  "triggered_notional_usd": 380000000.0,
  "cascade_depth": 0.029, "cascade_bucket": "low",
  "by_exchange": { "hyperliquid": 260000000.0, "binance": 80000000.0, "bybit": 40000000.0 },
  "by_side": { "long": 380000000.0, "short": 0.0 },
  "clusters": [
    { "price": 60100.0, "side": "long", "notional_usd": 42000000.0, "whale_usd": 18000000.0, "oi_usd": 24000000.0 }
  ],
  "whale_positions_used": 272, "exchanges": 3,
  "realized_context": { "available": true, "coverage_hours": 17.8, "by_side_24h": { "long": 6100000.0, "short": 2400000.0 } },
  "methodology": { "disclaimer": "Estimated — cannot know per-account margin, cross vs isolated, add-margin, or ADL." }
}

Honest note: Every projected number is derived from real DB reads; nothing is fabricated on failure. An untracked symbol, stale snapshot, or missing price returns ok: true, empty: true with a plain-English message, not fake bars. realized_context is a young, growing sample from the live forced-liquidation stream, surfaced only as context — it never makes the projection "realized."

GET /v1/wallet/{addr}/profile

Available to: Free No authentication required (per-IP throttled)

A cross-venue wallet profile built entirely from the live tracked-whale position snapshots. For a tracked Hyperliquid whale, returns current open positions, an unrealized-PnL / exposure / position-count time series, an OPEN/CLOSE/FLIP activity timeline (reconstructed by diffing consecutive snapshots), the decoded HL-leaderboard label, and an open-book summary. Live page: wallet-profiler.html.

Parameters

Parameter	Type	Description
addrrequired	string	Wallet address (path segment), e.g. `/v1/wallet/0x3bcae23e…/profile`.
daysoptional	integer	Look-back window for the series & timeline. Default: `30`.

Example Request

GET (no auth)

curl "https://api.smartmoneyapi.com/v1/wallet/0x3bcae23e8c380dab4732e9a159c0456f12d866f3/profile?days=30"

Example Response

JSON

{
  "ok": true, "wallet": "0x3bcae23e…", "tracked": true,
  "first_seen_ts": 1782827733, "latest_snapshot_ts": 1783418468, "as_of": 1783418468,
  "hyperliquid": {
    "label": { "name": "Andre is back", "score": 74,
      "window_pnl_usd": 1307000, "win_rate_pct": 71, "trades": 42 },
    "positions": [
      { "venue": "hyperliquid", "symbol": "ETH", "direction": "short",
        "size": 1200.0, "entry_px": 1800.0, "unrealized_pnl": 34800.0,
        "leverage": 20.0, "value_usd": 2160000.0 }
    ],
    "series": [ { "ts": 1783330000, "unrealized_pnl": 42000.0, "exposure_usd": 18400000.0, "positions": 5 } ],
    "timeline": [ { "ts": 1783400000, "event": "flip", "symbol": "ETH",
      "direction": "short", "from_direction": "long", "value_usd": 2160000.0 } ],
    "summary": {
      "open_positions": 5, "in_profit": 3, "in_loss": 2, "longs": 0, "shorts": 5,
      "total_unrealized_pnl": -12000.0, "total_exposure_usd": 21000000.0, "blended_leverage": 19.9,
      "window_days": 30, "snapshots_in_window": 474,
      "realized_pnl": null, "realized_pnl_note": "Not derivable — only open snapshots are seen, never closing fills."
    }
  }
}

Honest note: everything shown is real from the snapshot data — pnl is HL's own unrealized mark-to-market, value_usd is open notional. Realized P&L per round-trip is unavailable (we only see open snapshots, never closing fills) and is shown as null / —; timeline CLOSE events carry no P&L claim. A valid but untracked address returns tracked: false with a note; an invalid address returns ok: false, error: "invalid_address" (HTTP 400). The HL-leaderboard label is HL's own window standing at discovery, not computed by us.

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

GET /sentiment

Requires: Trader Pro

Returns a real-time Fear & Greed index (0-100) computed from derivatives sentiment, whale activity, volatility, and social signals. Includes component breakdown and 24-hour history for trend analysis.

Parameters

Parameter	Type	Description
symboloptional	string	Asset symbol. Default: `BTC`

Example Response

JSON

{
  "symbol": "BTC",
  "score": 72,
  "label": "Greed",
  "components": {
    "volatility": 65,
    "momentum": 78,
    "derivatives": 70,
    "whale_activity": 75,
    "social": 68
  },
  "history_24h": [
    { "ts": 1710940800, "score": 68, "label": "Greed" },
    { "ts": 1710937200, "score": 65, "label": "Greed" }
  ],
  "ts": 1710940821
}

Competitor equivalent: Santiment Social Volume + Alternative.me Fear & Greed — combined into a single endpoint with component breakdown.

Integrations

GET /tradingview/setup

Requires: Trader Pro

Returns your personalized TradingView integration setup: webhook URL, secret for validation, and ready-to-use Pine Script indicators that connect directly to the Smart Money API. Copy-paste the Pine Script into TradingView to overlay our signals on any chart.

Example Response

JSON

{
  "webhook_url": "https://api.smartmoneyapi.com/v1/tradingview/webhook",
  "webhook_secret": "tvs_a1b2c3...",
  "pine_scripts": {
    "composite_indicator": "// Smart Money Composite v1\n//@version=5\nindicator(...)...",
    "whale_activity": "// Whale Activity Overlay v1\n...",
    "funding_dashboard": "// Funding Rate + LSR Dashboard v1\n..."
  }
}

POST /tradingview/webhook

Available to: Trader Pro

Receives a TradingView alert, runs it through /confirm, and returns the confirmation. TradingView cannot send custom headers, so authenticate by including your webhook secret in the JSON body (this endpoint does not use X-API-Key). The response wraps the confirmation and adds a top-level action of CONFIRMED (daemon confidence HIGH/MEDIUM) or VETOED.

Request Body

JSON

{
  "secret": "your_webhook_secret",
  "symbol": "BTC",
  "direction": "long",
  "timeframe": "1h",
  "strategy": "EMA crossover",
  "price": 67500.0
}

Required: secret, symbol, direction (long|short). Optional: source, timeframe, strategy, price.

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

Real-Time Streaming (Live Swaps)

Stream DEX swaps ≥ $500 detected in real-time from our own BSC and Avalanche nodes. Two transports are available: a public Server-Sent Events (SSE) stream for free/browser clients, and a low-latency WebSocket firehose for paid tiers. Events are broadcast within seconds of inclusion in a block.

Public SSE Stream (Free)

Available to: Free Trader Pro

GET /v1/stream/public-swaps

No authentication required. Native EventSource support in all modern browsers. The server emits swap events and periodic heartbeats to keep the connection alive.

JavaScript (browser)

const es = new EventSource("https://api.smartmoneyapi.com/v1/stream/public-swaps");
es.addEventListener("swap", e => {
  const swap = JSON.parse(e.data);
  console.log(swap.chain, swap.pair, swap.amount_usd);
});

WebSocket Firehose (Paid)

Requires: Trader Pro

WSS /v1/ws/live-swaps?ticket=…

Authentication (recommended): never put your long-lived key in the URL — it gets logged by proxies and saved in browser history. Instead POST your key to /v1/ws/ticket using the safe X-API-Key header, then open the socket with the returned single-use ticket (valid ~60s, redeemed once). Server-side clients that can set headers may instead pass X-API-Key directly on the handshake. Free-tier keys receive a 402 payment_required response. A hello frame is sent on connect with your tier and the broadcast threshold.

JavaScript (browser)

// 1. Exchange your key for a short-lived ticket (key stays in the header)
const r = await fetch("https://api.smartmoneyapi.com/v1/ws/ticket", {
  method: "POST", headers: { "X-API-Key": "sm_xxx" }
});
const { ticket } = await r.json();
// 2. Open the socket with the single-use ticket
const ws = new WebSocket(`wss://api.smartmoneyapi.com/v1/ws/live-swaps?ticket=${ticket}`);
ws.onmessage = e => {
  const swap = JSON.parse(e.data);
  if (swap.type === "swap") console.log(swap);
};

WebSocket authentication (tickets)

Why: never put your API key in a WebSocket URL — query strings get logged by proxies, load balancers, and saved in browser history. Instead, exchange your key for a short-lived, single-use ticket over a normal authenticated POST, then connect with that ticket.

Flow: POST to /v1/ws/ticket with your X-API-Key header → receive { "ticket": "…", "expires_in": 60 }. Then open wss://api.smartmoneyapi.com/v1/ws/live-swaps?ticket=<ticket>. The ticket is single-use and expires in ~60 seconds. Server-side clients that can set request headers may instead pass X-API-Key directly on the WebSocket handshake — no ticket needed.

POST /v1/ws/ticket

Requires: Trader Pro

Mints a one-time ticket for an authenticated WebSocket handshake. Authenticate with the X-API-Key header (your key never leaves the request headers). The returned ticket can be redeemed once on /v1/ws/live-swaps before it expires.

cURL

curl -X POST -H "X-API-Key: sm_your_key" \
  "https://api.smartmoneyapi.com/v1/ws/ticket"

Example Response

JSON

{
  "ticket": "wst_9f3c1a8e4b2d…",
  "expires_in": 60
}

Response Fields

Field	Type	Description
ticket	string	Single-use token to append as `?ticket=` on the WebSocket URL. Redeemed once, then invalidated.
expires_in	number	Seconds until the ticket expires (~60). Mint a fresh ticket per connection attempt.

Note: the legacy ?key= query-param authentication is no longer accepted on WebSocket endpoints for security reasons. Use a ticket (browser clients) or the X-API-Key handshake header (server-side clients).

REST Snapshot

GET /v1/live-swaps/recent?limit=20

Returns the last N broadcast swaps from the rolling buffer. Useful for first-paint on dashboards before the stream connection opens. Also available: /v1/live-swaps/status for broadcaster stats.

Event Schema

Field	Type	Description
chain	string	`bsc` or `avalanche`
dex	string	Router name (e.g. `pancakeswap_v2`, `traderjoe`) or `unknown_dex`
swapper	string	Full 0x address of the wallet that executed the swap
swapper_short	string	Abbreviated form for display (e.g. `0xb300…028d`)
swapper_url	string	Direct link to the swapper on the chain's block explorer
tx_hash	string	Transaction hash
explorer_url	string	Direct link to the transaction on BscScan / Snowtrace
token_in	string	Symbol of the token sold (e.g. `USDT`)
token_out	string	Symbol of the token bought
amount_usd	number	USD value of the swap (minimum: $500)
pair	string	Formatted pair label (e.g. `USDT → USDC`)
block	number	Block number where the swap was mined
timestamp	number	Unix epoch seconds
significance	string	`low` / `medium` / `high` / `critical` based on USD size
seq	number	Monotonic broadcast sequence number — use for gap detection

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`, `eq`, `crosses_above`, `crosses_below`
thresholdrequired	float	Numeric value to compare the metric against
deliveryoptional	string	Delivery channel, e.g. `telegram` (default) or `webhook`
cooldown_minutesoptional	integer	Minimum minutes between re-triggers (default 60)

The live list of valid metrics and operators is returned by GET /v1/alerts/conditions as available_metrics and available_operators.

Available Metrics

Metric	Description
funding_rate	Current funding rate for symbol (as decimal)
global_lsr	Global long/short ratio for symbol
long_pct	Percentage of accounts net long for symbol
top_trader_lsr	Top-trader long/short ratio for symbol
taker_ratio	Taker buy/sell ratio for symbol
mvrv	Market Value to Realized Value ratio (BTC/ETH)
sopr	Spent Output Profit Ratio (BTC/ETH)
exchange_net_flow	On-chain exchange net-flow signal
accumulation	On-chain accumulation signal
whale_long_pct	Percentage of tracked whale wallets holding long positions for symbol
whale_n_wallets	Number of tracked whale wallets with a position in symbol
composite_long	Composite score for symbol queried in long direction
composite_short	Composite score for symbol queried in short direction
funding_spread	Cross-venue funding spread 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 }
  }
}

Stats & Signals

GET /v1/stats

Available to: Free Trader Pro No authentication required

Site-wide honest performance statistics sourced from smart_money_confirm distinct-call outcomes. Returns win rates at HIGH and MEDIUM confidence tiers, overall accuracy, profit factor, and a per-symbol breakdown. All figures are in-sample over the scoring window; consult calibration.html for context and forward-holdout methodology.

Example Response

JSON

{
  "high_winrate": 0.714,
  "high_winrate_n": 14,
  "medium_winrate": 0.530,
  "medium_winrate_n": 34,
  "overall_accuracy": 0.613,
  "overall_accuracy_n": 48,
  "profit_factor": 1.77,
  "avg_win_pct": 4.2,
  "winrate_horizon": "24h",
  "winrate_basis": "distinct confirm calls, 24h resolved outcomes",
  "winrate_by_symbol": {
    "BTC": { "win_rate": 0.68, "n": 22 },
    "ETH": { "win_rate": 0.55, "n": 18 },
    "SOL": { "win_rate": 0.60, "n": 8 }
  },
  "forward_holdout": {
    "win_rate": 0.59,
    "high_win_rate": 0.70,
    "high_n": 10,
    "is_distinct_from_insample": false
  }
}

In-sample caveat. All figures in this response are computed from the same period used to tune the scorer. The forward_holdout object is the only number accrued on data the scorer has never seen — watch it grow over time. See calibration.html for the full methodology and the in-sample / forward-test boundary.

GET /v1/signals/performance

Available to: Free Trader Pro No authentication required

Signal outcome tracking across multiple resolution horizons (4h, 12h, 24h, 72h). Returns hit rates per horizon, total signal counts, and a breakdown by signal type.

Parameters

Parameter	Type	Description
daysoptional	integer	Look-back window in days. Default: `30`
signal_typeoptional	string	Filter by type, e.g. `smart_money_confirm` or `regime_flip`. Omit for all types.
symboloptional	string	Filter by asset symbol, e.g. `BTC`. Omit for aggregate across all symbols.

Example Response

JSON

{
  "signal_type": "smart_money_confirm",
  "symbol": "BTC",
  "days": 30,
  "total_signals": 48,
  "horizons": {
    "4h": { "hit_rate": 0.65, "resolved": 46 },
    "12h": { "hit_rate": 0.61, "resolved": 44 },
    "24h": { "hit_rate": 0.58, "resolved": 40 },
    "72h": { "hit_rate": 0.54, "resolved": 32 }
  },
  "type_breakdown": {
    "smart_money_confirm": { "count": 35, "hit_rate_24h": 0.61 },
    "regime_flip": { "count": 13, "hit_rate_24h": 0.47 }
  }
}

GET /v1/signals/recent

Available to: Free Trader Pro No authentication required

Feed of recently published HIGH and MEDIUM signals across all monitored symbols. Each entry includes the signal type, confidence tier, direction, and resolution status where available.

Example Response

JSON

{
  "signals": [
    {
      "id": 1042,
      "symbol": "BTC",
      "direction": "long",
      "signal_type": "smart_money_confirm",
      "confidence": "HIGH",
      "composite": 0.74,
      "ts": 1710940821,
      "resolved": true,
      "outcome_24h": "win"
    }
  ],
  "count": 50
}

GET /v1/signals/{id}/outcome

Available to: Free Trader Pro No authentication required

Resolved outcome for a single signal by its numeric ID. Returns hit/miss at each resolution horizon (4h, 12h, 24h, 72h) along with the price at signal time and at resolution.

Parameters

Parameter	Type	Description
idrequired	integer	Signal ID (path segment), e.g. `/v1/signals/1042/outcome`

Example Response

JSON

{
  "id": 1042,
  "symbol": "BTC",
  "direction": "long",
  "confidence": "HIGH",
  "entry_price": 63200.0,
  "ts": 1710940821,
  "outcomes": {
    "4h": { "result": "win", "price": 64100.0, "pct": 1.41 },
    "12h": { "result": "win", "price": 65200.0, "pct": 3.16 },
    "24h": { "result": "win", "price": 65800.0, "pct": 4.11 },
    "72h": { "result": "pending", "price": null, "pct": null }
  }
}

GET /v1/confirm-winrate

Requires: Free Trader Pro

Confirm-signal win-rate breakdown for the authenticated user's own API key. Returns distinct-call win rates at each confidence tier, profit factor, and per-symbol figures. Requires a valid X-API-Key header.

Example Request

cURL

curl -H "X-API-Key: sm_your_key" \
  "https://api.smartmoneyapi.com/v1/confirm-winrate"

Example Response

JSON

{
  "high_winrate": 0.714,
  "high_n": 14,
  "medium_winrate": 0.530,
  "medium_n": 34,
  "overall_accuracy": 0.613,
  "overall_n": 48,
  "profit_factor": 1.77,
  "winrate_horizon": "24h",
  "by_symbol": {
    "BTC": { "win_rate": 0.68, "n": 22 },
    "ETH": { "win_rate": 0.55, "n": 18 }
  }
}

Distinct-call basis. Win rates are computed per distinct confirm call (one per symbol per 5-minute window), not per every API hit — this prevents N-inflation from bots that poll repeatedly. Figures are in-sample over the default 30-day window; the same caveat as /v1/stats applies.

Shadow Gate

Requires: Free Trader Pro

An immutable, append-only personal decision ledger. Submit your trade decisions before or after executing them; the system computes a confirm score against the Smart Money engine and appends a permanent row. Use it to build an honest, timestamped track record of how well the API's signal aligned with your own entries — entirely independent of the global win-rate pool. Free and Trader tier responses have evidence fields stripped; Pro returns the full breakdown. A tier delay applies to Free tier data.

POST /v1/shadow-gate/decisions

Submit a decision. Idempotent on the Idempotency-Key request header — re-submitting the same key returns the existing row without creating a duplicate. The system immediately calls the confirm engine and appends the result as an immutable ledger row.

Request Body

Field	Type	Description
symbolrequired	string	Asset symbol, e.g. `BTC`
siderequired	string	Trade direction: `long` or `short`
strategy_idoptional	string	Caller-defined strategy label (max 64 chars). Stored as-is for grouping and filtering.

Example Request

cURL

curl -X POST \
  -H "X-API-Key: sm_your_key" \
  -H "Idempotency-Key: my-signal-20260701-001" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"BTC","side":"long","strategy_id":"ema_crossover"}' \
  "https://api.smartmoneyapi.com/v1/shadow-gate/decisions"

Example Response

JSON

{
  "id": 318,
  "symbol": "BTC",
  "side": "long",
  "strategy_id": "ema_crossover",
  "decision": "CONFIRM",
  "confidence": "HIGH",
  "composite": 0.74,
  "size_mult": 1.5,
  "ts": 1710940821,
  "resolved": false
}

Tier note. Free and Trader responses omit the factors / adjustments evidence fields. Pro returns the full confirm breakdown. A tier delay applies to Free — the row is written immediately but the confirm score may reflect cached data up to 60 seconds old.

GET /v1/shadow-gate/decisions

List your own shadow-gate decisions, newest first. Owner-scoped — only decisions submitted by your API key are returned.

Parameters

Parameter	Type	Description
limitoptional	integer	Maximum rows to return. Default: `50`, max: `200`
cursoroptional	string	Opaque pagination cursor from a previous response's `next_cursor` field. Omit for the first page.

Example Response

JSON

{
  "decisions": [
    { "id": 318, "symbol": "BTC", "side": "long", "decision": "CONFIRM", "confidence": "HIGH", "composite": 0.74, "size_mult": 1.5, "ts": 1710940821, "resolved": false },
    { "id": 317, "symbol": "ETH", "side": "short", "decision": "SKIP", "confidence": "LOW", "composite": -0.12, "size_mult": 0.0, "ts": 1710937000, "resolved": true }
  ],
  "count": 2,
  "next_cursor": null
}

GET /v1/shadow-gate/decisions/{id}

Single decision by ID, including the full confirm evidence for Pro tier. Free and Trader tier responses have factors and adjustments stripped. Returns 403 if the decision belongs to a different API key.

Example Response (Pro)

JSON

{
  "id": 318,
  "symbol": "BTC",
  "side": "long",
  "strategy_id": "ema_crossover",
  "decision": "CONFIRM",
  "confidence": "HIGH",
  "composite": 0.74,
  "size_mult": 1.5,
  "factors": {
    "derivatives": { "score": 0.81, "weight": 0.40, "weighted": 0.324 },
    "onchain": { "score": 0.68, "weight": 0.35, "weighted": 0.238 },
    "whale": { "score": 0.73, "weight": 0.25, "weighted": 0.183 }
  },
  "ts": 1710940821,
  "resolved": false,
  "outcome": null
}

POST /v1/shadow-gate/decisions/{id}/resolve

Manually resolve a decision's outcome. Call this after closing the trade to record the final result against the ledger row. Once resolved, the row is immutable and cannot be changed again.

Request Body

Field	Type	Description
outcomerequired	string	Trade outcome: `win` or `loss`
exit_priceoptional	float	Exit price for the trade. Stored for reference; used to compute P&L % if provided.
pnl_pctoptional	float	Realized P&L as a percentage of position size, e.g. `3.5` or `-1.2`

Example Response

JSON

{
  "id": 318,
  "resolved": true,
  "outcome": "win",
  "exit_price": 65800.0,
  "pnl_pct": 4.1,
  "resolved_at": 1711027200
}

Immutability. The ledger row is append-only. Once a decision is submitted it cannot be deleted, and once resolved it cannot be re-resolved. This ensures the track record you build is honest and tamper-evident.

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
print(data["size_mult"]) # 1.5 / 1.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"] not in ["HIGH", "MEDIUM"]:
  print("Skipping — insufficient confidence")
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") in ["HIGH", "MEDIUM"]
    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"] not in ["HIGH", "MEDIUM"]:
    print(f"Skipping {symbol} {side} — insufficient confidence.")
    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