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

# Tracker

> Full trading profile for one wallet over a period, with period stats, win rate distribution, active and historical tokens, a realized PnL chart and recent trades.

The deepest view of a single wallet. For a chosen period it returns the wallet profile, aggregate period statistics, a win rate distribution across profit buckets, the tokens it is actively holding, the tokens it fully traded through, a realized PnL chart over time, and the most recent individual trades.

Use it to build a wallet detail page in your terminal, a KOL profile card, or a copytrade research view. All data is served from a permanently cached, WebSocket driven store.

<Tip>
  Choose the window with period, one of 6h, 1d, 7d or 30d. The profile aggregates only trades inside that window, while lifetime figures where present cover the whole history.
</Tip>

## Query Parameters

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

<ParamField query="address" type="string" required>
  The wallet address to profile.
</ParamField>

<ParamField query="period" default="1d" type="string">
  Aggregation window, one of 6h, 1d, 7d or 30d.
</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/wallets/tracker?blockchain=solana&address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW&period=7d&api_key=YOUR_KEY"
  ```

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

  params = {
      "blockchain": "solana",
      "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "period": "7d",
      "api_key": "YOUR_KEY",
  }
  r = requests.get("https://api.cabalspy.xyz/v1/wallets/tracker", params=params)
  d = r.json()["data"]

  ps = d["period_stats"]
  print(d["profile"]["name"], "realized pnl", ps["realized_pnl"], d["profile"]["currency"])
  print("active tokens", d["period_active_tokens"]["active_tokens_count"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana",
    address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    period: "7d",
    api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/wallets/tracker?${p}`);
  const { data } = await res.json();
  console.log(data.profile.name, "pnl", data.period_stats.realized_pnl);
  ```
</CodeGroup>

## Response

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

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="wallet" type="string">
      The profiled wallet address.
    </ResponseField>

    <ResponseField name="profile" type="object">
      <Expandable title="profile">
        <ResponseField name="name" type="string">
          Display name (may be empty).
        </ResponseField>

        <ResponseField name="image_url" type="string">
          Avatar URL.
        </ResponseField>

        <ResponseField name="twitter" type="string">
          Twitter or X link.
        </ResponseField>

        <ResponseField name="telegram" type="string">
          Telegram link.
        </ResponseField>

        <ResponseField name="blockchain" type="string">
          Chain.
        </ResponseField>

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

        <ResponseField name="type" type="string">
          Wallet type kol, smart or whale.
        </ResponseField>

        <ResponseField name="active_hours" type="array">
          Hours of day when the wallet is most active.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_stats" type="object">
      <Expandable title="period_stats">
        <ResponseField name="period" type="string">
          The requested window.
        </ResponseField>

        <ResponseField name="total_buy" type="number">
          Buy volume in the period (native).
        </ResponseField>

        <ResponseField name="total_buy_usd" type="number">
          Buy volume in USD.
        </ResponseField>

        <ResponseField name="total_sell" type="number">
          Sell volume in the period (native).
        </ResponseField>

        <ResponseField name="total_sell_usd" type="number">
          Sell volume in USD.
        </ResponseField>

        <ResponseField name="volume" type="number">
          Buy plus sell volume (native).
        </ResponseField>

        <ResponseField name="volume_usd" type="number">
          Buy plus sell volume in USD.
        </ResponseField>

        <ResponseField name="realized_pnl" type="number">
          Realized PnL in the period (native).
        </ResponseField>

        <ResponseField name="realized_pnl_usd" type="number">
          Realized PnL in USD.
        </ResponseField>

        <ResponseField name="realized_pnl_percentage" type="number">
          Realized PnL as a percentage.
        </ResponseField>

        <ResponseField name="buy_txn" type="integer">
          Number of buys.
        </ResponseField>

        <ResponseField name="sell_txn" type="integer">
          Number of sells.
        </ResponseField>

        <ResponseField name="largest_buy" type="number">
          Largest single buy in the period (native).
        </ResponseField>

        <ResponseField name="best_trade_pnl" type="number">
          Best single trade realized PnL.
        </ResponseField>

        <ResponseField name="worst_trade_pnl" type="number">
          Worst single trade realized PnL.
        </ResponseField>

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

        <ResponseField name="loss_count" type="integer">
          Losing closed positions.
        </ResponseField>

        <ResponseField name="avg_hold_time_minutes" type="number">
          Average holding time in minutes.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_win_rate_distribution" type="object">
      <Expandable title="period_win_rate_distribution">
        <ResponseField name="win_rate" type="integer">
          Number of winning positions.
        </ResponseField>

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

        <ResponseField name="above_500" type="integer">
          Positions with more than 500 percent gain.
        </ResponseField>

        <ResponseField name="above_100_to_500" type="integer">
          Positions with 100 to 500 percent gain.
        </ResponseField>

        <ResponseField name="above_zero_to_100" type="integer">
          Positions with 0 to 100 percent gain.
        </ResponseField>

        <ResponseField name="below_zero" type="integer">
          Losing positions.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_active_tokens" type="object">
      <Expandable title="period_active_tokens">
        <ResponseField name="active_tokens_count" type="integer">
          Number of tokens still held.
        </ResponseField>

        <ResponseField name="avg_position_size" type="number">
          Average position size (native).
        </ResponseField>

        <ResponseField name="still_holding_count" type="integer">
          Number of positions still open.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_active_tokens_list" type="array">
      <Expandable title="active token">
        <ResponseField name="token_name" type="string">
          Token name.
        </ResponseField>

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

        <ResponseField name="buy_value_usd" type="number">
          Total bought in USD.
        </ResponseField>

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

        <ResponseField name="sell_value_usd" type="number">
          Total sold in USD.
        </ResponseField>

        <ResponseField name="buy_tokens" type="number">
          Tokens bought.
        </ResponseField>

        <ResponseField name="sell_tokens" type="number">
          Tokens sold.
        </ResponseField>

        <ResponseField name="remaining_tokens" type="number">
          Tokens still held.
        </ResponseField>

        <ResponseField name="realized_pnl" type="number">
          Realized PnL on this token (native).
        </ResponseField>

        <ResponseField name="realized_pnl_usd" type="number">
          Realized PnL in USD.
        </ResponseField>

        <ResponseField name="realized_pnl_percentage" type="number">
          Realized PnL percentage.
        </ResponseField>

        <ResponseField name="bag_pct" type="number">
          Percent of peak holding still held.
        </ResponseField>

        <ResponseField name="supply_pct" type="number">
          Percent of total supply held.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_history_tokens" type="array">
      <Expandable title="history token">
        <ResponseField name="token_name" type="string">
          Token name.
        </ResponseField>

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

        <ResponseField name="buy_value_usd" type="number">
          Total bought in USD.
        </ResponseField>

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

        <ResponseField name="sell_value_usd" type="number">
          Total sold in USD.
        </ResponseField>

        <ResponseField name="buy_tokens" type="number">
          Tokens bought.
        </ResponseField>

        <ResponseField name="sell_tokens" type="number">
          Tokens sold.
        </ResponseField>

        <ResponseField name="realized_pnl" type="number">
          Realized PnL on this token (native).
        </ResponseField>

        <ResponseField name="realized_pnl_usd" type="number">
          Realized PnL in USD.
        </ResponseField>

        <ResponseField name="realized_pnl_percentage" type="number">
          Realized PnL percentage.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_realized_pnl_chart" type="array">
      <Expandable title="chart point">
        <ResponseField name="timestamp" type="string">
          ISO timestamp of the snapshot.
        </ResponseField>

        <ResponseField name="realized_pnl" type="number">
          Cumulative realized PnL at that point (native).
        </ResponseField>

        <ResponseField name="realized_pnl_usd" type="number">
          Cumulative realized PnL in USD.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_trades" type="array">
      <Expandable title="trade">
        <ResponseField name="signature" type="string">
          Transaction signature.
        </ResponseField>

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

        <ResponseField name="token_symbol" type="string">
          Token symbol.
        </ResponseField>

        <ResponseField name="transaction_type" type="string">
          buy or sell.
        </ResponseField>

        <ResponseField name="value" type="number">
          Trade value (native).
        </ResponseField>

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

        <ResponseField name="wallet_type" type="string">
          kol, smart or whale.
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO timestamp of the trade.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "profile": {
        "name": "Maze",
        "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
        "twitter": "https://x.com/MazeCCC",
        "telegram": "",
        "blockchain": "solana",
        "currency": "SOL",
        "type": "kol",
        "active_hours": [13, 14, 15, 20, 21]
      },
      "period_stats": {
        "period": "7d",
        "total_buy": 180.25,
        "total_buy_usd": 14840.6,
        "total_sell": 132.25,
        "total_sell_usd": 10890.65,
        "volume": 312.5,
        "volume_usd": 25731.25,
        "realized_pnl": 48.2,
        "realized_pnl_usd": 3968.6,
        "realized_pnl_percentage": 26.74,
        "buy_txn": 22,
        "sell_txn": 18,
        "largest_buy": 22.0,
        "best_trade_pnl": 31.4,
        "worst_trade_pnl": -8.9,
        "win_count": 14,
        "loss_count": 4,
        "avg_hold_time_minutes": 84.5
      },
      "period_win_rate_distribution": {
        "win_rate": 14,
        "win_rate_percentage": 77.78,
        "above_500": 1,
        "above_100_to_500": 4,
        "above_zero_to_100": 9,
        "below_zero": 4
      },
      "period_active_tokens": {
        "active_tokens_count": 3,
        "avg_position_size": 4.12,
        "still_holding_count": 3
      },
      "period_active_tokens_list": [
        {
          "token_name": "invisibull",
          "buy_value": 1.66,
          "buy_value_usd": 137.44,
          "sell_value": 0.0,
          "sell_value_usd": 0.0,
          "buy_tokens": 22113972.03,
          "sell_tokens": 0.0,
          "remaining_tokens": 22113972.03,
          "realized_pnl": -1.66,
          "realized_pnl_usd": -137.44,
          "realized_pnl_percentage": -100.0,
          "bag_pct": 100.0,
          "supply_pct": 2.21
        }
      ],
      "period_history_tokens": [
        {
          "token_name": "Pengu",
          "buy_value": 1.48,
          "buy_value_usd": 121.98,
          "sell_value": 1.15,
          "sell_value_usd": 95.46,
          "buy_tokens": 266294.3,
          "sell_tokens": 266294.3,
          "realized_pnl": -0.32,
          "realized_pnl_usd": -26.52,
          "realized_pnl_percentage": -21.62
        }
      ],
      "period_realized_pnl_chart": [
        { "timestamp": "2026-07-01T00:00:00Z", "realized_pnl": 12.4, "realized_pnl_usd": 1020.6 },
        { "timestamp": "2026-07-04T00:00:00Z", "realized_pnl": 48.2, "realized_pnl_usd": 3968.6 }
      ],
      "period_trades": [
        {
          "signature": "5xr8...",
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "token_symbol": "invisibull",
          "transaction_type": "buy",
          "value": 1.66,
          "currency": "SOL",
          "wallet_type": "kol",
          "created_at": "2026-07-04T16:25:34Z"
        }
      ]
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": true,
      "cache_age_seconds": 42,
      "version": "1.0.0",
      "timestamp": "2026-07-06T11:01:57Z"
    }
  }
  ```
</ResponseExample>

## Errors

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