> For the complete documentation index, see [llms.txt](https://cabalspy.gitbook.io/cabalspy-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cabalspy.gitbook.io/cabalspy-docs/wallet-activity/pnl-calendar.md).

# PnL Calendar

Realized-PnL calendar for a tracked wallet. Returns the wallet profile and a `months` array — one entry per calendar month (oldest first), each with its per-day breakdown and a month summary. For convenience the current month is also exposed flat as `dates` and `month`. Ideal for rendering a month-by-month calendar with arrow navigation.

## Get a wallet's daily PnL calendar

> Returns the realized-PnL calendar for a tracked wallet, grouped by month. The wallet category (kol / smart / whale) is detected automatically. Unknown addresses return \`404\`.\
> \
> The response \`data.months\` holds one block per month (oldest first); each block has a \`dates\` array (one object per active day) and a \`month\` summary. The current month is additionally exposed flat as \`data.dates\` and \`data.month\` for backwards compatibility.\
> \
> \*\*Parameters / settings\*\*\
> \- \`blockchain\` (required) — one of: \`solana\`, \`bnb\`, \`base\`, \`eth\`\
> \- \`address\` (required) — wallet address (Solana base58 or \`0x…\` for EVM chains)\
> \- \`api\_key\` (optional if Bearer header is used)<br>

```json
{"openapi":"3.0.3","info":{"title":"CabalSpy API — PnL Calendar","version":"1.0.0"},"tags":[{"name":"PnL Calendar","description":"Realized-PnL calendar for a tracked wallet. Returns the wallet profile and a `months` array — one entry per calendar month (oldest first), each with its per-day breakdown and a month summary. For convenience the current month is also exposed flat as `dates` and `month`. Ideal for rendering a month-by-month calendar with arrow navigation.\n"}],"servers":[{"url":"https://api.cabalspy.xyz"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer YOUR_KEY"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key"}},"schemas":{"PnlCalendarEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"wallet":{"type":"string"},"profile":{"type":"object"},"months":{"type":"array","description":"One block per calendar month, oldest first.","items":{"$ref":"#/components/schemas/MonthBlock"}},"dates":{"type":"array","description":"Current month's per-day entries (backwards-compat).","items":{"$ref":"#/components/schemas/CalendarDay"}},"month":{"allOf":[{"$ref":"#/components/schemas/MonthSummary"}],"description":"Current month's summary (backwards-compat)."}}},"meta":{"type":"object"}}},"MonthBlock":{"type":"object","properties":{"month":{"$ref":"#/components/schemas/MonthSummary"},"dates":{"type":"array","items":{"$ref":"#/components/schemas/CalendarDay"}}}},"MonthSummary":{"type":"object","properties":{"month":{"type":"integer","description":"Month number 1–12"},"year":{"type":"integer"},"realized_pnl":{"type":"number"},"realized_pnl_usd":{"type":"number"},"volume":{"type":"number"},"total_buy":{"type":"number"},"total_buy_usd":{"type":"number"},"total_sell":{"type":"number"},"total_sell_usd":{"type":"number"},"buy_txn":{"type":"integer"},"sell_txn":{"type":"integer"},"txn_total":{"type":"integer"},"tokens_traded":{"type":"integer"},"positive_streak":{"type":"integer","description":"Longest run of profitable days"},"negative_streak":{"type":"integer","description":"Longest run of losing days"}}},"CalendarDay":{"type":"object","properties":{"date":{"type":"string","description":"DD-MM-YY"},"realized_pnl":{"type":"number","description":"Realized PnL in native currency"},"realized_pnl_usd":{"type":"number"},"volume":{"type":"number","description":"buy + sell","native":null},"total_buy":{"type":"number"},"total_buy_usd":{"type":"number"},"total_sell":{"type":"number"},"total_sell_usd":{"type":"number"},"buy_txn":{"type":"integer"},"sell_txn":{"type":"integer"},"txn_total":{"type":"integer"},"tokens_traded":{"type":"integer"}}},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"docs":{"type":"string"}}}}}}},"paths":{"/v1/wallet/pnl_calendar":{"get":{"tags":["PnL Calendar"],"summary":"Get a wallet's daily PnL calendar","operationId":"getPnlCalendar","description":"Returns the realized-PnL calendar for a tracked wallet, grouped by month. The wallet category (kol / smart / whale) is detected automatically. Unknown addresses return `404`.\n\nThe response `data.months` holds one block per month (oldest first); each block has a `dates` array (one object per active day) and a `month` summary. The current month is additionally exposed flat as `data.dates` and `data.month` for backwards compatibility.\n\n**Parameters / settings**\n- `blockchain` (required) — one of: `solana`, `bnb`, `base`, `eth`\n- `address` (required) — wallet address (Solana base58 or `0x…` for EVM chains)\n- `api_key` (optional if Bearer header is used)\n","parameters":[{"name":"blockchain","in":"query","required":true,"schema":{"type":"string","enum":["solana","bnb","base","eth"]}},{"name":"address","in":"query","required":true,"schema":{"type":"string"}},{"name":"api_key","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Wallet found — returns the PnL calendar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PnlCalendarEnvelope"}}}},"400":{"description":"Missing or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Invalid or exhausted API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Wallet not tracked on this chain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```