> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Aggregate analytics over tracked wallets for a period, including most traded tokens, top performing wallets, win rate stats and volume trends.

Aggregate analytics over tracked wallets for a period. Four modes cover different questions, which tokens are most traded, which wallets perform best, what the win rate looks like, and how volume trends over time.

Use it to build dashboards and leaderboards, for example a most traded tokens this week widget or a top performers table.

<Tip>
  Choose the view with mode. All modes share the same wrapper (mode, blockchain, type, period, currency) and differ in the data they return. Set the window with period, one of 6h, 1d, 7d or 30d.
</Tip>

## Query Parameters

<ParamField query="blockchain" type="string" required>
  Chain. One of solana, bnb, base, eth.
</ParamField>

<ParamField query="type" type="string" required>
  Wallet category kol, smart or whale.
</ParamField>

<ParamField query="mode" type="string" required>
  Analytics view. One of most\_traded, top\_performers, win\_rate, volume\_trend.
</ParamField>

<ParamField query="period" default="7d" type="string">
  Aggregation window, one of 6h, 1d, 7d or 30d.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of items to return, for list modes.
</ParamField>

<ParamField query="api_key" type="string" required>
  Your API key. Alternatively pass it as an Authorization Bearer header.
</ParamField>

## Usage Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.cabalspy.xyz/v1/analytics?blockchain=solana&type=kol&mode=most_traded&period=7d&limit=20&api_key=YOUR_KEY"
  ```

  ```python Python theme={null}
  import requests

  params = {
      "blockchain": "solana", "type": "kol", "mode": "most_traded",
      "period": "7d", "limit": 20, "api_key": "YOUR_KEY",
  }
  r = requests.get("https://api.cabalspy.xyz/v1/analytics", params=params)

  for t in r.json()["data"]["data"]:
      print(t["rank"], t["token_name"], "wallets", t["wallet_count"], "vol", t["total_volume"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana", type: "kol", mode: "most_traded",
    period: "7d", limit: "20", api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/analytics?${p}`);
  const { data } = await res.json();
  data.data.forEach(t => console.log(t.rank, t.token_name, t.total_volume));
  ```
</CodeGroup>

## Response

All modes return the same wrapper. The list modes (most\_traded, top\_performers) put their items in a data array. win\_rate returns summary fields directly. The sections below describe each mode.

<ResponseField name="success" type="boolean">
  True on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data (common wrapper)">
    <ResponseField name="mode" type="string">
      The requested mode.
    </ResponseField>

    <ResponseField name="blockchain" type="string">
      Requested chain.
    </ResponseField>

    <ResponseField name="type" type="string">
      Requested wallet type.
    </ResponseField>

    <ResponseField name="period" type="string">
      Aggregation window.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Native currency.
    </ResponseField>

    <ResponseField name="data" type="array">
      Present for most\_traded and top\_performers. Items described below.
    </ResponseField>
  </Expandable>
</ResponseField>

### most\_traded item

<ResponseField name="rank" type="integer">
  Rank in the list.
</ResponseField>

<ResponseField name="mint" type="string">
  Token mint.
</ResponseField>

<ResponseField name="token_name" type="string">
  Token name.
</ResponseField>

<ResponseField name="wallet_count" type="integer">
  Number of tracked wallets that traded the token.
</ResponseField>

<ResponseField name="total_volume" type="number">
  Total volume (native).
</ResponseField>

<ResponseField name="total_buy" type="number">
  Total bought (native).
</ResponseField>

<ResponseField name="total_sell" type="number">
  Total sold (native).
</ResponseField>

<ResponseField name="net_flow" type="number">
  Buy minus sell (native).
</ResponseField>

<ResponseField name="buying_pressure" type="number">
  Buy share of volume.
</ResponseField>

<ResponseField name="currency" type="string">
  Native currency.
</ResponseField>

<ResponseField name="first_buy_at" type="string">
  When the first tracked buy happened.
</ResponseField>

### top\_performers item

<ResponseField name="profile" type="object">
  Wallet profile.
</ResponseField>

<ResponseField name="period_stats" type="object">
  Period statistics for the wallet (period, currency, total\_buy, total\_buy\_usd, total\_sell, total\_sell\_usd, total\_volume, total\_volume\_usd, realized\_pnl, realized\_pnl\_usd and related fields).
</ResponseField>

### win\_rate fields

For win\_rate the wrapper carries the summary directly instead of a data array.

<ResponseField name="total_wallets" type="integer">
  Total wallets considered.
</ResponseField>

<ResponseField name="wallets_with_trades" type="integer">
  Wallets that traded in the period.
</ResponseField>

<ResponseField name="win_count" type="integer">
  Winning closed positions.
</ResponseField>

<ResponseField name="closed_count" type="integer">
  Total closed positions.
</ResponseField>

<ResponseField name="win_rate_percentage" type="number">
  Win rate as a percentage.
</ResponseField>

<ResponseField name="distribution" type="object">
  Profit buckets (above\_500, above\_100\_to\_500, above\_zero\_to\_100, below\_zero).
</ResponseField>

### volume\_trend

For volume\_trend the data array holds time bucketed volume points over the period.

<ResponseExample>
  ```json Response (most_traded) theme={null}
  {
    "success": true,
    "data": {
      "mode": "most_traded",
      "blockchain": "solana",
      "type": "kol",
      "period": "7d",
      "currency": "SOL",
      "data": [
        {
          "rank": 1,
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "token_name": "invisibull",
          "wallet_count": 12,
          "total_volume": 312.5,
          "total_buy": 180.25,
          "total_sell": 132.25,
          "net_flow": 48.0,
          "buying_pressure": 57.6,
          "currency": "SOL",
          "first_buy_at": "2026-07-01T09:58:00Z"
        }
      ]
    },
    "pagination": { "limit": 20, "total": 1, "has_more": false, "next_cursor": null },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:01:57Z"
    }
  }
  ```

  ```json Response (win_rate) theme={null}
  {
    "success": true,
    "data": {
      "mode": "win_rate",
      "blockchain": "solana",
      "type": "kol",
      "period": "7d",
      "currency": "SOL",
      "total_wallets": 342,
      "wallets_with_trades": 210,
      "win_count": 1240,
      "closed_count": 2010,
      "win_rate_percentage": 61.69,
      "distribution": {
        "above_500": 42,
        "above_100_to_500": 310,
        "above_zero_to_100": 888,
        "below_zero": 770
      }
    },
    "meta": {
      "request_id": "req_9aa1917e433b",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:02:10Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code               | Meaning                                              |
| ------ | ------------------ | ---------------------------------------------------- |
| 400    | invalid\_parameter | blockchain, type, mode or period missing or invalid. |
| 401    | unauthorized       | API key missing.                                     |
| 403    | forbidden          | API key invalid or credits exhausted.                |
| 429    | rate\_limited      | Rate limit exceeded.                                 |