# How to integrate

## How to Integrate

The Wallet Tracker returns complete trading data for any wallet across **Solana**, **BNB Chain** and **Base** — profile, period stats, recent trades and a per-token breakdown. One endpoint works for all chains and all wallet types (KOL, Smart Money, Whale).

A full working Next.js demo is available on GitHub:\
👉 [**github.com/CabalSpy/Wallet-Tracker-Demo**](https://github.com/CabalSpy/Wallet-Tracker-Demo)

***

### Important — tracked wallets only

> ⚠️ **The Wallet Tracker only works for wallets that are already in our system.**
>
> We track a curated set of KOL, Smart Money and Whale wallets across Solana, BNB and Base. Arbitrary wallet addresses that are not in our database will return a `404 — Wallet not found` error.
>
> **The leaderboard is the source of truth.** Every wallet that appears in any leaderboard endpoint can be queried with the Wallet Tracker. If a wallet is not in the leaderboard, it cannot be tracked.

This means the intended integration flow is always:

1. **Fetch the leaderboard** → get a list of tracked wallets with their `wallet_address`
2. **Call the Wallet Tracker** with one of those addresses → get full trading data

You cannot use this endpoint as a general-purpose blockchain explorer. It is scoped exclusively to the wallets that CabalSpy monitors in real time.

***

### How it works

1. Get a `wallet_address` from any leaderboard endpoint
2. Pass it to `/api/wallet/tracker` with a period
3. The chain is detected automatically. You can optionally pass `&chain=SOL`, `&chain=BNB` or `&chain=BASE` to force a specific chain — recommended when linking from a leaderboard so wallets that exist on multiple chains are shown correctly.

```
GET https://api.cabalspy.xyz/api/wallet/tracker?wallet=WALLET_ADDRESS&period=1d&chain=BNB&api_key=YOUR_KEY
```

***

### Step 1 — Get wallet addresses from the leaderboard

All leaderboard responses contain a `wallet_address` field. Use any of these endpoints as your data source:

| Chain | Category    | Endpoint                               |
| ----- | ----------- | -------------------------------------- |
| SOL   | KOL         | `GET /api/stats/leaderboard`           |
| SOL   | Smart Money | `GET /api/stats/Smart_leaderboard`     |
| BNB   | KOL         | `GET /api/stats/leaderboard_bnb`       |
| BNB   | Smart Money | `GET /api/stats/SmartBnb_leaderboard`  |
| Base  | KOL         | `GET /api/stats/leaderboard_base`      |
| Base  | Smart Money | `GET /api/stats/SmartBase_leaderboard` |

All leaderboard endpoints accept a `period` parameter (`6h`, `1d`, `7d`, `30d`).

***

### Step 2 — Call the Wallet Tracker

Pass the `wallet_address` from the leaderboard directly as the `wallet` parameter.

**Solana KOL wallet**

```
GET /api/wallet/tracker?wallet=G6fUXjMKPJzCY1rveAE6Qm7wy5U3vZgKDJmN1VPAdiZC&period=1d&api_key=YOUR_KEY
```

**BNB KOL wallet**

```
GET /api/wallet/tracker?wallet=0x7a2363a401b2340c7941dd2eeff0196a5078d2e6&period=7d&api_key=YOUR_KEY
```

**Base Smart Money wallet**

```
GET /api/wallet/tracker?wallet=0xa83b73f5644cde337b61da79589f10ea15548811&period=30d&api_key=YOUR_KEY
```

***

### Step 3 — Use the response

The response always has the same four fields regardless of chain:

```json
{
  "profile":        { ... },
  "period_stats":   { ... },
  "recent_trades":  [ ... ],
  "token_overview": [ ... ]
}
```

#### profile

Identity and metadata for the wallet. Use `chain` and `currency` to know which blockchain was detected and which unit to display values in.

```json
{
  "wallet_address": "G6fUXjMKPJzCY1rveAE6Qm7wy5U3vZgKDJmN1VPAdiZC",
  "name":           "Cented",
  "image_url":      "cented.png",
  "twitter":        "@Cented",
  "telegram":       "",
  "chain":          "SOL",
  "currency":       "SOL",
  "wallet_types":   ["kol"]
}
```

> **Image URL:** The `image_url` field contains only the filename. Prepend `https://cabalspy.xyz/images/` to get the full URL.\
> Example: `cented.png` → `https://cabalspy.xyz/images/cented.png`

#### period\_stats

Aggregated buy/sell volume and PNL for the requested period. All values are in the wallet's native currency (`SOL`, `BNB` or `ETH`).

```json
{
  "period":      "1d",
  "currency":    "SOL",
  "buy":         148.2341,
  "sell":        254.1820,
  "pnl":         105.9479,
  "pnl_percent": 71.48,
  "buy_count":   34,
  "sell_count":  28
}
```

`pnl` = `sell - buy`. `pnl_percent` = `(sell - buy) / buy × 100`.

#### recent\_trades

Last 30 transactions, sorted newest first. The `value` field is always in the native currency of the chain.

```json
[
  {
    "signature":        "5UfgJ5vVZx...",
    "token_symbol":     "PEPE",
    "mint":             "PEPExxxx...",
    "transaction_type": "buy",
    "value":            4.25,
    "currency":         "SOL",
    "wallet_type":      "kol",
    "created_at":       "2025-03-19T14:22:11Z"
  }
]
```

#### token\_overview

Last 30 tokens traded, sorted by most recent activity. Contains per-token PNL for the requested period.

```json
[
  {
    "mint":         "PEPExxxx...",
    "token_symbol": "PEPE",
    "invested":     18.42,
    "sold":         31.75,
    "pnl":          13.33,
    "pnl_percent":  72.37,
    "currency":     "SOL",
    "held":         0.0,
    "bag_pct":      0.0,
    "supply_pct":   0.0,
    "last_active":  "2025-03-19T14:22:11Z"
  }
]
```

`invested` = total native currency spent buying this token in the period.\
`sold` = total received from selling.\
`held`, `bag_pct` and `supply_pct` reflect the current open position — these are `0` until new transactions come in after the first API call.

***

### Supported periods

| Period | Description             |
| ------ | ----------------------- |
| `6h`   | Last 6 hours            |
| `1d`   | Last 24 hours (default) |
| `7d`   | Last 7 days             |
| `30d`  | Last 30 days            |

***

### Chain & currency reference

| Chain  | Wallet format       | `currency` in response |
| ------ | ------------------- | ---------------------- |
| Solana | base58 (\~44 chars) | `SOL`                  |
| BNB    | `0x...`             | `BNB`                  |
| Base   | `0x...`             | `ETH`                  |

The chain is detected automatically. However, if a wallet exists on multiple chains (e.g. a trader active on both BNB and Base), pass `&chain=BNB` or `&chain=BASE` to get the correct data. This is especially important when linking from a leaderboard — always pass the chain the user was browsing. If no chain is passed, the API falls back to auto-detection.

***

### Next.js integration example

The GitHub demo shows a complete production-ready integration:

* Leaderboard with SOL, BNB and Base support
* Wallet popup that opens when clicking any trader
* Correct currency display per chain
* Activity feed and token overview tabs

👉 [**github.com/CabalSpy/Wallet-Tracker-Demo**](https://github.com/CabalSpy/Wallet-Tracker-Demo)

```bash
git clone https://github.com/CabalSpy/Wallet-Tracker-Demo
cd Wallet-Tracker-Demo
cp .env.local.example .env.local
# Add your API key to .env.local
npm install && npm run dev
```


---

# Agent Instructions: 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:

```
GET https://cabalspy.gitbook.io/cabalspy-docs/wallet-tracker/how-to-integrate.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.