# API Reference Per-wallet trading data across all chains and wallet types. One endpoint — works for KOL, Smart Money and Whale wallets on SOL, BNB and Base. ## Get wallet trading data > Returns a complete trading profile for the given wallet address including:\ > \ > \- \*\*profile\*\* — name, avatar, social links, detected chain\ > \- \*\*period\_stats\*\* — total buy/sell volume and PNL for the requested period\ > \- \*\*recent\_trades\*\* — last 30 individual transactions\ > \- \*\*token\_overview\*\* — last 30 tokens traded with per-token PNL\ > \ > The wallet is looked up across all chains simultaneously.\ > If the wallet is not found in any chain, a \`404\` is returned.\ > \ > \*\*Response is cached for 30 seconds per wallet + period combination.\*\*\ > \ > \> ⚠️ \*\*Tracked wallets only.\*\*\ > \> This endpoint only works for wallets that CabalSpy actively monitors.\ > \> The leaderboard endpoints are the source of tracked wallet addresses.\ > \> Any wallet address that does not appear in a leaderboard will return \`404\`.\ > \> This is not a general-purpose blockchain explorer.\ > \ > \### Usage examples\ > \ > \*\*Solana KOL wallet:\*\*\ > \`\`\`\ > GET /api/wallet/tracker?wallet=G6fUXjMKPJzCY1rveAE6Qm7wy5U3vZgKDJmN1VPAdiZC\&period=1d\&chain=SOL\&api\_key=YOUR\_KEY\ > \`\`\`\ > \ > \*\*BNB KOL wallet:\*\*\ > \`\`\`\ > GET /api/wallet/tracker?wallet=0x7a2363a401b2340c7941dd2eeff0196a5078d2e6\&period=7d\&chain=BNB\&api\_key=YOUR\_KEY\ > \`\`\`\ > \ > \*\*Base Smart Money wallet:\*\*\ > \`\`\`\ > GET /api/wallet/tracker?wallet=0xa83b73f5644cde337b61da79589f10ea15548811\&period=30d\&chain=BASE\&api\_key=YOUR\_KEY\ > \`\`\`\ > \ > \### Integration guide\ > \ > To integrate this endpoint into your frontend, use the leaderboard endpoints to\ > get wallet addresses, then call this endpoint when a user clicks on a wallet.\ > See the full Next.js demo at \*\* > \ > \#### Leaderboard endpoints (wallet address 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 entries contain a \`wallet\_address\` field — pass that value\ > directly as the \`wallet\` parameter to this endpoint.
````json {"openapi":"3.0.3","info":{"title":"CabalSpy API — API Reference","version":"1.0.0"},"tags":[{"name":"API Reference","description":"Per-wallet trading data across all chains and wallet types.\nOne endpoint — works for KOL, Smart Money and Whale wallets on SOL, BNB and Base.\n"}],"servers":[{"url":"https://api.cabalspy.xyz","description":"Production Server"}],"paths":{"/api/wallet/tracker":{"get":{"tags":["API Reference"],"summary":"Get wallet trading data","description":"Returns a complete trading profile for the given wallet address including:\n\n- **profile** — name, avatar, social links, detected chain\n- **period_stats** — total buy/sell volume and PNL for the requested period\n- **recent_trades** — last 30 individual transactions\n- **token_overview** — last 30 tokens traded with per-token PNL\n\nThe wallet is looked up across all chains simultaneously.\nIf the wallet is not found in any chain, a `404` is returned.\n\n**Response is cached for 30 seconds per wallet + period combination.**\n\n> ⚠️ **Tracked wallets only.**\n> This endpoint only works for wallets that CabalSpy actively monitors.\n> The leaderboard endpoints are the source of tracked wallet addresses.\n> Any wallet address that does not appear in a leaderboard will return `404`.\n> This is not a general-purpose blockchain explorer.\n\n### Usage examples\n\n**Solana KOL wallet:**\n```\nGET /api/wallet/tracker?wallet=G6fUXjMKPJzCY1rveAE6Qm7wy5U3vZgKDJmN1VPAdiZC&period=1d&chain=SOL&api_key=YOUR_KEY\n```\n\n**BNB KOL wallet:**\n```\nGET /api/wallet/tracker?wallet=0x7a2363a401b2340c7941dd2eeff0196a5078d2e6&period=7d&chain=BNB&api_key=YOUR_KEY\n```\n\n**Base Smart Money wallet:**\n```\nGET /api/wallet/tracker?wallet=0xa83b73f5644cde337b61da79589f10ea15548811&period=30d&chain=BASE&api_key=YOUR_KEY\n```\n\n### Integration guide\n\nTo integrate this endpoint into your frontend, use the leaderboard endpoints to\nget wallet addresses, then call this endpoint when a user clicks on a wallet.\nSee the full Next.js demo at **https://github.com/CabalSpy/Wallet-Tracker-Demo**.\n\n#### Leaderboard endpoints (wallet address source)\n\n| Chain | Category | Endpoint |\n|-------|-------------|----------|\n| SOL | KOL | `GET /api/stats/leaderboard` |\n| SOL | Smart Money | `GET /api/stats/Smart_leaderboard` |\n| BNB | KOL | `GET /api/stats/leaderboard_bnb` |\n| BNB | Smart Money | `GET /api/stats/SmartBnb_leaderboard` |\n| Base | KOL | `GET /api/stats/leaderboard_base` |\n| Base | Smart Money | `GET /api/stats/SmartBase_leaderboard` |\n\nAll leaderboard entries contain a `wallet_address` field — pass that value\ndirectly as the `wallet` parameter to this endpoint.\n","operationId":"getWalletTracker","parameters":[{"name":"api_key","in":"query","required":true,"description":"Your valid API key","schema":{"type":"string"}},{"name":"wallet","in":"query","required":true,"description":"Wallet address to look up. \n- Solana: base58 encoded public key (~44 characters) \n- BNB / Base: EVM address starting with `0x`\n","schema":{"type":"string"}},{"name":"period","in":"query","required":false,"description":"Time period for stats and trade history. Defaults to `1d`.","schema":{"type":"string","enum":["6h","1d","7d","30d"],"default":"1d"}},{"name":"chain","in":"query","required":false,"description":"Force a specific chain for this wallet lookup.\nRecommended when linking from a leaderboard — BNB and Base both use\n`0x` addresses, so a wallet can exist on both chains simultaneously.\nIf omitted, the chain is detected automatically.\n","schema":{"type":"string","enum":["SOL","BNB","BASE"]}}],"responses":{"200":{"description":"Wallet found — returns full trading profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletTrackerResponse"}}}},"400":{"description":"Missing or invalid parameter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Invalid or exhausted API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Wallet not found.\nThis means the wallet is not tracked by CabalSpy.\nOnly wallets that appear in the leaderboard endpoints can be queried.\nArbitrary wallet addresses will always return 404.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"WalletTrackerResponse":{"type":"object","required":["profile","period_stats","recent_trades","token_overview"],"properties":{"profile":{"$ref":"#/components/schemas/WalletProfile"},"period_stats":{"$ref":"#/components/schemas/PeriodStats"},"recent_trades":{"type":"array","description":"Last 30 transactions for this wallet in descending chronological order.","items":{"$ref":"#/components/schemas/WalletTrade"}},"token_overview":{"type":"array","description":"Last 30 tokens traded, sorted by most recent activity.\nOnly tokens with non-zero buy or sell volume are included.\nUSDC/USDT positions are excluded.\n","items":{"$ref":"#/components/schemas/TokenPosition"}}}},"WalletProfile":{"type":"object","description":"Identity and metadata for the wallet.","required":["wallet_address","chain","currency","wallet_types"],"properties":{"wallet_address":{"type":"string","description":"The queried wallet address."},"name":{"type":"string","description":"Display name. Empty string if not set."},"image_url":{"type":"string","description":"Profile image filename. Prepend `https://cabalspy.xyz/images/` to get the full URL. \nExample: `cented.png` → `https://cabalspy.xyz/images/cented.png`\n"},"twitter":{"type":"string","description":"Twitter/X handle or URL. Empty string if not set."},"telegram":{"type":"string","description":"Telegram handle or URL. Empty string if not set."},"chain":{"type":"string","description":"Detected blockchain for this wallet.\nAuto-detected if no chain parameter is passed. When a wallet exists\non both BNB and Base, pass &chain=BNB or &chain=BASE in the request\nto get the correct chain.\n","enum":["SOL","BNB","BASE"]},"currency":{"type":"string","description":"Native currency for this chain. Used as the unit for all value fields.","enum":["SOL","BNB","ETH"]},"wallet_types":{"type":"array","description":"Which categories this wallet belongs to.\nA wallet can appear in multiple categories (e.g. both `kol` and `smart`).\n","items":{"type":"string","enum":["kol","smart","whale"]}}}},"PeriodStats":{"type":"object","description":"Aggregated trading statistics for the requested period.\nAll value fields are in the wallet's native currency (SOL / BNB / ETH).\n","required":["period","currency","buy","sell","pnl","pnl_percent","buy_count","sell_count"],"properties":{"period":{"type":"string","description":"The period that was requested.","enum":["6h","1d","7d","30d"]},"currency":{"type":"string","description":"Unit for buy, sell and pnl values.","enum":["SOL","BNB","ETH"]},"buy":{"type":"number","format":"float","description":"Total amount spent buying tokens in this period."},"sell":{"type":"number","format":"float","description":"Total amount received from selling tokens in this period."},"pnl":{"type":"number","format":"float","description":"Realized PNL = sell − buy.\nPositive = profit. Negative = loss.\n"},"pnl_percent":{"type":"number","format":"float","description":"PNL as percentage of buy volume.\nFormula: `(sell - buy) / buy × 100`\nReturns `-100` if buy > 0 and sell = 0.\nReturns `0` if both buy and sell are 0.\n"},"buy_count":{"type":"integer","description":"Number of buy transactions in this period."},"sell_count":{"type":"integer","description":"Number of sell transactions in this period."}}},"WalletTrade":{"type":"object","description":"A single transaction by this wallet.","properties":{"signature":{"type":"string","description":"Transaction hash / signature. \n- Solana: base58 signature (~88 chars) \n- BNB / Base: `0x` prefixed tx hash\n"},"token_symbol":{"type":"string","description":"Symbol of the traded token. May be empty for unknown tokens."},"mint":{"type":"string","description":"Token contract / mint address. \n- Solana: base58 mint address \n- BNB / Base: `0x` contract address\n"},"transaction_type":{"type":"string","description":"Direction of the trade.","enum":["buy","sell","swap"]},"value":{"type":"number","format":"float","description":"Trade value in the wallet's native currency (SOL / BNB / ETH).\nThis is the amount of native currency spent (buy) or received (sell).\n"},"currency":{"type":"string","description":"Currency unit for the value field.","enum":["SOL","BNB","ETH"]},"wallet_type":{"type":"string","description":"Which wallet category this transaction belongs to.","enum":["kol","smart","whale"]},"created_at":{"type":"string","format":"date-time","description":"UTC timestamp of the transaction."}}},"TokenPosition":{"type":"object","description":"Aggregated buy/sell data for a single token, for the requested period.\nSorted by most recent activity (`last_active` descending).\n","properties":{"mint":{"type":"string","description":"Token mint / contract address."},"token_symbol":{"type":"string","description":"Token symbol. May be empty if unknown."},"invested":{"type":"number","format":"float","description":"Total native currency spent buying this token in the period."},"sold":{"type":"number","format":"float","description":"Total native currency received from selling this token in the period."},"pnl":{"type":"number","format":"float","description":"PNL for this token = sold − invested.\n"},"pnl_percent":{"type":"number","format":"float","description":"PNL as percentage of invested.\nFormula: `(sold - invested) / invested × 100`\n"},"currency":{"type":"string","description":"Currency unit for invested, sold and pnl.","enum":["SOL","BNB","ETH"]},"held":{"type":"number","format":"float","description":"Current token balance held (in token units, not native currency).\n`0` if the position was fully closed or if position data is not yet available\nfor this wallet.\n"},"peak":{"type":"number","format":"float","description":"Peak token balance ever held (in token units).\n`0` if position data is not yet available.\n"},"bag_pct":{"type":"number","format":"float","description":"Percentage of the peak balance still held.\nExample: `50.0` means the wallet sold half its peak position.\n`0` if position data is not yet available.\n"},"supply_pct":{"type":"number","format":"float","description":"Percentage of the total token supply held at peak.\nUseful for detecting large holders.\n`0` if position data is not yet available.\n"},"last_active":{"type":"string","format":"date-time","description":"Timestamp of the most recent transaction for this token."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}} ```` --- # 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/api-reference.md?ask= ``` 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.