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

---

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:

{
  "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.

{
  "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).

{
  "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.

[
  {
    "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.

[
  {
    "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

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