> 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/wallet-history.md).

# Wallet History

Returns a tracked wallet's complete LIFETIME trading history — every recorded transaction with no time limit. Includes aggregated lifetime stats, a per-token overview, a win-rate distribution and the full trade list via cursor pagination. Closed days are cached immutably and only the current day is read live, so responses stay fast across the full history.

## Get a wallet's lifetime trading history

> Aggregates all recorded transactions for the wallet across its entire history (not limited to a period). Only wallets that appear in a leaderboard are tracked — unknown addresses return \`404\`.\
> \
> \*\*Parameters\*\*\
> \- \`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 — Wallet History","version":"1.0.0"},"tags":[{"name":"Wallet History","description":"Returns a tracked wallet's complete LIFETIME trading history — every recorded transaction with no time limit. Includes aggregated lifetime stats, a per-token overview, a win-rate distribution and the full trade list via cursor pagination. Closed days are cached immutably and only the current day is read live, so responses stay fast across the full history.\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":{"WalletHistoryEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"profile":{"type":"object","properties":{"wallet_address":{"type":"string"},"name":{"type":"string"},"image_url":{"type":"string"},"twitter":{"type":"string"},"telegram":{"type":"string"},"blockchain":{"type":"string"},"type":{"type":"string"},"currency":{"type":"string"}}},"lifetime_stats":{"type":"object","properties":{"currency":{"type":"string"},"buy":{"type":"number","description":"Total bought (native)."},"sell":{"type":"number","description":"Total sold (native)."},"realized_pnl":{"type":"number","description":"Realized PnL (native)."},"realized_pnl_percentage":{"type":"number"},"buy_txn":{"type":"integer","description":"Number of buy transactions."},"sell_txn":{"type":"integer","description":"Number of sell transactions."},"total_tx_count":{"type":"integer"},"win_rate":{"type":"number"},"win_count":{"type":"integer"},"total_sold":{"type":"integer","description":"Number of tokens with at least one sell."},"active_tokens_count":{"type":"integer"},"largest_buy":{"type":"number"},"best_trade_pnl":{"type":"number"},"worst_trade_pnl":{"type":"number"},"still_holding_count":{"type":"integer"}}},"win_rate_distribution":{"type":"object","description":"Lifetime trade outcome buckets by sell/buy ratio.","properties":{"above_500":{"type":"integer","description":"Sold for ≥ 5× the buy amount (≥ 500%)."},"above_100_to_500":{"type":"integer","description":"Sold for ≥ 2× and < 5× (100–500%)."},"above_zero_to_100":{"type":"integer","description":"Sold for > 1× and < 2× (0–100%)."},"below_zero":{"type":"integer","description":"Sold at a loss (< 1×)."}}},"token_overview":{"type":"array","items":{"$ref":"#/components/schemas/HistoryToken"}},"trades":{"type":"array","description":"A page of trades, newest first. Use pagination.next_cursor to fetch the next page; iterate until next_cursor is null to obtain every transaction.\n","items":{"$ref":"#/components/schemas/HistoryTrade"}},"pagination":{"type":"object","properties":{"limit":{"type":"integer","description":"Page size used for this response."},"next_cursor":{"type":"string","nullable":true,"description":"Cursor for the next page, or null if there are no more trades."},"has_more":{"type":"boolean","description":"True if more trades are available."}}}}},"meta":{"type":"object"}}},"HistoryToken":{"type":"object","properties":{"mint":{"type":"string"},"token_name":{"type":"string"},"invested":{"type":"number","description":"Total bought for this token (native)."},"sold":{"type":"number","description":"Total sold for this token (native)."},"realized_pnl":{"type":"number"},"realized_pnl_percentage":{"type":"number"},"currency":{"type":"string"},"buy_txn":{"type":"integer","description":"Number of buy transactions for this token."},"sell_txn":{"type":"integer","description":"Number of sell transactions for this token."},"first_seen":{"type":"string","format":"date-time"},"last_seen":{"type":"string","format":"date-time"},"still_holding":{"type":"boolean","description":"True if less than 95% has been sold."}}},"HistoryTrade":{"type":"object","properties":{"tx_signature":{"type":"string","description":"On-chain transaction signature/hash."},"mint":{"type":"string"},"token_name":{"type":"string"},"transaction_type":{"type":"string","enum":["buy","sell"]},"value":{"type":"number","description":"Trade value (native)."},"currency":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"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/wallets/history":{"get":{"tags":["Wallet History"],"summary":"Get a wallet's lifetime trading history","operationId":"getWalletHistory","description":"Aggregates all recorded transactions for the wallet across its entire history (not limited to a period). Only wallets that appear in a leaderboard are tracked — unknown addresses return `404`.\n\n**Parameters**\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":"cursor","in":"query","required":false,"description":"Opaque pagination cursor from `pagination.next_cursor` of the previous response. Omit for the first page. Keep calling with the returned cursor until `next_cursor` is null to export every trade.\n","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Trades per page (1–1000).","schema":{"type":"integer","default":500,"minimum":1,"maximum":1000}},{"name":"api_key","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Wallet found — returns lifetime history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletHistoryEnvelope"}}}},"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"}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cabalspy.gitbook.io/cabalspy-docs/wallet-activity/wallet-history.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.