Crypto Liquidation & Funding 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.

Public repositories

Two repositories are public on GitHub. Neither needs an account or a key to read. They exist so that you — or a coding agent working on your behalf — can point tooling at a machine-readable contract, generate a client in whatever language you actually write in, and see exactly what each endpoint returns before paying for a key.

Which copy is authoritative. The spec served at api.smartmoneyapi.com/openapi.json is regenerated from the router and is always current — it cannot fall behind the code without failing CI. The GitHub copy is a published snapshot: it is updated deliberately, so between updates it can lag. If the two ever disagree, the live document is the correct one. Build against the live URL when you can fetch it at build time, and use the repository when you want a pinned, reviewable file in version control.

Quickstart in 2 minutes

Step 0 — Call it right now, with no key. A large part of the API is public: derivatives, whales, on-chain, options, ETF flows, market indices and news all answer without authentication. Run one here before you decide whether any of this is worth a signup.

Or skip the hand-rolling. The OpenAPI spec generates a client in any language, and the official Python client and docs repository are public on GitHub — no account, no key needed to read either.

Step 1 — Base URL. Every endpoint lives under:

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:

Expected response:

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

Not every request needs a key. The public data endpoints — derivatives screener, whale crowding and events, on-chain metrics, options, ETF flows, market indices, DEX and news — answer anonymously. Keyless traffic is rate-limited per client IP and per route; the threshold is not published and may change without notice, so treat the 429 as the signal rather than planning against a number. Everything else (confirmation, exports, alerts, websockets, per-account state) requires an API key passed as the X-API-Key HTTP header. Which of the two paths you want, and what each one actually gets you, is set out in Keyless access vs a free key.

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.

Keyless access vs a free key

A large part of this API answers with no key at all. That path is real and supported, and it is documented here rather than left implicit — an undocumented free path is one nobody can plan against, and it is how “just scrape it anonymously” quietly became a reasonable-looking strategy.

What works with no key

The public market-data families: the derivatives screener, funding heatmap and OI rankings; options chain, PCR and GEX; ETF flows; market indices and dominance; on-chain metrics, TVL, stablecoins and gas; DEX screener; whale events, summary, crowding and consensus; the liquidation heatmap, symbol inventory, simulator and aftermath study; COT, seasonality, technicals, mood, rankings and the news feeds. Where a paid view of the same path exists, the keyless response is the truncated one — /v1/derivatives/screener returns the top 10 rows, not the full table.

What does not work with no key

/v1/confirm, the shadow-gate decision ledger, whale alerts, usage, exports, every WebSocket and every per-account endpoint return 401 without a key. There is no keyless route to any of them. That now includes the last stream that used to answer without one: /v1/stream/public-swaps requires a credential like everything else — see below. A free key is enough; there is no paid tier gate on it.

How keyless is limited

Keyless calls are throttled per client IP and per route, and the limit is enforced independently of any plan. The exact threshold is not published and is subject to change without notice. Build for the rejection, not for a number: back off on 429 on a schedule of your own. Keyless traffic is also not attributed to any account — it does not appear in /v1/usage, on a dashboard, or in anything support can look up on your behalf.

What a free key adds

Every figure in the Free column is read at page load from plans.json via plans.js, the same manifest the server enforces. If a cell renders blank, the manifest could not be read — that is a failure, not an offer.

What Trader adds over a free key

All tracked symbols instead of five; 3,000 calls/day at 30/min; the unstripped /v1/confirm evidence block (reasons, details, deriv_score, onchain_score, whale_score); and the Trader endpoint set — snapshot, whales and whale events, liquidations, smart-stop, funding-arb, the full derivatives screener beyond the public top 10, the DeFiLlama suite, exports, the research capture and the symbol-universe coverage views. See pricing for the full comparison.

On streaming, Trader is not “WebSocket instead of no WebSocket” — Free has a socket too. What Trader adds is more channels and a larger allowance; the exact figures are in Per-plan allowance, read from the manifest.

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.

Request Body

This section previously carried a hand-written example response naming a synced field the endpoint does not return. It was removed rather than corrected, because the docs build cannot call this endpoint to capture a real one. The response shape is defined by /openapi.json, which is generated from the server source on every build and therefore cannot drift.

Rate Limits

Every plan number above is read at page load from plans.json — the same manifest the gateway enforces — through the generated plans.js. The anonymous row is deliberately unquantified: keyless throttling exists to stop sustained scraping, and a published budget is a scraping target. It is limited, and the limit may change without notice.

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. The daily cap resets at 00:00 UTC.

Base URL

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:

Every error returns the same shape:

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:

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:

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 — derivatives markets for funding, OI and liquidation data, and whale tracking covers — 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

Example Request

Example Response

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.

Delta Ingestion

If you are polling on a schedule, do not re-download data you already have. Two mechanisms cover the two kinds of endpoint, and both are available on every tier including free.

1. Cursors — for append-only feeds

Feeds return a max_id alongside the data. Pass it back as since_id on the next request and you receive only what has been recorded since. Ids are monotonic, so nothing is skipped or repeated.

2. ETags — for snapshots

Snapshot endpoints replace their whole payload each refresh, so a cursor makes no sense. They carry an ETag instead. Send it back as If-None-Match and you get 304 Not Modified with an empty body while the data is unchanged.

The derivatives screener refreshes about every two minutes and advertises this in an X-Refresh-After header. A client polling it every ten seconds transfers a body once per cycle instead of twelve times.

Response Fields

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.

GET  /onchain

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

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 price/market-cap/volume (CoinGecko) for backtesting. Endpoints: /v1/historical/funding, /v1/historical/open-interest, /v1/historical/long-short, /v1/historical/market. Symbols for the first three are Binance pair ids (e.g. BTCUSDT), case-sensitive — a plain BTC or lowercase pair answers count: 0 with HTTP 200, not an error.

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.

GET  /signals

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

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).

GET  /health

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

GET  /usage

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

POST  /webhooks

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

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

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

This section previously carried a hand-written example response containing an LLM narrative that was never generated, plus a ts field this endpoint never emits. It was removed. The model fills regime, regime_label, summary, signal_conflicts, risk_factors, recommendation and time_horizon; the server then adds symbol, generated_at, generated_at_unix, generation_time_ms and ai_backend. The response shape is defined by /openapi.json, which is generated from the server source on every build and therefore cannot drift.

GET  /liquidations

Two different things in one payload. (1) A modelled ladder of where leveraged positions would liquidate — longs and shorts — built from measured open interest, an average leverage inferred from funding, and the liquidation prices of tracked Hyperliquid wallets. (2) realized_heatmap — what actually liquidated, aggregated live from public exchange WebSocket feeds: Binance, OKX, Bybit, Bitget, BitMEX (absent in a very calm market or just after startup).

Parameters

Response fields

The Plans column is the whole tier boundary for this endpoint. It is checked against api_gateway._handle_liquidations on every build — if the reshape changes and this table does not, the build fails rather than this page going quietly false.

What each plan receives

Example Response

Not an illustration — this is the response this endpoint actually returned for ?symbol=BTC on a Trader key, captured 2026-08-28, with the two ladders at their real length of 5 and 5. Only the nearest level of each is printed here (the … stands for the other 4 and 4) — every other value is verbatim. A Pro response is the same document with the full ladders, the three nearest_* qualifier fields, the whole realized_heatmap in place of realized_totals/realized_by_side, and no withheld block.

GET  /liquidations/heatmap

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

Response fields you must read before drawing a conclusion

Example Response

GET  /liquidations/symbols

Which symbols the liquidation archive actually holds — per-symbol event count, first and last timestamp, total liquidated notional, plus the venue list. Call this before trusting an empty heatmap. /liquidations/heatmap answers for any symbol string you hand it, so a symbol we have never recorded returns exactly the same well-formed empty grid as a symbol that was merely quiet. This endpoint is how you tell those apart.

Parameters

Example Response

GET  /liquidations/onchain

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

Example Response

GET  /smart-stop

Returns a stop price together with the basis it was derived from. stop_basis records whether the recommendation came from a modelled liquidation cluster or from nothing but your own risk_pct with no cluster read at all — two stops that look identical on the wire and mean completely different things. The clusters it may use are the modelled ladder from /liquidations, not an observed order book, and they carry that endpoint’s caveats.

Parameters

Example Response

Not an illustration — this is the response this endpoint actually returned for ?symbol=BTC&direction=long&entry_price=79832.36&risk_pct=2.0 on a Trader key, captured 2026-08-28. Prices move; the shape and the vocabulary do not.

GET  /funding-arb

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

This section previously carried a hand-written example response naming spread, apr and estimated_profit_8h_usd — none of which appears anywhere in the server source. It was removed. The response shape is defined by /openapi.json, which is generated from the server source on every build and therefore cannot drift.

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  /smart-money/flow

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

Example Response

GET  /v1/whales/crowding

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

Example Request

Example Response

GET  /v1/options/gex

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

Example Request

Example Response

Captured from the running API on 2026-08-28 (GET /v1/options/gex?symbol=BTC). profile carries one row per strike; 74 of the 76 rows are elided behind the …. Values move; the field names and the nesting are what this documents.

GET  /v1/liquidations/simulate

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

Example Request

Example Response

GET  /v1/liquidations/aftermath

What price actually did after big liquidation minutes, measured on the retained live tape. An “event” is a 1-minute liquidation-notional bin above that symbol’s 90th percentile and at least $25,000; the side is the dominant liq_side in the bin. Each horizon reports n, mean, median, positive fraction, standard deviation, a 95% confidence interval, a permutation p-value and a plain-language verdict. This is descriptive, not a signal — data_posture says so in every response, and horizons that are indistinguishable from baseline return exactly that verdict rather than being dressed up as an edge.

Parameters

Example Response

GET  /v1/liquidations/aftermath/historical

The same question asked over two years of 4h open-interest and price history, because the live tape is only weeks deep. Takes no parameters — it serves one precomputed study covering every symbol in the dataset, keyed under per_symbol.

Example Response

GET  /v1/wallet/{addr}/profile

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

Example Request

Example Response

GET  /v1/l2/trades

Raw trade prints for one venue over a bounded UTC hour window, read directly from our L2 collector's store. Only venue=hyperliquid returns rows today. We collect a real-time trade tape from 11 exchanges for internal research, but a licence review completed 2026-09-04 found that nine of the ten centralised venues' API terms forbid redistribution or resale of their market data, with no carve-out for derived or aggregated data — see /v1/l2/venues for the full table and the reason per venue. Hyperliquid is the one exception, cleared by an explicit operator decision (it publishes no such restriction in any governing document).

Parameters

Example Request

The exact response shape (row fields, coverage, source_terms) is defined by /openapi.json, generated from the server source on every build.

GET  /v1/l2/venues

Every venue the L2 collector knows, whether it is cleared to reach a paying subscriber, and the reason for the ones that are not — read directly from the collector's own licence table, never a hand-maintained list. Use this to check a venue's status before calling /v1/l2/trades.

GET  /flows

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.

This section previously carried a hand-written example response naming a rotations_detected field that appears nowhere in the server source. It was removed. The response shape is defined by /openapi.json, which is generated from the server source on every build and therefore cannot drift.

GET  /whale-events

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

This section previously carried a hand-written example response whose summary fields (new_opens, closes, flips_to_long, flips_to_short) appear nowhere in the server source. It was removed. The response shape is defined by /openapi.json, which is generated from the server source on every build and therefore cannot drift.

GET  /regimes/history

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

This section previously carried a hand-written example response naming current_regime, regime_summary, avg_duration_h and avg_return_pct — none of which appears anywhere in the server source. It was removed. The response shape is defined by /openapi.json, which is generated from the server source on every build and therefore cannot drift.

GET  /exchange-health

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

Captured from the running API on 2026-08-28 (GET /v1/exchange-health). Values move; the field names and the nesting are what this documents.

GET  /sentiment

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

Example Response

Integrations

GET  /tradingview/setup

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

Abridged: the response also carries secret_returned_once, rotated and created. The Pine source is truncated here; the real payload contains all three scripts in full.

POST  /tradingview/webhook

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

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

Personalization

GET  /preferences

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

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

Preference Fields

GET  /watchlist

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.

This section previously carried a hand-written example response in which watchlist was an array of objects with confidence, action and cascade_risk fields. watchlist is an array of symbol strings; the per-symbol data sits under symbols, keyed by symbol, and each entry carries long_signal, short_signal, long_score, short_score, regime and suggested_long_size_usd. The top level also returns user_id and risk_tolerance. The old example was removed rather than corrected, because the docs build cannot call this endpoint to capture a real one. The response shape is defined by /openapi.json, which is generated from the server source on every build and therefore cannot drift.

Real-time streaming

Streaming is on every plan, including Free, with a per-plan allowance read from the same manifest the gateway enforces. Up to seven channels — swaps, liquidations, funding, whales, signals, orderbook and fills — are multiplexed onto one WebSocket, and every frame carries the channel it came from and the unit of its principal number.

This is a correction of something that was genuinely wrong. Before it shipped, the paid plans carried a websocket flag while the only handler gated on a hard-coded tier list, so a paying Trader was refused in practice; and /v1/stream/public-swaps served the same events keyless, unmetered and uncapped. The anonymous visitor had the better deal than the customer. Both halves are fixed below.

Connecting — mint a ticket, then open the socket

An API key is never accepted in a WebSocket URL. ?key= and ?api_key= are rejected, and a test enforces that they stay rejected — query strings are logged by proxies and load balancers and saved in browser history. Exchange your key for a short-lived, single-use ticket over a normal authenticated POST, then connect with the ticket. Server-side clients that can set request headers may send X-API-Key on the handshake instead.

Response

Minting a ticket spends one from your daily ticket allowance. That is deliberate: a ticket is the only way a browser opens a socket, so metering the mint is what stops a stream of short-lived sockets from dodging the concurrent-connection cap.

GET  /v1/ws/channels

Public on purpose: you can read what streaming exists, which plan carries it, and whether a channel currently has a producer, before paying for it. It publishes the catalogue and channel state — never market data.

Every frame carries its channel and the unit of its principal number. Nothing on the bus is re-normalised: venue_registry is the only normaliser in this system, and these producers publish values it has already normalised.

What each channel does not include

A stream is as much defined by its gaps as by its contents, and a gap you were not told about is one you will average over and publish as market data. So:

Channel state is three-way

An unwired channel is never rendered as “0 events”. /v1/ws/channels and the socket’s hello frame report each channel as one of:

Per-plan allowance

Every figure in this table is read at page load from plans.json — the same manifest the gateway enforces at request time — through the generated plans.js. Nothing here is typed into the page. If a cell renders blank, the manifest could not be read: that is a failure, not an offer. The live values are also on /v1/plans and /v1/ws/channels, and they arrive on your own ticket and hello frame — prefer those to any table.

These are derived, not picked. Frames/day is the plan’s daily REST call budget × 100 — a streamed frame costs roughly a hundredth of a REST call, because there is no per-call key validation and no per-call rate-limit round trip, and one socket is amortised over many frames. Concurrent sockets is the plan’s per-minute burst ÷ 10, floored at one. Connection time per day is concurrent sockets × 24 h on the paid plans: you may hold every socket you are entitled to open for the whole day. Free is the deliberate exception — its connection-time figure is a test allowance, enough to point a client at the socket and watch it work, not enough to run a bot off it. The derivation itself is test-enforced.

Refusals

The socket closes itself with a JSON reason rather than going silent, because a silent socket is indistinguishable from a dead feed.

GET  /v1/stream/public-swaps — requires a free key

This SSE stream used to answer any caller successfully — keyless, unmetered and uncapped — carrying the same swap events as the paid socket. It now requires a credential. A free account key is enough, so nothing here is behind a paywall; what changed is that the anonymous visitor no longer gets a better deal than the customer.

With a credential — a ?ticket=, an X-API-Key header or a bearer token — it is charged against your plan’s streaming allowance exactly like a socket: admission, per-frame, connection seconds, release. Streaming does not become free because the transport is SSE.

Without a credential it now returns 401. Create a free account, generate a key, and use it as an X-API-Key header, a bearer token, or a ?ticket=. The free tier covers this stream.

REST snapshot

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

Swap event schema

Venue coverage — eleven instrument tables, and what is not in them

There is exactly one unit-normalisation layer in this system. Every contract multiplier it applies is sourced from the venue’s own instruments endpoint and is carried on the result together with the exact field it came from, so any normalised figure traces back to (raw value, multiplier, source).

Two production defects are why it exists. OKX sz is always contracts, never base coin — reading BTC-USDT-SWAP size as BTC overstated it 100×, and gold 1000×. A BitMEX inverse volume is contracts where one contract is one US dollar, which read as coin was roughly 78,000× off the venue’s own homeNotional. Neither venue did anything wrong: we read a documented field under an undocumented assumption.

Three rules follow, and they are what you are relying on whenever you read a cross-venue number from this API:

1. A venue whose metadata cannot be read yields MISSING for that instrument — never a guessed multiplier, never a default, never zero. Missing is honest; a wrong multiplier is a fabricated measurement.
2. An aggregate is the sum of normalised values only, and always states which venues contributed and which were missing. An aggregate that hides a missing venue is a lie about coverage, not a rounding error.
3. Nothing guesses a funding interval. It is read per instrument or it is MISSING — a large share of Bybit and Bitget perpetuals settle every 4h, and assuming 8h publishes exactly half the true APR for those instruments.

Eleven requests are made, producing eleven tables (Binance is read twice, because USDⓒ-M and COIN-M are separate APIs), plus two further tables derived from Deribit’s single payload at no extra request.

Declared and excluded, so their absence is never mistaken for a venue that lists nothing:

The “what we do not request” column is the important one. absence_is_conclusive on /v1/symbols/universe/coverage is false for exactly those product lines: a symbol missing there is our fetch gap, not the venue’s answer. Before this distinction existed, every Deribit option and every Bitget COIN-M symbol was reported as “not listed” by a venue that lists it.

Symbol universe

The listing lifecycle across every venue we read. Its whole purpose is to separate “this venue does not list that symbol” from “we never asked that venue for that product line” — different facts, and only the first one is about the venue.

Three properties worth knowing before you build on it:

An empty universe explains itself. If no venue table could be read, total_live is null and universe_state.meaning says the count is unknown. It is never rendered as 0. A genuine zero — every venue readable, none listing a match — says so in the same field, and that zero is a measurement.

Scaled tickers are linked, never merged. 1000PEPE and KPEPE are connected to PEPE as scale_variants with the multiplier stated. No venue publishes that multiplier as a field, so the link is derived — and is labelled as derived. Merging them would silently add two different instruments together.

Delisted symbols are kept in history and are never returned by /v1/symbols/universe. Query /v1/symbols/universe/asset for them.

Free responses are a sample, and say so: the payload carries what was returned, what the total was, and why it was truncated. It is never presented as the whole set.

Metals — gold and silver

Gold and silver are carried as first-class symbols, XAU and XAG, and both are reachable by name on a free key — the free symbol list is BTC, ETH, SOL, XAU, XAG. They flow through the same derivatives path as every crypto symbol: screener, confirm, heatmap, snapshot.

Two further names exist and are deliberately kept apart from these. XAUT and PAXG are perpetuals on tokenised gold — they carry issuer and redemption risk on top of the metal, and they are labelled asset_class: "tokenised_metal" rather than "metal". The symbol-universe layer will never alias PAXG, XAUT or XAUM onto XAU: tokenised gold is not the gold index, and merging them would silently blend two different risks into one series.

Funding on the real settlement clock

Gold and silver settle funding every four hours on both venues that carry them — not eight. This used to matter a great deal and be invisible: annualised funding was computed as rate × 3 × 365, i.e. “8-hourly, always”, which published half the true APR for every 4h instrument. It was not a metals-only defect — measured on 2026-08-29, 424 of 703 Binance USDT perpetuals settle on a 4h clock, so the majority of the table was wrong, gold and silver included.

The settlement interval is a property of the instrument, not the venue, and both venues publish it per instrument. Every row that carries an annualised funding figure now also carries the interval that produced it, so you can check the arithmetic rather than trust it:

History depth, and what a historical row does not yet tell you

Metals history was extended from under a day to roughly thirty days by replaying funding, open interest, long/short, taker flow and price from the venues’ own REST endpoints. Thirty days is a venue ceiling, not a setting on our side — Binance does not serve its /futures/data/* series further back than that, so no amount of re-running deepens it. From here the span grows by observation, one day per day.

Those replayed rows are stored separately from observed ones and are labelled backfilled against observed, with a database constraint that makes it structurally impossible to write a replayed row under the “observed” label. Where both exist for one timestamp, the observed row wins. Two columns are deliberately empty on the Bybit side of the backfill rather than filled: that venue’s account-ratio is a headcount across all accounts, and pouring it into a position-weighted top-trader column would be a different statistic wearing the column’s name.

GET  /v1/cot/*

CFTC Commitment of Traders positioning — the regulator’s own weekly census of who holds the futures, which is the one positioning series in this API that does not come from an exchange API at all. Four public endpoints:

The bucket names depend on the symbol, and you must not hardcode them. The CFTC publishes different market families in different reports, and this API does not flatten that difference away, because flattening it would mean relabelling one category as another:

For the metals, the speculative bucket is managed_money, and the response says so in speculator_category rather than leaving you to infer it. Each bucket carries long, short, net, a human label, and — except for the nonreportable bucket, where the CFTC does not publish it — spreading. Spreading is a real component of open interest and is reported separately rather than being folded into either side.

Research capture

Timestamps are epoch milliseconds, everywhere, verified against every shard. A table reported empty exists in the schema and has no rows in any shard — that is not the same as a table we could not read: a shard that cannot be opened is reported in unreadable_shards with its reason, and its rows are never counted as zero.

Reads run on the research store’s own worker pool rather than the shared executor, so a slow shard scan cannot starve the rest of the gateway. A read that is refused or fails answers 503, never 502 or 504.

POST  /alerts/conditions

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.

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

Permanently removes an alert condition by its ID.

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

Create Alert — Request Body

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

Available Metrics

GET  /kelly

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

This section previously carried a hand-written example response printing half_kelly and avg_reward_risk_ratio, neither of which exists. The real payload is method, win_rate, avg_rr, kelly_fraction, half_kelly_fraction, suggested_size_usd, suggested_pct_of_account, samples — and nothing else: no symbol, no direction, no confidence echo. It was removed. The response shape is defined by /openapi.json, which is generated from the server source on every build and therefore cannot drift.

GET  /performance

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

Parameters

Example Response

Captured from the running API on 2026-08-28 (GET /v1/performance?symbol=BTC&days=30); 14 of the 16 symbols in by_symbol are elided. The buckets count correct / incorrect / neutral, not a win rate. Values move; the field names and the nesting are what this documents.