KOL Signals API — alerts when KOLs
buy the same token
The KOL signals API fires an entry signal when enough tracked KOL or Smart Money wallets buy the same token, and an exit signal when they leave. You set the thresholds; delivery is a WebSocket stream or a REST snapshot.
Turn KOL cluster buys into alerts you can act on
What it shows
A KOL signals API reports coordinated buying. When a group of KOL or Smart Money wallets buys the same token inside a short window, that is a cluster. Each signal names the token, the wallets in the cluster with their profiles, how much they invested in native currency and USD, and the trade that triggered it.
On the live stream every signal is marked entry or exit and carries the token’s live market cap plus, per wallet, the entry market cap, bag percentage and unrealized PnL. The REST snapshot adds a signal_strength of strong or medium and the time span between the first and latest buy.
How it works
For live alerts, open the WebSocket and subscribe to the signal stream with a chain, a token ("*" for all tokens or one address) and a rule block per wallet type. In a kol or smart block, entry_at lists the wallet counts that fire an entry (up to 3 values), exit_at lists the remaining holder counts that fire an exit (up to 2 values) and min_buy is the smallest buy that counts, in the chain’s native currency. With both blocks set, the entry gate is an AND: every type must reach its own count.
Optional filters narrow the cluster: min_win_rate, include_wallets, exclude_wallets, min_token_age and max_token_age (hours since the first tracked buy). For a signals page you refresh on a schedule, call GET /v1/signals with mode=cluster and tune it with min_wallets (default 3), min_value and hours (default 1). GET /v1/signals/history returns the cluster signals that would have fired on past days, for backtesting.
Supported chains: Solana, BNB Chain, Base, Ethereum and Robinhood Chain. The signal stream covers KOL and Smart Money rules; Smart Money is not available on Ethereum.
Quick start
Get a free key from the API dashboard (10,000 credits per month, no credit card), then:
const ws = new WebSocket("wss://stream.cabalspy.xyz?apiKey=YOUR_KEY");
ws.onopen = () => {
ws.send(JSON.stringify({
op: "subscribe", stream: "signal", blockchain: "solana", token: "*",
kol: { min_buy: 0.5, entry_at: [3, 5], exit_at: [1] },
min_win_rate: 50,
}));
};
ws.onmessage = (e) => {
const msg = JSON.parse(e.data);
if (msg.event === "signal") {
const d = msg.data;
console.log(d.signal_kind, d.token.symbol, "wallets", d.cluster.qualifying_total);
}
};curl "https://api.cabalspy.xyz/v1/signals?blockchain=solana&type=kol&mode=cluster&min_wallets=3&hours=1&api_key=YOUR_KEY"Who builds this
- Telegram and Discord bots — post an alert the moment a third or fifth KOL buys a token
- Alpha bots and AI agents — use entry and exit signals as a trigger, gated by win rate and token age
- Trading terminals — a signals page seeded over REST and updated live from the stream
- Quants and analysts — backtest a cluster strategy against the signals history endpoint
Frequently asked questions
01How do I get alerts when KOLs buy the same token?
Connect to wss://stream.cabalspy.xyz with your API key and subscribe to the signal stream with a chain, token "*" and a kol block such as { "entry_at": [3], "exit_at": [1] }. CabalSpy then pushes an entry signal when the third qualifying KOL wallet buys a token and an exit signal when only one is still holding.
02What is a KOL signals API?
A KOL signals API turns the trades of labeled KOL and Smart Money wallets into events. CabalSpy detects clusters, meaning several tracked wallets buying the same token within a time window, and delivers them as live entry and exit signals over WebSocket or as a snapshot from GET /v1/signals.
03Can I require both KOLs and Smart Money before a signal fires?
Yes. Send both a kol and a smart block when you subscribe to the signal stream. The entry gate is then an AND: each configured wallet type must reach its own entry_at count before the entry signal fires. You can also add min_win_rate so only wallets above a lifetime win rate count.
04Can I backtest KOL cluster signals?
Yes. GET https://api.cabalspy.xyz/v1/signals/history with blockchain, type and days returns the cluster signals that would have fired on past days, each with the token, wallet count, amount invested and triggered_at timestamp, so you can compare them with price history from your own source.
05How are signals billed?
A REST call to the signals endpoint is one request, which costs 10 credits. On the WebSocket stream each delivered signal deducts a fixed number of credits that is higher than a plain event, because a signal aggregates a whole cluster. The free tier includes 10,000 credits per month.
Go deeper
Related use cases
Build KOL Signal Service into your product. Start free today.
10,000 free credits every month, REST and WebSocket access, no credit card. Plans from $49/month.