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

# History

> Complete lifetime trading history of a wallet, with lifetime stats, win rate distribution, a per token overview and a paginated trade log.

The full lifetime record of a wallet. Returns aggregate lifetime statistics, a win rate distribution across profit buckets, a per token overview of everything the wallet has traded, and a paginated log of individual trades newest first.

Where the tracker focuses on a single period, history covers the entire life of the wallet. Use it for a complete profile page, tax style trade exports, or deep research on a trader.

<Tip>
  The trade log is paginated. Read pagination.next\_cursor from the response and pass it back as cursor to fetch the next page. When next\_cursor is null you have reached the end.
</Tip>

## Query Parameters

<ParamField query="blockchain" type="string" required>
  Chain of the wallet. One of solana, bnb, base, eth.
</ParamField>

<ParamField query="type" type="string" required>
  Wallet category kol, smart or whale. Availability per chain. Solana has kol, smart, whale. BNB and Base have kol, smart. ETH has kol.
</ParamField>

<ParamField query="address" type="string" required>
  The wallet address whose history you want.
</ParamField>

<ParamField query="limit" default="50" type="integer">
  Number of trades per page in the trade log.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for the next page of trades, the pagination.next\_cursor from the previous response. Empty means from the newest trade.
</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/wallets/history?blockchain=solana&type=kol&address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW&limit=50&api_key=YOUR_KEY"
  ```

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

  params = {
      "blockchain": "solana", "type": "kol",
      "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "limit": 50, "api_key": "YOUR_KEY",
  }
  r = requests.get("https://api.cabalspy.xyz/v1/wallets/history", params=params)
  d = r.json()["data"]

  print("lifetime pnl", d["lifetime_stats"]["realized_pnl"], d["lifetime_stats"]["currency"])
  for t in d["trades"]:
      print(t["created_at"], t["transaction_type"], t["token_name"], t["value"])

  nxt = d["pagination"]["next_cursor"]
  if nxt:
      params["cursor"] = nxt
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana", type: "kol",
    address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    limit: "50", api_key: "YOUR_KEY",
  });
  const res = await fetch(`https://api.cabalspy.xyz/v1/wallets/history?${p}`);
  const { data } = await res.json();
  data.trades.forEach(t => console.log(t.created_at, t.transaction_type, t.token_name));
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  True on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="profile" type="object">
      <Expandable title="profile">
        <ResponseField name="wallet_address" type="string">
          Wallet address.
        </ResponseField>

        <ResponseField name="name" type="string">
          Display name (may be empty).
        </ResponseField>

        <ResponseField name="image_url" type="string">
          Avatar URL.
        </ResponseField>

        <ResponseField name="twitter" type="string">
          Twitter or X link.
        </ResponseField>

        <ResponseField name="telegram" type="string">
          Telegram link.
        </ResponseField>

        <ResponseField name="blockchain" type="string">
          Chain.
        </ResponseField>

        <ResponseField name="type" type="string">
          Wallet type.
        </ResponseField>

        <ResponseField name="currency" type="string">
          Native currency.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="lifetime_stats" type="object">
      <Expandable title="lifetime_stats">
        <ResponseField name="currency" type="string">
          Native currency.
        </ResponseField>

        <ResponseField name="buy" type="number">
          Total bought over the wallet lifetime (native).
        </ResponseField>

        <ResponseField name="sell" type="number">
          Total sold over the wallet lifetime (native).
        </ResponseField>

        <ResponseField name="realized_pnl" type="number">
          Lifetime realized PnL (native).
        </ResponseField>

        <ResponseField name="realized_pnl_percentage" type="number">
          Lifetime realized PnL percentage.
        </ResponseField>

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

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

        <ResponseField name="total_tx_count" type="integer">
          Total transactions.
        </ResponseField>

        <ResponseField name="win_rate" type="number">
          Win rate as a percentage.
        </ResponseField>

        <ResponseField name="win_count" type="integer">
          Number of winning positions.
        </ResponseField>

        <ResponseField name="total_sold" type="integer">
          Number of closed positions.
        </ResponseField>

        <ResponseField name="active_tokens_count" type="integer">
          Number of tokens with any activity.
        </ResponseField>

        <ResponseField name="largest_buy" type="number">
          Largest single buy (native).
        </ResponseField>

        <ResponseField name="best_trade_pnl" type="number">
          Best single trade realized PnL.
        </ResponseField>

        <ResponseField name="worst_trade_pnl" type="number">
          Worst single trade realized PnL.
        </ResponseField>

        <ResponseField name="still_holding_count" type="integer">
          Number of positions still open.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="win_rate_distribution" type="object">
      <Expandable title="win_rate_distribution">
        <ResponseField name="above_500" type="integer">
          Positions with more than 500 percent gain.
        </ResponseField>

        <ResponseField name="above_100_to_500" type="integer">
          Positions with 100 to 500 percent gain.
        </ResponseField>

        <ResponseField name="above_zero_to_100" type="integer">
          Positions with 0 to 100 percent gain.
        </ResponseField>

        <ResponseField name="below_zero" type="integer">
          Losing positions.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="token_overview" type="array">
      <Expandable title="token">
        <ResponseField name="mint" type="string">
          Token mint.
        </ResponseField>

        <ResponseField name="token_name" type="string">
          Token name.
        </ResponseField>

        <ResponseField name="invested" type="number">
          Total invested in this token (native).
        </ResponseField>

        <ResponseField name="sold" type="number">
          Total sold value of this token (native).
        </ResponseField>

        <ResponseField name="realized_pnl" type="number">
          Realized PnL on this token (native).
        </ResponseField>

        <ResponseField name="realized_pnl_percentage" type="number">
          Realized PnL percentage.
        </ResponseField>

        <ResponseField name="currency" type="string">
          Native currency.
        </ResponseField>

        <ResponseField name="buy_txn" type="integer">
          Buys on this token.
        </ResponseField>

        <ResponseField name="sell_txn" type="integer">
          Sells on this token.
        </ResponseField>

        <ResponseField name="first_seen" type="string">
          ISO timestamp of the first trade on this token.
        </ResponseField>

        <ResponseField name="last_seen" type="string">
          ISO timestamp of the most recent trade on this token.
        </ResponseField>

        <ResponseField name="still_holding" type="boolean">
          Whether the wallet still holds a meaningful position.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="trades" type="array">
      <Expandable title="trade">
        <ResponseField name="tx_signature" type="string">
          Transaction signature.
        </ResponseField>

        <ResponseField name="mint" type="string">
          Token mint.
        </ResponseField>

        <ResponseField name="token_name" type="string">
          Token name or symbol.
        </ResponseField>

        <ResponseField name="transaction_type" type="string">
          buy or sell.
        </ResponseField>

        <ResponseField name="value" type="number">
          Trade value (native).
        </ResponseField>

        <ResponseField name="currency" type="string">
          Native currency (may be null on some historical rows).
        </ResponseField>

        <ResponseField name="created_at" type="string">
          ISO timestamp of the trade.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pagination" type="object">
      <Expandable title="pagination">
        <ResponseField name="limit" type="integer">
          Trades per page.
        </ResponseField>

        <ResponseField name="next_cursor" type="string">
          Cursor for the next page (null means end).
        </ResponseField>

        <ResponseField name="has_more" type="boolean">
          Whether more pages follow.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "profile": {
        "wallet_address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
        "name": "Maze",
        "image_url": "https://cabalspy.xyz/images/7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW.png",
        "twitter": "https://x.com/MazeCCC",
        "telegram": "",
        "blockchain": "solana",
        "type": "kol",
        "currency": "SOL"
      },
      "lifetime_stats": {
        "currency": "SOL",
        "buy": 1840.5,
        "sell": 2010.75,
        "realized_pnl": 170.25,
        "realized_pnl_percentage": 9.25,
        "buy_txn": 412,
        "sell_txn": 388,
        "total_tx_count": 800,
        "win_rate": 61.34,
        "win_count": 138,
        "total_sold": 225,
        "active_tokens_count": 240,
        "largest_buy": 42.0,
        "best_trade_pnl": 88.6,
        "worst_trade_pnl": -19.4,
        "still_holding_count": 15
      },
      "win_rate_distribution": {
        "above_500": 6,
        "above_100_to_500": 28,
        "above_zero_to_100": 104,
        "below_zero": 87
      },
      "token_overview": [
        {
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "token_name": "invisibull",
          "invested": 1.66,
          "sold": 0.0,
          "realized_pnl": -1.66,
          "realized_pnl_percentage": -100.0,
          "currency": "SOL",
          "buy_txn": 1,
          "sell_txn": 0,
          "first_seen": "2026-07-04T16:25:34Z",
          "last_seen": "2026-07-04T16:25:34Z",
          "still_holding": true
        }
      ],
      "trades": [
        {
          "tx_signature": "5xr8abc...",
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "token_name": "invisibull",
          "transaction_type": "buy",
          "value": 1.66,
          "currency": "SOL",
          "created_at": "2026-07-04T16:25:34Z"
        }
      ],
      "pagination": {
        "limit": 50,
        "next_cursor": "MjAyNi0wNy0wNFQxNjoyNTozNFp8NXhyOGFiYw==",
        "has_more": true
      }
    },
    "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 or type missing or invalid. |
| 401    | unauthorized       | API key missing.                       |
| 403    | forbidden          | API key invalid or credits exhausted.  |
| 429    | rate\_limited      | Rate limit exceeded.                   |