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

> Day by day realized PnL calendar for a wallet, grouped by month, with per day profit and loss, volume, trade counts and win loss streaks.

A day by day realized PnL calendar for a wallet, grouped by month. Each day carries the realized PnL, volume, buy and sell counts and how many distinct tokens were traded. Each month adds a summary with totals and the longest winning and losing day streaks.

Use it to render a heatmap style trading calendar on a wallet profile, the kind that shows green and red days at a glance. Months are returned oldest first, and the current month updates continuously.

<Tip>
  The response includes months, an array of all months oldest first, plus dates and month for the current month at the top level for convenience. Each day date uses the format DD-MM-YY, for example 04-07-26.
</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 whose calendar you want.
</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/wallet/pnl_calendar?blockchain=solana&address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW&api_key=YOUR_KEY"
  ```

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

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

  for month in d["months"]:
      m = month["month"]
      print(m["year"], m["month"], "pnl", m["realized_pnl"], "streak", m["positive_streak"])
      for day in month["dates"]:
          print(" ", day["date"], day["realized_pnl"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana",
    address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/wallet/pnl_calendar?${p}`);
  const { data } = await res.json();
  data.months.forEach(month =>
    month.dates.forEach(day => console.log(day.date, day.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 wallet address.
    </ResponseField>

    <ResponseField name="profile" type="object">
      Wallet profile (name, image\_url, twitter, telegram, blockchain, currency, type).
    </ResponseField>

    <ResponseField name="months" type="array">
      <Expandable title="month">
        <ResponseField name="dates" type="array">
          <Expandable title="day">
            <ResponseField name="date" type="string">
              Day in the format DD-MM-YY, for example 04-07-26.
            </ResponseField>

            <ResponseField name="realized_pnl" type="number">
              Realized PnL for the day (native). Positive is a green day, negative a red day.
            </ResponseField>

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

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

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

            <ResponseField name="txn_total" type="integer">
              Total transactions that day.
            </ResponseField>

            <ResponseField name="tokens_traded" type="integer">
              Distinct tokens traded that day.
            </ResponseField>

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

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

            <ResponseField name="total_buy_usd" type="number">
              Total bought that day in USD.
            </ResponseField>

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

            <ResponseField name="total_sell_usd" type="number">
              Total sold that day in USD.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="month" type="object">
          <Expandable title="month summary">
            <ResponseField name="month" type="integer">
              Month number 1 to 12.
            </ResponseField>

            <ResponseField name="year" type="integer">
              Year.
            </ResponseField>

            <ResponseField name="positive_streak" type="integer">
              Longest run of consecutive profitable days in the month.
            </ResponseField>

            <ResponseField name="negative_streak" type="integer">
              Longest run of consecutive losing days in the month.
            </ResponseField>

            <ResponseField name="realized_pnl" type="number">
              Total realized PnL for the month (native).
            </ResponseField>

            <ResponseField name="realized_pnl_usd" type="number">
              Total realized PnL for the month in USD.
            </ResponseField>

            <ResponseField name="volume" type="number">
              Total volume for the month (native).
            </ResponseField>

            <ResponseField name="buy_txn" type="integer">
              Total buys in the month.
            </ResponseField>

            <ResponseField name="sell_txn" type="integer">
              Total sells in the month.
            </ResponseField>

            <ResponseField name="txn_total" type="integer">
              Total transactions in the month.
            </ResponseField>

            <ResponseField name="tokens_traded" type="integer">
              Distinct tokens traded in the month.
            </ResponseField>

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

            <ResponseField name="total_buy_usd" type="number">
              Total bought in the month in USD.
            </ResponseField>

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

            <ResponseField name="total_sell_usd" type="number">
              Total sold in the month in USD.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="dates" type="array">
      Convenience copy of the current month dates array (same shape as months dates).
    </ResponseField>

    <ResponseField name="month" type="object">
      Convenience copy of the current month summary (same shape as months month).
    </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"
      },
      "months": [
        {
          "dates": [
            {
              "date": "04-07-26",
              "realized_pnl": 12.4,
              "realized_pnl_usd": 1020.6,
              "buy_txn": 6,
              "sell_txn": 5,
              "txn_total": 11,
              "tokens_traded": 4,
              "volume": 88.5,
              "total_buy": 50.25,
              "total_buy_usd": 4137.6,
              "total_sell": 38.25,
              "total_sell_usd": 3150.4
            }
          ],
          "month": {
            "month": 7,
            "year": 2026,
            "positive_streak": 3,
            "negative_streak": 1,
            "realized_pnl": 48.2,
            "realized_pnl_usd": 3968.6,
            "volume": 312.5,
            "buy_txn": 22,
            "sell_txn": 18,
            "txn_total": 40,
            "tokens_traded": 23,
            "total_buy": 180.25,
            "total_buy_usd": 14840.6,
            "total_sell": 132.25,
            "total_sell_usd": 10890.65
          }
        }
      ],
      "dates": [],
      "month": {}
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "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 missing or invalid.        |
| 401    | unauthorized       | API key missing.                      |
| 403    | forbidden          | API key invalid or credits exhausted. |
| 429    | rate\_limited      | Rate limit exceeded.                  |