# Crypto Smart-Money vs Retail Positioning API > How crypto's biggest, most-capitalised futures traders are positioned versus the retail crowd — and the divergence between them — computed live from Binance's public futures positioning feed (no key, nothing stored). Binance splits its perpetual traders into the whole crowd and the "top traders" (the top ~20% of accounts by margin balance, a smart-money proxy) and publishes the long/short split of each. When smart money leans one way while the crowd leans the other, that gap is a classic contrarian signal: an over-long retail crowd the big accounts are quietly fading often marks a local top, and vice versa. The positioning endpoint returns, for a coin, the long/short ratio and long-share of three cohorts side by side — the global crowd, the top traders by account, and the top traders by position size. The divergence endpoint returns the smart-money-minus-retail gap with a plain-language read. The history endpoint returns the time-series across 5m to 1d buckets so you can watch the gap open and close. The smart-money-versus-retail / positioning-divergence cut for crypto — distinct from the single-cohort long/short-ratio feed, the funding-rate, open-interest and price APIs. It tells you who is on which side, not just how many are long. ## Authentication All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys. ```bash curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/smartmoney-api/..." ``` ## Pricing - **Free** (Free) — 750 calls/Mo, 2 req/s - **Starter** ($12/Mo) — 20,000 calls/Mo, 6 req/s - **Pro** ($36/Mo) — 95,000 calls/Mo, 18 req/s - **Business** ($83/Mo) — 500,000 calls/Mo, 45 req/s ## Endpoints ### Positioning #### `GET /v1/positioning` — Three positioning cohorts side by side with the divergence **Parameters:** - `coin` (query, optional, string) — Base coin (quote defaults to USDT) Example: `BTC` - `symbol` (query, optional, string) — Full USDT-perp symbol Example: `BTCUSDT` - `period` (query, optional, string) — Bucket: 5m,15m,30m,1h,2h,4h,6h,12h,1d Example: `5m` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/smartmoney-api/v1/positioning?coin=BTC&symbol=BTCUSDT&period=5m" ``` **Response:** ```json { "data": { "note": "Three positioning cohorts from Binance futures, latest reading. retail_crowd is every account; top_traders_* are the top ~20% of accounts by margin balance (smart-money proxy), by account count and by position size. long_account_pct is the share positioned long. The divergence between top_traders_by_position and retail_crowd is the contrarian signal.", "period": "5m", "source": "Binance USDS-M futures", "symbol": "BTCUSDT", "cohorts": [ { "label": "Global crowd (by accounts)", "cohort": "retail_crowd", "timestamp": 1781260200000, "is_smart_money": false, "long_account_pct": 60.2, "long_short_ratio": 1.5126, "short_account_pct": 39.8 }, { "label": "Top traders (by accounts)", "cohort": "top_traders_by_accounts", "timestamp": 1781260200000, "is_smart_money": true, "long_account_pct": 62.15, "long_short_ratio": 1.642, "short_account_pct": 37.85 }, { "label": "Top traders (by position size)", "cohort": "top_traders_by_position", "timestamp": 1781260200000, "is_smart_money": true, "long_account_pct": 54.79, "long_short_ratio": 1.2117, …(truncated, see openapi.json for full schema) ``` ### Divergence #### `GET /v1/divergence` — Smart-money-minus-retail long-share gap with a contrarian read **Parameters:** - `coin` (query, optional, string) — Base coin Example: `ETH` - `period` (query, optional, string) — Bucket Example: `1h` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/smartmoney-api/v1/divergence?coin=ETH&period=1h" ``` **Response:** ```json { "data": { "note": "long_pct_gap = top-trader long-share minus crowd long-share (positive = smart money more long than the crowd). A large positive gap is a bullish tilt; a large negative gap (crowd over-long) is a contrarian bearish tilt. Threshold +/-8 percentage points. Not financial advice.", "read": "The crowd is notably more long than the top traders — a contrarian bearish tilt (retail euphoria the big accounts are fading).", "period": "1h", "signal": "crowd_over_long", "source": "Binance USDS-M futures", "symbol": "ETHUSDT", "ratio_gap": -0.6704, "long_pct_gap": -10.21, "retail_long_pct": 65.75, "smart_money_long_pct": 55.54 }, "meta": { "timestamp": "2026-06-12T10:35:27.594Z", "request_id": "668c2ac8-7574-40b3-bf19-a1f896be3ed2" }, "status": "ok", "message": "Divergence retrieved successfully", "success": true } ``` ### History #### `GET /v1/history` — Time-series of all three cohorts and the gap **Parameters:** - `coin` (query, optional, string) — Base coin Example: `BTC` - `period` (query, optional, string) — Bucket Example: `1h` - `limit` (query, optional, string) — Points 1-500 Example: `48` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/smartmoney-api/v1/history?coin=BTC&period=1h&limit=48" ``` **Response:** ```json { "data": { "note": "Time-series of all three positioning cohorts and the smart-money-minus-retail long-share gap, oldest to newest. Watch long_pct_gap open and close to see smart money and the crowd diverge and re-converge.", "count": 48, "period": "1h", "points": [ { "timestamp": 1781089200000, "long_pct_gap": -14.09, "retail_crowd_long_pct": 67.98, "retail_crowd_ls_ratio": 2.123, "top_traders_by_accounts_long_pct": 68.86, "top_traders_by_accounts_ls_ratio": 2.2113, "top_traders_by_position_long_pct": 53.89, "top_traders_by_position_ls_ratio": 1.1686 }, { "timestamp": 1781092800000, "long_pct_gap": -14.13, "retail_crowd_long_pct": 68.14, "retail_crowd_ls_ratio": 2.1387, "top_traders_by_accounts_long_pct": 69.08, "top_traders_by_accounts_ls_ratio": 2.2342, "top_traders_by_position_long_pct": 54.01, "top_traders_by_position_ls_ratio": 1.1742 }, { "timestamp": 1781096400000, "long_pct_gap": -14.29, "retail_crowd_long_pct": 67.72, "retail_crowd_ls_ratio": 2.0979, "top_traders_by_accounts_long_pct": 68.59, "top_traders_by_accounts_ls_ratio …(truncated, see openapi.json for full schema) ``` ### Meta #### `GET /v1/meta` — Service metadata **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/smartmoney-api/v1/meta" ``` **Response:** ```json { "data": { "note": "symbol is a USDT perpetual (BTCUSDT) or a base (BTC, default quote USDT). period is 5m-1d (default 5m). history limit is 1-500 (default 48). Read fresh per call, nothing cached.", "source": "Binance USDS-M futures data (globalLongShortAccountRatio, topLongShortAccountRatio, topLongShortPositionRatio), live", "periods": [ "5m", "15m", "30m", "1h", "2h", "4h", "6h", "12h", "1d" ], "service": "smartmoney-api", "endpoints": { "GET /v1/meta": "This document.", "GET /v1/history": "Time-series of all three cohorts and the gap (symbol=BTCUSDT, period=1h, limit=48).", "GET /v1/divergence": "Smart-money-minus-retail long-share gap with a contrarian read (symbol=BTCUSDT).", "GET /v1/positioning": "Three positioning cohorts side by side with the divergence (symbol=BTCUSDT, period=5m)." }, "description": "Crypto smart-money vs retail positioning — how Binance's top traders (top ~20% of accounts by margin) are positioned versus the retail crowd, and the divergence between them, live (no key, nothing stored). positioning returns the long/short ratio and long-share of three cohorts side by side. divergence returns the smart-money-minus-retail gap with a contrarian read. history returns the time-series. The positioning-divergence / smart-money-versus …(truncated, see openapi.json for full schema) ``` --- Marketplace page: https://www.oanor.com/api/smartmoney-api OpenAPI spec: https://www.oanor.com/api/smartmoney-api/openapi.json