# Tokens

## Smart-money holders of a token (tracked traders)

`stalkchain_fomo_token_holders` · **250 credits**

> Ask: *"Which tracked traders hold DEED?"*

GET /token/{address}/holders - which TRACKED the provider traders hold a token, ranked by USD value: (For the COUNT and the smart-money share of all holders, prefer stalkchain_fomo_kol_holders.) {handle, amount, valueUsd, priceUsd}. This is the 'which KOLs hold it' list. 250 credits. Populated from captured balances; available:false = nothing captured for this token yet. For a count + concentration summary use stalkchain_fomo_kol_holders instead.

| Input | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Token contract address (EVM 0x... or Solana mint) |
| `limit` | integer | no |  |

REST: `POST /api/v1/tools/stalkchain_fomo_token_holders` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_token_holders?…`.

## Deployer & insider positions on a token (rug signal)

`stalkchain_fomo_token_devs` · **250 credits**

> Ask: *"Is the DEED dev still holding, or dumping?"*

The deployer and insiders of a token with their own positions. Answers 'are the insiders still in or did they exit', 'did the dev sell'. handle, wallet, isDev, amount, valueUsd, costBasisUsd, realized/unrealized PnL, averageEntryPrice, averageHoldTimeSeconds, tradeId, and the dev's own written thesis. A dev closing their bag shows here first. An EMPTY list means the provider knows of no dev holding, NOT that the token is safe. 250 credits.

| Input | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Token contract address (EVM 0x... or Solana mint) |
| `chain` | string or number | no | Chain name (robinhood\|solana\|base\|bsc\|eth\|monad) or raw networkId. Only needed for tokens outside the provider's directory (else 400). |

REST: `POST /api/v1/tools/stalkchain_fomo_token_devs` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_token_devs?…`.

## Token buy/sell flow + holder concentration

`stalkchain_fomo_token_stats` · **250 credits**

> Ask: *"Buy vs sell flow on DEED over the last hour and day."*

How many buys versus sells on this token, and how concentrated are the holders. Buy/sell flow and pressure per window — use for one named token; to compare which tokens several traders entered use stalkchain_fomo_multi_trader_entries. Windows {5m,1h,4h,24h} each with buys, sells, uniqueBuyers, uniqueSellers, buyVolumeUsd, sellVolumeUsd, netVolumeUsd, buySellRatio; plus total holders and top10HoldersPercent. This is the volume/flow tool ('who was pushing it'). 250 credits.

| Input | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Token contract address (EVM 0x... or Solana mint) |
| `chain` | string or number | no | Chain name (robinhood\|solana\|base\|bsc\|eth\|monad) or raw networkId. Only needed for tokens outside the provider's directory (else 400). |

REST: `POST /api/v1/tools/stalkchain_fomo_token_stats` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_token_stats?…`.

## OHLCV candles (where the data plan includes them)

`stalkchain_fomo_token_candles` · **250 credits** · Growth-plan upstream only.

> Ask: *"Hourly candles for DEED."*

Price chart data for a token — OHLCV candles for charting or technical analysis, down to 1-second resolution. resolution: 1S\|15S\|30S\|1\|5\|15\|30\|60\|240\|720\|1D\|7D (minutes unless suffixed). Only answers where this deployment's data plan includes candles; otherwise it returns 402/403. When candles are not available, for a price series use stalkchain_price_history (any chain, daily/hourly/5-minute); for the current price stalkchain_token_prices_multichain, or stalkchain_fomo_search (priceUsd, marketCapUsd).

| Input | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Token contract address (EVM 0x... or Solana mint) |
| `resolution` | string | no | e.g. 1, 5, 60, 1D, 15S |
| `countBack` | integer | no |  |
| `from` | string or number | no |  |
| `to` | string or number | no |  |
| `chain` | string or number | no | Chain name (robinhood\|solana\|base\|bsc\|eth\|monad) or raw networkId. Only needed for tokens outside the provider's directory (else 400). |
| `fill` | boolean | no | Emit empty buckets too |

REST: `POST /api/v1/tools/stalkchain_fomo_token_candles` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_token_candles?…`.

## Several traders hitting one token (computed live)

`stalkchain_fomo_coordinated_activity` · **125 credits**

> Ask: *"Which tokens did several tracked traders buy in the last hour?"*

Are several traders piling into the same coin at once — a coordination and herding signal computed live. Use when the question is whether a move looks coordinated or organic; for a plain list of tokens with 3+ buyers in a window use stalkchain_fomo_multi_trader_entries. Which tokens several DISTINCT tracked traders bought (or sold) inside a window. Computed from the live alert firehose (125 credits), because the upstream activity board stopped updating on 2026-08-23. That board is still tried with a short 8 s budget and appended as `providerBoard` when it answers. Same output shape as stalkchain_fomo_multi_trader_entries.

| Input | Type | Required | Description |
|---|---|---|---|
| `side` | `buy` \| `sell` | no |  |
| `minTraders` | integer | no | Default 3 |
| `windowMinutes` | number | no | Default 60 |
| `chain` | string | no |  |
| `limit` | integer | no |  |

REST: `POST /api/v1/tools/stalkchain_fomo_coordinated_activity` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_coordinated_activity?…`.

## How many / which tracked traders (KOLs) hold a token

`stalkchain_fomo_kol_holders` · **500 credits**

> Ask: *"How many KOLs hold DEED on Robinhood Chain?"*

How many tracked traders and KOLs hold this token, and what share of all holders is smart money. Answers 'do the KOLs have bags in this', 'is smart money in this ticker'. Use for who HOLDS it now; for who has been SELLING use stalkchain_fomo_kol_sell_pressure. Reads the tracked holders (FOMO traders holding it, by USD value) and the token's stats (total holders, top10HoldersPercent, 24h flow). Returns trackedHolderCount, trackedValueUsd, trackedShareOfHoldersPct (tracked / total holders), concentration, and the top holders. Percentage of SUPPLY is not derivable (the provider exposes no supply); percentage of holders is. ~500 credits (250 without stats).

| Input | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Token contract address (EVM 0x... or Solana mint) |
| `chain` | string or number | no | Chain name or networkId; only needed for tokens outside the provider's directory |
| `includeStats` | boolean | no | Default true |
| `limit` | integer | no | Top holders to list (default 20) |

REST: `POST /api/v1/tools/stalkchain_fomo_kol_holders` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_kol_holders?…`.

## Share of tracked holders that sold a token recently

`stalkchain_fomo_kol_sell_pressure` · **375 credits**

> Ask: *"What share of CATE's KOL holders sold today?"*

Are the KOLs dumping this token. What share of the tracked holders have sold or exited recently, who sold, and who is still holding. Use when asked about selling, dumping, exiting or distribution; for who currently holds it use stalkchain_fomo_kol_holders. Combines the current tracked holders with recent sell alerts filtered to this token. A trader who sold EVERYTHING is no longer in the holder list, so the denominator is currentHolders + fullyExitedSellers. Returns sellersPct, whether thresholdPercent was crossed, who sold (with realized PnL from the alert), and who still holds. ~375 credits. Coverage is bounded by the alert ring (100 sells per call); the response states the time range actually covered.

| Input | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Token contract address (EVM 0x... or Solana mint) |
| `windowMinutes` | number | no | Look-back (default 1440 = 24h). Coverage is bounded by the newest 100 sell alerts; the response states the range actually covered. |
| `thresholdPercent` | number | no | Alert threshold (default 10) |
| `chain` | string | no |  |

REST: `POST /api/v1/tools/stalkchain_fomo_kol_sell_pressure` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_kol_sell_pressure?…`.

## One-call token analysis (flow, holders, devs, theses)

`stalkchain_fomo_analyze_token` · **750 credits** · +1,250 with includeTheses.

> Ask: *"Analyze DEED: flow, holders, devs, risks."*

Full research writeup on one COIN in a single call — the memo for a token, not a person (for a person use stalkchain_fomo_trader_report). Everything about one token in a single call — the default door for 'tell me about this coin', 'is this worth buying', 'research this token'. Prefer this over chaining stalkchain_fomo_token_stats + stalkchain_fomo_token_holders + stalkchain_fomo_token_devs, which costs more and tells you less. Research memo covering buy/sell flow over 5m/1h/4h/24h, total holders + top10 concentration, tracked smart-money holders, deployer/insider positions with rug flags, and (optional) the most-liked theses explaining WHY traders are in. Costs ~750 credits (stats+holders+devs), +1,250 with includeTheses. Pass chain for tokens outside the provider's directory. For a trending scan use stalkchain_fomo_trending_analysis.

| Input | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Token contract address (EVM 0x... or Solana mint) |
| `chain` | string or number | no | Chain name or networkId; only needed for tokens outside the provider's directory |
| `includeTheses` | boolean | no | Add most-liked theses (+1,250 credits) |
| `includeDevs` | boolean | no | Default true |

REST: `POST /api/v1/tools/stalkchain_fomo_analyze_token` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_analyze_token?…`.

## Find and analyze trending / graduated tokens

`stalkchain_fomo_trending_analysis` · **2,500 credits** · 250 + ~750 per token analyzed (default 3).

> Ask: *"Find and analyze the newest trending tokens."*

Find what is trending right now and analyse it in one step. Use when no specific token is named and the ask is to go find something; when the user already has a coin, use stalkchain_fomo_analyze_token. Reads a token board (trending \| graduated \| most-held) then runs stalkchain_fomo_analyze_token on the top N (default 3, max 5). Cost: 250 + ~750 per token (+1,250 per token with includeTheses) - a 5-token scan with theses is ~10,250 credits, so keep N small on a tight budget. Filter by chain/marketCap to focus.

| Input | Type | Required | Description |
|---|---|---|---|
| `board` | `trending` \| `graduated` \| `most-held` | no | Default trending |
| `topN` | integer | no | Default 3 |
| `chain` | string | no | Only tokens whose board 'network' matches this name/id |
| `maxMarketCapUsd` | number | no | Skip tokens above this market cap (find early ones) |
| `includeTheses` | boolean | no |  |

REST: `POST /api/v1/tools/stalkchain_fomo_trending_analysis` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_trending_analysis?…`.

## Top traders holding tokens X, Y, Z

`stalkchain_fomo_top_traders_for_tokens` · **1,000 credits** · 250 per token + 250 leaderboard.

> Ask: *"Who are the top traders in PONS, DEED and CACHE?"*

Who are the best traders holding these several tokens. Use for 2-5 tokens at once; for one token's holders use stalkchain_fomo_kol_holders. For each token (max 5) reads the tracked holders, unions them, and joins the leaderboard for the chosen window to attach rank and pnlUsd. Ranked by number of the given tokens held, then leaderboard PnL, then value held. 250 credits per token + 250 for the leaderboard. Wallets come from the leaderboard row when the trader is on it; otherwise use stalkchain_fomo_search (250) rather than stalkchain_fomo_resolve_trader (2,500).

| Input | Type | Required | Description |
|---|---|---|---|
| `tokens` | array of string | yes | Token contract addresses |
| `window` | `24h` \| `7d` \| `30d` \| `all` | no | Leaderboard window to rank by (default 7d) |
| `limit` | integer | no | Default 25 |

REST: `POST /api/v1/tools/stalkchain_fomo_top_traders_for_tokens` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_top_traders_for_tokens?…`.

## Who launched this token, and when (best effort)

`stalkchain_fomo_token_launch_research` · **500 credits** · Up to ~1,000 with dev trade details.

> Ask: *"Who launched this coin and when?"*

Answers 'who launched this coin and when?' from the social-trading data: the token's dev list gives the deployer and insider handles, wallets, positions and their own thesis; the dev's trade is then opened to read when their position was opened (a proxy for launch time) and whether they have sold. Adds the token's stats for age context. ~500-1,000 credits. If no dev is known, the result says so; for the on-chain deployer of a Solana token use stalkchain_token_deployer.

| Input | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Token contract address (EVM 0x... or Solana mint) |
| `chain` | string or number | no | Chain name or networkId; only needed for tokens outside the provider's directory |

REST: `POST /api/v1/tools/stalkchain_fomo_token_launch_research` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_token_launch_research?…`.

## Compact token snapshot (store it, diff later)

`stalkchain_fomo_token_snapshot` · **500 credits**

> Ask: *"Snapshot DEED's holders so I can compare tomorrow."*

Answers 'how do this token's holders change over time' - the provider has no history endpoint, so take snapshots and diff them with stalkchain_fomo_compare_snapshots. Returns {capturedAt, priceUsd, marketCapUsd, totalHolders, top10HoldersPercent, trackedHolders[{handle, amount, valueUsd}], flow24h}; price and market cap are live at capturedAt. ~500 credits. Save the JSON in your own store (file, DB) and call again later.

| Input | Type | Required | Description |
|---|---|---|---|
| `address` | string | yes | Token contract address (EVM 0x... or Solana mint) |
| `chain` | string or number | no | Chain name or networkId; only needed for tokens outside the provider's directory |
| `holdersLimit` | integer | no | Default 50 |

REST: `POST /api/v1/tools/stalkchain_fomo_token_snapshot` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_token_snapshot?…`.

## Diff two token snapshots (local, 0 credits)

`stalkchain_fomo_compare_snapshots` · **free**

> Ask: *"Compare yesterday's and today's DEED snapshots."*

Pure local diff of two stalkchain_fomo_token_snapshot outputs: new tracked holders, exited holders, who increased/decreased their bag, change in total holders, top10 concentration and price. No API call.

| Input | Type | Required | Description |
|---|---|---|---|
| `before` | object | yes |  |
| `after` | object | yes |  |

REST: `POST /api/v1/tools/stalkchain_fomo_compare_snapshots` with the inputs as a JSON body, or `GET /api/v1/tools/stalkchain_fomo_compare_snapshots?…`.