How to Build a Powerful Whale Tracker in 4 Steps

A token can move ten percent in a minute and the candle alone never tells you why. Most of the time the real cause is a handful of large trades clearing a thin order book, and if you only watch price, you find out after the move instead of during it. A whale transaction tracker fixes that by watching the trades themselves, so a six figure buy or a sudden wave of selling shows up the moment it happens.

This guide builds that whale tracker on Solana with Birdeye Data. It does four things in sequence: reads a token’s normal trading volume so your threshold is not a guess, pulls only the trades that clear that threshold, splits those trades into buy and sell pressure, and watches for new ones as they land. What you do with the alert, whether that is a Telegram ping, a trading signal, or a dashboard, is your call.

Whale Transaction Tracker in 4 Steps

Here is the whole pipeline in plain terms, so you can follow it even without reading the rest of the guide.

1. Read the token’s normal trading stats. Pull aggregate volume and the buy versus sell split across a few timeframes, so your whale threshold reflects how this specific token actually trades.
2. Pull only the trades above that threshold. Query the trades endpoint with a minimum dollar volume, so you process whale sized prints instead of the full tape.
3. Classify each print as a buy or a sell. Sum the dollar volume per direction, so the layer reports net pressure instead of a raw trade count.
4. Poll for new prints on a short loop. Each pass picks up trades since the last one you saw, so the whale tracker fires close to the moment a whale trade lands.

Every endpoint below runs on Solana and works on a Premium plan over standard REST (representational state transfer) calls, so the whole whale tracker runs on simple polling.

Mix Up to 8 Timeframes Before You Set a Threshold

A whale is relative. A $20,000 trade is enormous on a token with $50,000 of daily volume and barely noticeable on one with $50 million, so the first call is not detection, it is context.

Endpoint: GET /defi/v3/token/trade-data/single

Chains: All chains

Plan availability: Lite plan and higher, so it runs on Premium

Docs: Token Trade Data (Single)

This endpoint returns a token’s trade statistics across timeframes from one minute to 24 hours in a single flat object, including trade counts, buy and sell volume, and the percent change against the prior period.

Parameter	In	Required	Notes
address	query	yes	the token address, not token_address
frames	query	no	up to 8 custom intervals; minutes from 1m to 1440m, seconds in multiples of 5 up to 3600s, hours limited to 1h, 2h, 4h, 8h, 24h
ui_amount_mode	query	no	raw or scaled (default), Solana only
x-chain	header	no	defaults to solana

This endpoint uses address, not token_address, which is easy to get wrong if you are jumping here from an endpoint in the next stage. Leave frames unset on your first call to see every available window, then narrow it once you know which timeframes you actually need. If you do set frames, the hour intervals only accept the fixed set 1h, 2h, 4h, 8h, 24h, while minute and second intervals follow their own ranges, so do not mix in an arbitrary hour value like 3h.

curl -s "<https://public-api.birdeye.so/defi/v3/token/trade-data/single?address=TOKEN_ADDRESS>" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "x-chain: solana"

Size your threshold from volume_1h_usd or volume_24h_usd, and read the backdrop from volume_buy_24h_usd against volume_sell_24h_usd before you look at a single trade. Keep the dollar fields separate from the token quantity fields: volume_buy_24h is a token amount, while volume_buy_24h_usd is the dollar figure, and buy_24h/sell_24h are trade counts, not volume at all. Run every threshold and pressure calculation on the _usd fields, since mixing in a token quantity field produces numbers with no real meaning.

A simple starting heuristic works well: set min_volume near 0.5 to 1 percent of volume_1h_usd, then tighten or loosen it based on how many alerts you actually want to act on. A token moving $2 million an hour might use a $15,000 to $20,000 floor, while one moving $50,000 an hour should sit closer to $500. Revisit the number whenever volume shifts meaningfully, since a fixed dollar figure quietly becomes too loose or too tight as the token’s own activity changes, and a whale tracker built on a stale threshold misses exactly the trades it exists to catch.

With a baseline in hand, you know what counts as large for this specific token. The next call goes and finds those trades.

Pull Up to 500 Trades Above Your Dollar Threshold

Most tokens generate thousands of small trades for every one that matters. Filtering for size up front means your whale tracker only ever has to look at the prints worth caring about.

Endpoint: GET /defi/v3/token/txs-by-volume

Chains: Solana

Plan availability: Lite plan and higher, so it runs on Premium

Docs: Token Trades by Volume

This endpoint returns trades for one token filtered by a minimum and maximum volume, so you get back exactly the whale sized prints rather than the full trade history.

Parameter	In	Required	Notes
token_address	query	yes	the token to monitor
volume_type	query	yes	usd or amount, no default
min_volume	query	no	up to 3 decimals
max_volume	query	no	up to 3 decimals
sort_type	query	yes	desc or asc
tx_type	query	no	swap (default), buy, sell, add, remove, all
limit	query	no	up to 500

This endpoint uses token_address, the opposite of the previous stage. volume_type has no default, so a missing value returns a 400 error rather than falling back to a sensible choice; set it to usd and pair it with min_volume so the threshold from stage one becomes a dollar filter rather than a token count.

curl -s "<https://public-api.birdeye.so/defi/v3/token/txs-by-volume?token_address=TOKEN_ADDRESS&volume_type=usd&min_volume=10000&sort_type=desc&limit=100>" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "x-chain: solana"

The response is data.items, and each print carries volume_usd, owner, side, a from and to leg with ui_change_amount, and pool_id. There is also a raw volume field, but its denomination is not fixed since it sometimes reports the monitored token’s amount and sometimes the paired token’s amount, so size everything on volume_usd instead and leave volume for display only.

You now have a clean stream of whale sized trades on the token you are watching. The next stage turns that stream into a directional read.

Split the Tape into Buy and Sell Pressure

A whale buying and a whale selling look identical on a line chart but mean opposite things for where price goes next, so direction is not optional.

Endpoint: GET /defi/v3/token/txs-by-volume (filtered with tx_type=buy and tx_type=sell)

Chains: Solana

Plan availability: Lite plan and higher, so it runs on Premium

Docs: Token Trades by Volume

This is the same endpoint as stage two, used two ways. Either read each print’s side field from a combined pull, or issue two calls with tx_type=buy and tx_type=sell to get each direction pre split.

curl -s "<https://public-api.birdeye.so/defi/v3/token/txs-by-volume?token_address=TOKEN_ADDRESS&volume_type=usd&min_volume=10000&tx_type=buy&sort_type=desc&limit=100>" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "x-chain: solana"

The convention is relative to the token you query: a print labeled buy means the monitored token was acquired, so it sits in the to leg with a positive ui_change_amount, and a print labeled sell means it was given up, so it sits in from with a negative ui_change_amount. This reads correctly as long as you pass the token you are actually monitoring as token_address. Pass a quote token such as SOL instead and the trades returned span every pair that token touches, which flips the meaning of the labels, so always query the specific token you care about.

Sum volume_usd across each direction over a rolling window, say the last hour, to get a net pressure figure rather than a raw count of buys and sells. A token can show ten buys and two sells and still be net negative if the two sells are large enough, so the dollar sum is what matters, not the trade count.

If you run the same pipeline across several tokens at once, a trade that touches two of your monitored tokens in a single swap gets evaluated once per token, since each call is scoped to its own token_address rather than shared across a watchlist. That is the correct behavior for a per-token whale tracker, but it is worth knowing before you sum pressure figures across multiple tokens and expect the totals to be mutually exclusive.

With buy and sell pressure separated, you have a directional read on every whale move. The last stage makes that read continuous instead of a single snapshot.

Poll for New Whale Prints Every 2 to 5 Seconds

A whale tracker that only answers when asked is a research tool, not an alert system. The final stage turns the same endpoint into a live feed with a short polling loop.

API: GET /defi/v3/token/txs-by-volume (REST polling, default on Premium)

Chains: Solana

Plan availability: Lite plan and higher, so it runs on Premium

Docs: Token Trades by Volume

On each pass, ask for trades after the timestamp of the last one you processed, and any new whale sized prints are your alert. This call still needs every parameter from the detection stage, token_address, volume_type, and min_volume included, since after_time only adds an incremental window on top of the same filter.

Parameter	In	Required	Notes
after_time	query	no	unix timestamp in seconds, the lower bound
before_time	query	no	unix timestamp in seconds, the upper bound
sort_type	query	yes	use asc when polling forward in time

curl -s "<https://public-api.birdeye.so/defi/v3/token/txs-by-volume?token_address=TOKEN_ADDRESS&volume_type=usd&min_volume=10000&after_time=1755058900&sort_type=asc&limit=100>" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "x-chain: solana"

Set after_time to the block_unix_time of the last print you handled, and dedupe incoming records on the composite key tx_hash plus ins_index plus inner_ins_index. One transaction can produce several trade legs that share a single hash but differ by index, so deduping on tx_hash alone drops real legs rather than just true duplicates. The pagination flag comes back as has_next for a standard token on Solana; a scaled UI token can return hasNext instead, so read both keys defensively if your watchlist might include one.

A polling interval of two to five seconds catches most whale activity without straining your credit budget, though a very high traffic token can warrant something tighter. Going much below roughly one second rarely buys you meaningful extra warning, since a trade still has to confirm on chain before it shows up in the response, and it multiplies your credit spend for little benefit.

For teams that want push delivery instead of polling, the large trade stream is available on higher plans and removes the loop entirely. On a Premium plan, a short REST polling interval on this endpoint is the reliable default and keeps the entire whale tracker on plain REST.

That closes the loop. A market wide stream of activity has become a precise event: a trade large enough to matter, on the token you are watching, with a direction attached.

Trace One Whale Print Through All 4 Stages

The field names above stay abstract until you attach numbers to them. Here is an illustrative run through the whale tracker’s four stages.

Suppose stage one returns a token with volume_24h_usd near $2 million and a roughly even split between volume_buy_24h_usd and volume_sell_24h_usd. Given that backdrop, you set the whale threshold at $15,000, large enough to filter out routine retail trades without missing real size.

Stage two pulls every trade above that threshold and returns four prints in the last hour, each with volume_usd between $15,000 and $40,000. None of them alone would move the market, but four of them inside an hour is already a meaningful concentration of size.

Stage three splits those four prints by direction. Three carry the monitored token in their to leg with a positive ui_change_amount, so they are buys, and their combined volume_usd comes to roughly $90,000. The fourth carries the token in from with a negative ui_change_amount, a sell worth about $18,000. Net pressure over that hour reads firmly positive, around $72,000 of net buying.

Stage four keeps polling on a short interval, and ten minutes later a fifth trade lands with volume_usd near $30,000, again with the monitored token on the to side. The tracker fires immediately, since a fresh buy just landed on top of an hour that was already net positive. That alert, not the raw trade list, is the actual output of a whale tracker.

Track Your Credit Usage

Every stage above consumes API credits, and a whale tracker polling on a tight loop across several tokens can consume them faster than a one off script. Check your consumption with a single call so a short polling interval does not surprise you.

curl -s "<https://public-api.birdeye.so/utils/v1/credits>" \
  -H "X-API-KEY: YOUR_API_KEY"

Use the result to tune your polling interval and the number of tokens you watch, so coverage and cost stay in balance.

Putting It Together: Reference Architecture

The four stages chain into a loop that turns a relative threshold into a continuous live signal.

Use this checklist before you ship:

• Size every threshold from the _usd fields in the baseline, never the raw token quantity fields.
• Always set volume_type=usd explicitly, since the parameter has no default and a missing value returns a 400 error.
• Query the specific token you are monitoring, not a quote token like SOL, so the buy and sell labels read correctly.
• Sum volume_usd per direction to get net pressure instead of counting trades.
• Dedupe on the composite key, not tx_hash alone, so multi leg transactions are not collapsed.
• Watch your credit usage and tune the polling interval and watchlist size to match.

FAQ

What counts as a whale trade?

There is no universal dollar figure, since a large trade on one token is routine on another. Set the threshold relative to the token’s own baseline volume, using volume_1h_usd or volume_24h_usd from the trade data endpoint, rather than a single number applied across every token you watch.

Which chain does this whale tracker run on?

The volume filtered trades endpoint that drives detection, classification, and polling is Solana only, so this whale tracker targets Solana. The baseline endpoint in stage one supports other chains as well, if you need the aggregate stats elsewhere.

How do you tell a buy from a sell?

Read the print relative to the token you queried. The monitored token sitting in the to leg of the trade, with a positive ui_change_amount, is a buy, and the same token sitting in from with a negative amount is a sell. Query the specific token you care about rather than a quote token, or the labels stop reading correctly.

Why does volume not match volume_usd?

The volume field is a raw token amount, and which side of the trade it reports is not fixed from print to print. Treat volume_usd as the only reliable figure for thresholds and pressure math, and use volume for display only if you need the token quantity.

How often should the whale tracker poll?

Match the interval to how fast you need to react and to your credit budget. A few seconds between calls is typical for an active token, and the credits endpoint lets you confirm what a given interval costs before you commit to it.

Can you look back at whale activity that already happened?

Yes, the same endpoint that powers live polling also answers a historical question. Set before_time and after_time to bound a past window instead of polling forward, and the response returns every whale sized print inside that range. This is useful for reviewing what drove a price move after the fact, or for backtesting a threshold before you commit to it for live monitoring.

Should one whale tracker watch several tokens at once?

Yes, and the whale tracker scales by running stages one through four per token rather than building anything new. Keep each token’s threshold tied to its own baseline instead of reusing one number across very different tokens, since a single fixed floor floods you with noise on a quiet token and misses everything on an active one. Running several polling loops in parallel adds up in credits faster than a single token does, so check the credits endpoint as you add tokens rather than after your usage has already spiked.

Can you get push alerts instead of polling?

Yes. A large trade stream is available on higher plans and removes the loop entirely. On a Premium plan, a short REST polling interval on the trades endpoint achieves the same outcome.

---

Ready to build your whale transaction tracker? Start with the Birdeye Data API and the full endpoint reference at docs.birdeye.so. For background on the network these trades settle on, see the Solana documentation.