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

> GET /v1/wallets/history: lifetime stats, a per-token overview and the complete paginated trade log of a verified wallet.

The full lifetime record of a verified wallet of your users. Returns 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 whole life of the wallet. Use it for a complete profile page, 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. Statistics and the token overview always cover the whole history.
</Tip>

## Query Parameters

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

<ParamField query="address" type="string" required>
  A wallet verified on this chain by one of your users.
</ParamField>

<ParamField query="limit" default="500" type="integer">
  Trades per page in the trade log, 1 to 1000.
</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="scope" default="instance" type="string">
  `global` allows any CabalSpy ID wallet. Enterprise plan only.
</ParamField>

<ParamField query="instance" type="string">
  Your Instance ID. Only needed when your account has several instances.
</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-id.cabalspy.xyz/v1/wallets/history?blockchain=solana&address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW&limit=50" \
    -H "Authorization: Bearer YOUR_KEY"
  ```

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

  H = {"Authorization": "Bearer YOUR_KEY"}
  params = {
      "blockchain": "solana",
      "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "limit": 50,
  }
  r = requests.get("https://api-id.cabalspy.xyz/v1/wallets/history", params=params, headers=H).json()
  d = r["data"]

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

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

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana",
    address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
    limit: "50",
  });
  const res = await fetch(`https://api-id.cabalspy.xyz/v1/wallets/history?${p}`, {
    headers: { Authorization: "Bearer YOUR_KEY" },
  });
  const { data, pagination } = 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">
      The owner's profile, the same fields as on the [tracker](/cabalspy-id/tracker), plus wallet\_address.
    </ResponseField>

    <ResponseField name="lifetime_stats" type="object">
      <Expandable title="lifetime_stats">
        <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), sells minus buys.
        </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 trades.
        </ResponseField>

        <ResponseField name="win_rate" type="number">
          Wins divided by tokens sold, as a percentage.
        </ResponseField>

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

        <ResponseField name="total_sold" type="integer">
          Number of tokens with at least one sell.
        </ResponseField>

        <ResponseField name="active_tokens_count" type="integer">
          Number of tokens ever traded.
        </ResponseField>

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

        <ResponseField name="best_trade_pnl" type="number">
          Best realized PnL on a single token.
        </ResponseField>

        <ResponseField name="worst_trade_pnl" type="number">
          Worst realized PnL on a single token.
        </ResponseField>

        <ResponseField name="still_holding_count" type="integer">
          Tokens where less than 95 percent of the buy value was sold.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="win_rate_distribution" type="object">
      <Expandable title="win_rate_distribution">
        <ResponseField name="above_500" type="integer">
          Tokens sold for at least 5x the buy.
        </ResponseField>

        <ResponseField name="above_100_to_500" type="integer">
          Tokens sold for 2x to 5x.
        </ResponseField>

        <ResponseField name="above_zero_to_100" type="integer">
          Tokens sold for more than 1x and less than 2x.
        </ResponseField>

        <ResponseField name="below_zero" type="integer">
          Tokens sold at a loss.
        </ResponseField>
      </Expandable>
    </ResponseField>

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

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

        <ResponseField name="token_logo" type="string">
          Token logo URL.
        </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 less than 95 percent of the buy value was sold.
        </ResponseField>
      </Expandable>
    </ResponseField>

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

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

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

        <ResponseField name="token_logo" type="string">
          Token logo URL.
        </ResponseField>

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

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

        <ResponseField name="value_usd" type="number">
          Trade value in USD.
        </ResponseField>

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

        <ResponseField name="created_at" type="string">
          ISO timestamp of the trade.
        </ResponseField>
      </Expandable>
    </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>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "lifetime_stats": {
        "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_count": 138,
        "total_sold": 225,
        "win_rate": 61.33,
        "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",
          "token_logo": "https://...",
          "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-10-12T16:25:34Z",
          "last_seen": "2026-10-12T16:25:34Z",
          "still_holding": true
        }
      ],
      "trades": [
        {
          "tx_signature": "5xr8abc...",
          "mint": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
          "token_name": "invisibull",
          "token_logo": "https://...",
          "transaction_type": "buy",
          "value": 1.66,
          "value_usd": 137.44,
          "currency": "SOL",
          "created_at": "2026-10-12T16:25:34Z"
        }
      ],
      "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",
        "wallet_address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW"
      }
    },
    "pagination": {
      "limit": 50,
      "next_cursor": "MjAyNi0xMC0xMlQxNjoyNTozNCswMDowMHw1eHI4YWJj...",
      "has_more": true
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "v1",
      "timestamp": "2026-10-13T08:04:11Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | blockchain or address is missing. |
| 400 | invalid\_parameter | blockchain, address, limit or cursor invalid. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | scope\_not\_allowed | scope=global needs the Enterprise plan. |
| 404 | wallet\_not\_found | The wallet is not verified on this chain by one of your users. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.