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

> GET /v1/wallets/tracker: the full trading profile of a verified wallet for a period: stats, realized PnL, win rate distribution, traded tokens, PnL chart and trades.

The deepest view of one verified wallet of your users. For a chosen period it returns the owner's profile, aggregate period statistics, a win rate distribution across profit buckets, the tokens traded, a cumulative realized PnL chart and the individual trades.

The numbers are computed exactly like the CabalSpy API [tracker](/tracker), so a wallet shows the same figures on both APIs. Realized PnL is the cash flow inside the window, sells minus buys.

<Tip>
  Choose the window with period, one of 6h, 1d, 7d or 30d. Windows are rolling, counted back from now. The PnL chart starts at 0 at the beginning of the period and ends at the period's realized PnL, with one point every 15 minutes.
</Tip>

## Query Parameters

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

<ParamField query="address" type="string" required>
  A wallet verified on this chain by one of your users.
</ParamField>

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

<ParamField query="scope" default="instance" type="string">
  `global` allows any CabalSpy ID wallet. Enterprise plan only.
</ParamField>

<ParamField query="instance" type="string">
  Your Instance ID. Only needed when your account has several instances.
</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-id.cabalspy.xyz/v1/wallets/tracker?blockchain=solana&address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW&period=7d" \
    -H "Authorization: Bearer YOUR_KEY"
  ```

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

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

  ps = d["period_stats"]
  print(d["profile"]["username"], "realized pnl", ps["realized_pnl"], d["profile"]["currency"])
  print("win rate", d["period_win_rate_distribution"]["win_rate_percentage"], "%")
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana",
    address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    period: "7d",
  });
  const res = await fetch(`https://api-id.cabalspy.xyz/v1/wallets/tracker?${p}`, {
    headers: { Authorization: "Bearer YOUR_KEY" },
  });
  const { data } = await res.json();
  console.log(data.profile.username, "pnl", data.period_stats.realized_pnl_usd);
  ```
</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="csid_id" type="string">
          The owner's CabalSpy ID.
        </ResponseField>

        <ResponseField name="username" type="string">
          X handle, or `tg.<telegram username>` / `id.<10 hex characters>` for users without X.
        </ResponseField>

        <ResponseField name="name" type="string">
          Display name.
        </ResponseField>

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

        <ResponseField name="twitter" type="string">
          X profile link, null without X.
        </ResponseField>

        <ResponseField name="telegram" type="string">
          Link to the owner's verified Telegram account (`https://t.me/<username>`), or an empty string.
        </ResponseField>

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

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

        <ResponseField name="type" type="string">
          Always csid.
        </ResponseField>

        <ResponseField name="kol" type="boolean">
          Whether the owner holds the KOL badge.
        </ResponseField>

        <ResponseField name="active_hours" type="string">
          The hours of the day (UTC) with most of the trades of the last 30 days, for example "13:00-21:00 UTC". Empty without trades.
        </ResponseField>

        <ResponseField name="profile_url" type="string">
          Public CabalSpy ID profile.
        </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), sells minus buys.
        </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 of the buy volume.
        </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 realized PnL on a single token.
        </ResponseField>

        <ResponseField name="worst_trade_pnl" type="number">
          Worst realized PnL on a single token.
        </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 time from first buy to first sell, in minutes.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_win_rate_distribution" type="object">
      <Expandable title="period_win_rate_distribution">
        <ResponseField name="win_count" type="integer">
          Winning closed positions. A position is closed once at least 99 percent of the bought tokens are sold.
        </ResponseField>

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

        <ResponseField name="win_rate_percentage" type="number">
          Wins divided by closed positions, as a percentage.
        </ResponseField>

        <ResponseField name="above_500" type="integer">
          Tokens sold for at least 5x the buy.
        </ResponseField>

        <ResponseField name="above_100_to_500" type="integer">
          Tokens sold for 2x to 5x.
        </ResponseField>

        <ResponseField name="above_zero_to_100" type="integer">
          Tokens sold for more than 1x and less than 2x.
        </ResponseField>

        <ResponseField name="below_zero" type="integer">
          Tokens sold at a loss.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_active_tokens" type="object">
      <Expandable title="period_active_tokens">
        <ResponseField name="active_tokens_count" type="integer">
          Tokens with a remaining balance from the period's trades.
        </ResponseField>

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

        <ResponseField name="still_holding_count" type="integer">
          Tokens where less than 95 percent of the buy value was sold.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_history_tokens" type="array">
      <Expandable title="token">
        <ResponseField name="mint" type="string">
          Token mint or contract.
        </ResponseField>

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

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

        <ResponseField name="token_logo" type="string">
          Token logo URL.
        </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 bought minus tokens sold in the period.
        </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="currency" type="string">
          Native currency.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="period_realized_pnl_chart" type="array">
      <Expandable title="chart point">
        <ResponseField name="timestamp" type="string">
          ISO timestamp, every 15 minutes from the start of the period to now.
        </ResponseField>

        <ResponseField name="realized_pnl" type="number">
          Cumulative realized PnL since the start of the period (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="tx_signature" type="string">
          Transaction signature or hash.
        </ResponseField>

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

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

        <ResponseField name="token_logo" type="string">
          Token logo URL.
        </ResponseField>

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

        <ResponseField name="buy_value" type="number">
          Trade value (native), on buys. Sells carry sell\_value instead.
        </ResponseField>

        <ResponseField name="buy_value_usd" type="number">
          Trade value in USD, on buys. Sells carry sell\_value\_usd instead.
        </ResponseField>

        <ResponseField name="token_amount" type="number">
          Tokens bought or sold.
        </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": {
        "csid_id": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
        "username": "MazeCCC",
        "name": "Maze",
        "image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
        "twitter": "https://x.com/MazeCCC",
        "telegram": "",
        "blockchain": "solana",
        "currency": "SOL",
        "type": "csid",
        "kol": true,
        "active_hours": "13:00-21:00 UTC",
        "profile_url": "https://id.cabalspy.xyz/u/MazeCCC"
      },
      "period_stats": {
        "period": "7d",
        "total_buy": 180.25,
        "total_buy_usd": 14840.6,
        "total_sell": 228.45,
        "total_sell_usd": 18809.2,
        "volume": 408.7,
        "volume_usd": 33649.8,
        "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_count": 14,
        "closed_count": 18,
        "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": 8.19,
        "still_holding_count": 3
      },
      "period_history_tokens": [
        {
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "token_name": "invisibull",
          "token_symbol": "invisibull",
          "token_logo": "https://...",
          "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,
          "realized_pnl": -1.66,
          "realized_pnl_usd": -137.44,
          "realized_pnl_percentage": -100.0,
          "currency": "SOL",
          "remaining_tokens": 22113972.03
        }
      ],
      "period_realized_pnl_chart": [
        { "timestamp": "2026-10-06T08:00:00Z", "realized_pnl": 0.0, "realized_pnl_usd": 0.0 },
        { "timestamp": "2026-10-06T08:15:00Z", "realized_pnl": 0.0, "realized_pnl_usd": 0.0 },
        { "timestamp": "2026-10-13T08:00:00Z", "realized_pnl": 48.2, "realized_pnl_usd": 3968.6 }
      ],
      "period_trades": [
        {
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "token_name": "invisibull",
          "token_logo": "https://...",
          "transaction_type": "buy",
          "buy_token": null,
          "sell_token": null,
          "buy_value": 1.66,
          "buy_value_usd": 137.44,
          "token_amount": 22113972.03,
          "created_at": "2026-10-12T16:25:34Z",
          "tx_signature": "5xr8..."
        }
      ]
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "v1",
      "timestamp": "2026-10-13T08:00:00Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | blockchain or address is missing. |
| 400 | invalid\_parameter | blockchain, period or address invalid. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | scope\_not\_allowed | scope=global needs the Enterprise plan. |
| 404 | wallet\_not\_found | The wallet is not verified on this chain by one of your users. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.