# 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"
```

### 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"
```

### 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"
```

### Meta

#### `GET /v1/meta` — Service metadata

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/smartmoney-api/v1/meta"
```


---
Marketplace page: https://www.oanor.com/api/smartmoney-api
OpenAPI spec: https://www.oanor.com/api/smartmoney-api/openapi.json