> ## 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 wallet of your users.

The full lifetime record of a 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.

> [!NOTE]
>
> White-Label: unverified wallets of your platform users work here too, while `wallet_trust` is `all`. `profile.wallet_verified` tells you whether the wallet is payment-verified, so you can show a badge. With `wallet_trust: verified_only` only payment-verified wallets are answered.

## Query Parameters

**blockchain** `string` *required*

Chain of the wallet. One of solana, bnb, base, eth, rh.

**address** `string` *required*

A wallet of one of your users on this chain: payment-verified, or an unverified wallet of one of your [platform users](https://docs.cabalspy.xyz/cabalspy-id/white-label.md#unverified-and-verified-wallets) while your instance's `wallet_trust` is `all`.

**mint** `string`

Only the trades of this token, for example to mark a user's buys and sells on a token's price chart. The lifetime stats then cover this token only.

**limit** `integer` (default: 500)

Trades per page in the trade log, 1 to 1000.

**cursor** `string`

Cursor for the next page of trades, the pagination.next\_cursor from the previous response. Empty means from the newest trade.

**scope** `string` (default: instance)

`global` allows any CabalSpy ID wallet. Enterprise plan only.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

## Usage Example

```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));
```

## Response

**success** `boolean`

True on success.

**data** `object`

**data**

**profile** `object`

The owner's profile, the same fields as on the [tracker](https://docs.cabalspy.xyz/cabalspy-id/tracker.md), plus wallet\_address.

**lifetime\_stats** `object`

**lifetime\_stats**

**buy** `number`

Total bought over the wallet lifetime (native).

**sell** `number`

Total sold over the wallet lifetime (native).

**realized\_pnl** `number`

Lifetime realized PnL (native), sells minus buys.

**realized\_pnl\_percentage** `number`

Lifetime realized PnL percentage.

**buy\_txn** `integer`

Total buys.

**sell\_txn** `integer`

Total sells.

**total\_tx\_count** `integer`

Total trades.

**win\_rate** `number`

Wins divided by tokens sold, as a percentage.

**win\_count** `integer`

Number of winning tokens.

**total\_sold** `integer`

Number of tokens with at least one sell.

**active\_tokens\_count** `integer`

Number of tokens ever traded.

**largest\_buy** `number`

Largest single buy (native).

**best\_trade\_pnl** `number`

Best realized PnL on a single token.

**worst\_trade\_pnl** `number`

Worst realized PnL on a single token.

**still\_holding\_count** `integer`

Tokens where less than 95 percent of the buy value was sold.

**win\_rate\_distribution** `object`

**win\_rate\_distribution**

**above\_500** `integer`

Tokens sold for at least 5x the buy.

**above\_100\_to\_500** `integer`

Tokens sold for 2x to 5x.

**above\_zero\_to\_100** `integer`

Tokens sold for more than 1x and less than 2x.

**below\_zero** `integer`

Tokens sold at a loss.

**token\_overview** `array`

**token**

**mint** `string`

Token mint or contract.

**token\_name** `string`

Token name.

**token\_logo** `string`

Token logo URL.

**invested** `number`

Total invested in this token (native).

**sold** `number`

Total sold value of this token (native).

**realized\_pnl** `number`

Realized PnL on this token (native).

**realized\_pnl\_percentage** `number`

Realized PnL percentage.

**currency** `string`

Native currency.

**buy\_txn** `integer`

Buys on this token.

**sell\_txn** `integer`

Sells on this token.

**first\_seen** `string`

ISO timestamp of the first trade on this token.

**last\_seen** `string`

ISO timestamp of the most recent trade on this token.

**still\_holding** `boolean`

Whether less than 95 percent of the buy value was sold.

**trades** `array`

**trade**

**tx\_signature** `string`

Transaction signature or hash.

**mint** `string`

Token mint or contract.

**token\_name** `string`

Token symbol or name.

**token\_logo** `string`

Token logo URL.

**transaction\_type** `string`

buy or sell.

**value** `number`

Trade value (native).

**value\_usd** `number`

Trade value in USD.

**currency** `string`

Native currency.

**token\_amount** `number`

Tokens bought or sold.

**price\_usd** `number`

Price per token in USD at the trade: value\_usd / token\_amount.

**created\_at** `string`

ISO timestamp of the trade.

**pagination** `object`

**pagination**

**limit** `integer`

Trades per page.

**next\_cursor** `string`

Cursor for the next page (null means end).

**has\_more** `boolean`

Whether more pages follow.

```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"
  }
}
```

## 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. |
| 403 | product\_not\_enabled | The key is not enabled for the CabalSpy ID API (API keys page, Works with). |
| 403 | scope\_not\_allowed | scope=global needs the Enterprise plan. |
| 404 | wallet\_not\_found | The wallet does not count on this chain for one of your users: not payment-verified, and not an unverified wallet of one of your platform users (or `wallet_trust` is `verified_only`). |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |


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