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

# PnL calendar

> GET /v1/wallets/pnl_calendar: realized PnL per UTC day of a wallet of your users, grouped by month, with trade counts and win and loss streaks.

Realized PnL per UTC day of a wallet of your users, grouped by month, with buy and sell counts, volume, tokens traded and win and loss streaks. It covers the whole history of the wallet.

Use it to render a green and red PnL heatmap on a profile page.

> [!TIP]
>
> Months are ordered oldest first. The current month is also returned on its own as month, with its days in dates, so a calendar for this month needs no extra work.

> [!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`.

**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/pnl_calendar?blockchain=solana&address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW" \
  -H "Authorization: Bearer YOUR_KEY"
```

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

params = {"blockchain": "solana", "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW"}
r = requests.get("https://api-id.cabalspy.xyz/v1/wallets/pnl_calendar", params=params,
                 headers={"Authorization": "Bearer YOUR_KEY"})
for m in r.json()["data"]["months"]:
    print(m["year"], m["month"], m["realized_pnl"], "best streak", m["positive_streak"])
```

```javascript JavaScript theme={null}
const p = new URLSearchParams({
  blockchain: "solana",
  address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
});
const res = await fetch(`https://api-id.cabalspy.xyz/v1/wallets/pnl_calendar?${p}`, {
  headers: { Authorization: "Bearer YOUR_KEY" },
});
const { data } = await res.json();
data.dates.forEach(d => console.log(d.date, d.realized_pnl));
```

## Response

**success** `boolean`

True on success.

**data** `object`

**data**

**wallet** `string`

The wallet address.

**profile** `object`

The owner's profile, the same fields as on the [tracker](https://docs.cabalspy.xyz/cabalspy-id/tracker.md).

**months** `array`

**month**

**month** `integer`

Month, 1 to 12.

**year** `integer`

Year.

**dates** `array`

Days with trades in this month, see day below.

**realized\_pnl** `number`

Realized PnL in the month (native).

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

Realized PnL in USD.

**volume** `number`

Buy plus sell volume (native).

**total\_buy** `number`

Bought (native).

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

Bought in USD.

**total\_sell** `number`

Sold (native).

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

Sold in USD.

**buy\_txn** `integer`

Buys.

**sell\_txn** `integer`

Sells.

**txn\_total** `integer`

All trades.

**tokens\_traded** `integer`

Distinct tokens traded in the month.

**positive\_streak** `integer`

Longest run of consecutive trading days in profit.

**negative\_streak** `integer`

Longest run of consecutive trading days at a loss.

**current\_positive\_streak** `integer`

Current month only: the running profit streak.

**current\_negative\_streak** `integer`

Current month only: the running loss streak.

**dates** `array`

**day**

**date** `string`

UTC day as dd-mm-yy.

**realized\_pnl** `number`

Realized PnL of the day (native), sells minus buys.

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

Realized PnL in USD.

**buy\_txn** `integer`

Buys.

**sell\_txn** `integer`

Sells.

**txn\_total** `integer`

All trades.

**tokens\_traded** `integer`

Distinct tokens traded.

**volume** `number`

Buy plus sell volume (native).

**total\_buy** `number`

Bought (native).

**total\_sell** `number`

Sold (native).

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

Bought in USD.

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

Sold in USD.

**month** `object`

The current month, the same shape as an entry of months, or null when the wallet has no trades this month.

```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": "",
      "profile_url": "https://id.cabalspy.xyz/u/MazeCCC"
    },
    "months": [
      {
        "month": 10,
        "year": 2026,
        "dates": [
          {
            "date": "12-10-26",
            "realized_pnl": 4.12,
            "realized_pnl_usd": 339.21,
            "buy_txn": 6,
            "sell_txn": 5,
            "txn_total": 11,
            "tokens_traded": 4,
            "volume": 30.5,
            "total_buy": 13.19,
            "total_sell": 17.31,
            "total_buy_usd": 1086.1,
            "total_sell_usd": 1425.31
          }
        ],
        "realized_pnl": 4.12,
        "realized_pnl_usd": 339.21,
        "volume": 30.5,
        "total_buy": 13.19,
        "total_buy_usd": 1086.1,
        "total_sell": 17.31,
        "total_sell_usd": 1425.31,
        "buy_txn": 6,
        "sell_txn": 5,
        "txn_total": 11,
        "tokens_traded": 4,
        "positive_streak": 1,
        "negative_streak": 0,
        "current_positive_streak": 1,
        "current_negative_streak": 0
      }
    ],
    "dates": [
      {
        "date": "12-10-26",
        "realized_pnl": 4.12,
        "realized_pnl_usd": 339.21,
        "buy_txn": 6,
        "sell_txn": 5,
        "txn_total": 11,
        "tokens_traded": 4,
        "volume": 30.5,
        "total_buy": 13.19,
        "total_sell": 17.31,
        "total_buy_usd": 1086.1,
        "total_sell_usd": 1425.31
      }
    ],
    "month": { "month": 10, "year": 2026, "...": "same as months[-1]" }
  },
  "meta": {
    "request_id": "req_5162c7cf7f87",
    "cached": false,
    "cache_age_seconds": 0,
    "version": "v1",
    "timestamp": "2026-10-13T08:04:11Z"
  }
}
```

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | blockchain or address is missing. |
| 400 | invalid\_parameter | blockchain 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.