Aggregate and elite-trader long/short positioning ratios — the classic contrarian feed.

Retail long/short ratios tell you where the crowd is positioned; top-trader ratios tell you where the smart money sits. When they diverge, that's tradeable information. The `type` parameter picks which ratio flavour you want. Pass a `coin` and you also get that coin's history so you can chart the ratio over time.

Query parameters

All query parameters are optional unless marked required.

Response shape

Always wrapped in the standard envelope. Nullable fields are explicitly marked — treat missing numeric data as a real data-source gap, not as an error.

// Wrapped in the standard envelope:
// {
//   data: /* shape below */,
//   meta?: { total?: number; limit?: number; offset?: number; ... }
// }

{
  type: "global_account" | "top_trader_position" | "top_trader_account"
      | "elite_position" | "taker_volume";
  summary: {
    avgRatio: number;
    bullish: number;     // count of ratios > 1
    bearish: number;     // count of ratios < 1
  };
  latest: Array<{
    coin: string;
    ratio: number;
    longPct: number;
    shortPct: number;
    ts: number;
  }>;
  history?: Array<{ ts: number; ratio: number; longPct: number; shortPct: number }>;
}

Example

Copy the curl, replace YOUR_KEY with a real key from your dashboard, and run.

curl -sS "http://localhost:3000/api/v1/long-short?type=top_trader_position&coin=BTC" \
  -H "Authorization: Bearer cg_live_YOUR_KEY"

{
  "data": {
    "type": "top_trader_position",
    "summary": { "avgRatio": 1.12, "bullish": 34, "bearish": 16 },
    "latest": [
      { "coin": "BTC", "ratio": 1.27, "longPct": 55.9, "shortPct": 44.1, "ts": 1744835000000 },
      { "coin": "ETH", "ratio": 0.92, "longPct": 47.9, "shortPct": 52.1, "ts": 1744835000000 }
    ],
    "history": [
      { "ts": 1744748600000, "ratio": 1.18, "longPct": 54.1, "shortPct": 45.9 }
    ]
  },
  "meta": { "total": 2, "limit": 50, "historyPoints": 1 }
}

Notes

• `top_trader_position` weights by position size; `top_trader_account` by headcount — they disagree often.
• Elite position is a narrower sample than top-trader. Expect sparser history.