> ## 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 wallet of your users for a period: stats, realized PnL, win rate distribution, traded tokens, PnL chart and trades.

The deepest view of one 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](https://docs.cabalspy.xyz/tracker.md), 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.

> [!NOTE]
>
> White-Label: unverified wallets of your platform users work here too, while `wallet_trust` is `all`. `profile.wallet_verified` tells you whether the wallet is payment-verified, so you can show a badge. With `wallet_trust: verified_only` only payment-verified wallets are answered.

## Query Parameters

**blockchain** `string` *required*

Chain of the wallet. One of solana, bnb, base, eth, rh.

**address** `string` *required*

A wallet of one of your users on this chain: payment-verified, or an unverified wallet of one of your [platform users](https://docs.cabalspy.xyz/cabalspy-id/white-label.md#unverified-and-verified-wallets) while your instance's `wallet_trust` is `all`.

**period** `string` (default: 1d)

Aggregation window, one of 6h, 1d, 7d or 30d.

**scope** `string` (default: instance)

`global` allows any CabalSpy ID wallet. Enterprise plan only.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

## Usage Example

```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);
```

## Response

**success** `boolean`

True on success.

**data** `object`

**data**

**wallet** `string`

The profiled wallet address.

**profile** `object`

**profile**

**csid\_id** `string`

The owner's CabalSpy ID.

**username** `string`

X handle, or `tg.<telegram username>` / `id.<10 hex characters>` for users without X.

**name** `string`

Display name.

**image\_url** `string`

Avatar URL.

**twitter** `string`

X profile link, null without X.

**telegram** `string`

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

**blockchain** `string`

Chain.

**currency** `string`

Native currency.

**type** `string`

Always csid.

**kol** `boolean`

Whether the owner holds the KOL badge.

**active\_hours** `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.

**profile\_url** `string`

Public CabalSpy ID profile. Null for platform users.

**wallet\_verified** `boolean`

Whether this wallet is payment-verified. False for an unverified wallet of one of your platform users.

**period\_stats** `object`

**period\_stats**

**period** `string`

The requested window.

**total\_buy** `number`

Buy volume in the period (native).

**total\_buy\_usd** `number`

Buy volume in USD.

**total\_sell** `number`

Sell volume in the period (native).

**total\_sell\_usd** `number`

Sell volume in USD.

**volume** `number`

Buy plus sell volume (native).

**volume\_usd** `number`

Buy plus sell volume in USD.

**realized\_pnl** `number`

Realized PnL in the period (native), sells minus buys.

**realized\_pnl\_usd** `number`

Realized PnL in USD.

**realized\_pnl\_percentage** `number`

Realized PnL as a percentage of the buy volume.

**buy\_txn** `integer`

Number of buys.

**sell\_txn** `integer`

Number of sells.

**largest\_buy** `number`

Largest single buy in the period (native).

**best\_trade\_pnl** `number`

Best realized PnL on a single token.

**worst\_trade\_pnl** `number`

Worst realized PnL on a single token.

**win\_count** `integer`

Winning closed positions.

**loss\_count** `integer`

Losing closed positions.

**avg\_hold\_time\_minutes** `number`

Average time from first buy to first sell, in minutes.

**period\_win\_rate\_distribution** `object`

**period\_win\_rate\_distribution**

**win\_count** `integer`

Winning closed positions. A position is closed once at least 99 percent of the bought tokens are sold.

**closed\_count** `integer`

Closed positions.

**win\_rate\_percentage** `number`

Wins divided by closed positions, as a percentage.

**above\_500** `integer`

Tokens sold for at least 5x the buy.

**above\_100\_to\_500** `integer`

Tokens sold for 2x to 5x.

**above\_zero\_to\_100** `integer`

Tokens sold for more than 1x and less than 2x.

**below\_zero** `integer`

Tokens sold at a loss.

**period\_active\_tokens** `object`

**period\_active\_tokens**

**active\_tokens\_count** `integer`

Tokens with a remaining balance from the period's trades.

**avg\_position\_size** `number`

Average buy size (native).

**still\_holding\_count** `integer`

Tokens where less than 95 percent of the buy value was sold.

**period\_history\_tokens** `array`

**token**

**mint** `string`

Token mint or contract.

**token\_name** `string`

Token name.

**token\_symbol** `string`

Token symbol.

**token\_logo** `string`

Token logo URL.

**buy\_value** `number`

Total bought (native).

**buy\_value\_usd** `number`

Total bought in USD.

**sell\_value** `number`

Total sold (native).

**sell\_value\_usd** `number`

Total sold in USD.

**buy\_tokens** `number`

Tokens bought.

**sell\_tokens** `number`

Tokens sold.

**remaining\_tokens** `number`

Tokens bought minus tokens sold in the period.

**realized\_pnl** `number`

Realized PnL on this token (native).

**realized\_pnl\_usd** `number`

Realized PnL in USD.

**realized\_pnl\_percentage** `number`

Realized PnL percentage.

**currency** `string`

Native currency.

**period\_realized\_pnl\_chart** `array`

**chart point**

**timestamp** `string`

ISO timestamp, every 15 minutes from the start of the period to now.

**realized\_pnl** `number`

Cumulative realized PnL since the start of the period (native).

**realized\_pnl\_usd** `number`

Cumulative realized PnL in USD.

**period\_trades** `array`

**trade**

**tx\_signature** `string`

Transaction signature or hash.

**mint** `string`

Token mint or contract.

**token\_name** `string`

Token symbol or name.

**token\_logo** `string`

Token logo URL.

**transaction\_type** `string`

buy or sell.

**buy\_value** `number`

Trade value (native), on buys. Sells carry sell\_value instead.

**buy\_value\_usd** `number`

Trade value in USD, on buys. Sells carry sell\_value\_usd instead.

**token\_amount** `number`

Tokens bought or sold.

**created\_at** `string`

ISO timestamp of the trade.

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

## 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. |
| 403 | product\_not\_enabled | The key is not enabled for the CabalSpy ID API (API keys page, Works with). |
| 403 | scope\_not\_allowed | scope=global needs the Enterprise plan. |
| 404 | wallet\_not\_found | The wallet does not count on this chain for one of your users: not payment-verified, and not an unverified wallet of one of your platform users (or `wallet_trust` is `verified_only`). |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |


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