# Traders

## Search traders and tokens

`stalkchain_fomo_search` · **250 credits**

> Ask: *"Find the trader frankdegods and give me his wallets."*

Which wallets belong to this handle — look up a trader by name or handle and get the wallet addresses that belong to them, plus userId and PnL. The cheap first step for any named person. Returns wallet addresses, userId and PnL — the cheap first step for any named person. Also finds tokens by ticker or name. For an arbitrary wallet address you already have, use stalkchain_wallet_pnl. Search by handle or display name (traders) or symbol/name (tokens). 250 credits. Trader hits already include userId, both wallets and PnL, so this is the CHEAP way to look a trader up (vs stalkchain_fomo_resolve_trader at 2,500). Token hits give address, name, networkId, and the LIVE market cap (circulating where known, with fdvUsd, priceUsd and liquidityUsd alongside; marketCapBasis says circulating or fully diluted, marketCapSource where each figure came from). Searching by userId is not supported - use stalkchain_fomo_resolve_trader for that.

| Input | Type | Required | Description |
|---|---|---|---|
| `q` | string | yes | Handle, display name, token symbol or token name |
| `type` | `traders` \| `tokens` \| `all` | no | Restrict result type (default all) |
| `limit` | integer | no |  |

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

## Resolve trader (full live profile) - 2,500 credits

`stalkchain_fomo_resolve_trader` · **2,500 credits** · Full live profile; use stalkchain_fomo_search (250) when you only need wallets and PnL.

> Ask: *"Give me everything about unipcs: wallets, PnL per window, account age, hold time."*

The complete live profile for one trader, when search is not enough. START WITH stalkchain_fomo_search (250 credits) — it already returns wallets, userId and PnL. Only come here when you need the full record. ~35 live fields: real Solana + EVM wallets, pnl {24h,7d,30d,all}, volume, trades, swapCount, followers/following, holdings count, topTokens, verified, description, clan, createdAt + accountAgeDays, averageHoldTimeSeconds, private/restricted flags. EXPENSIVE: 2,500 credits on a hit (250 on an unknown handle). If you only need wallets/userId/PnL, call stalkchain_fomo_search first (250). Result is cached 15 min. wallets.status="resolving" means try again shortly.

| Input | Type | Required | Description |
|---|---|---|---|
| `trader` | string | yes | Trader handle (case-insensitive, optional @) or userId (UUID). Prefer userId when known: handles can be renamed. |
| `fresh` | boolean | no | Bypass the cache (costs credits again) |

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

## Trader positions (open/closed, entry/exit, PnL)

`stalkchain_fomo_trader_positions` · **250 credits** · Per page; deep fan-out costs per upstream call.

> Ask: *"What positions does unipcs hold right now, with entry prices and PnL?"*

What positions does this trader hold, and what did they enter and exit at. One row per token position: status, amount, avgEntryPrice/avgExitPrice, realized/unrealized PnL, costBasisUsd, bought/sold/transferredIn/Out amounts, priceUsd, chain, createdAt/closedAt, tradeId. 250 credits per upstream call. Upstream returns all OPEN positions but only 25 most-recent CLOSED per call: use status=closed for closed history, cursor='start' then nextCursor to page, or deep=true to fan out across chains/orders in one call (up to ~12 calls = 3,000 credits; deep=N buys N calls). A full history is never obtainable from the provider (complete is always false; closedTotalUpstream tells the real total). avgEntryPrice null = tokens were received, not bought. available:false = not captured yet. Heavy accounts often time out on the plain read; the server then automatically retries with deep=2 (per-chain fetch, same 250 credits) and marks the result [fallback: deep=2].

| Input | Type | Required | Description |
|---|---|---|---|
| `trader` | string | yes | Trader handle (case-insensitive, optional @) or userId (UUID). Prefer userId when known: handles can be renamed. |
| `status` | `open` \| `closed` \| `all` | no | Narrow to open or closed. Traders with 200+ open positions hide all closed rows unless status=closed. |
| `limit` | integer | no | Rows per page (max 200) |
| `cursor` | string | no | 'start' for page 1, then the previous response's nextCursor |
| `deep` | boolean or integer | no | true = full fan-out (~12 upstream calls); N (2-12) = buy only N upstream calls |

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

## Trader fills (individual swaps)

`stalkchain_fomo_trader_swaps` · **250 credits** · Per page of 100 fills.

> Ask: *"Show the last 20 fills of unipcs."*

Every individual buy and sell this trader made, fill by fill. Answers 'every fill he has done', 'his trade history', 'all his swaps'. Use for the raw swap history rather than aggregated positions (for those use stalkchain_fomo_trader_positions). 100 per page, newest first: swapId, chain, tokenIn/tokenOut {address, amount, usd}, tradeIdIn/tradeIdOut (join to positions), at. 250 credits per page; page with cursor=nextCursor. The 100 cap is per FILTER: pass tokenAddress to reach months back for one token. deep=true re-asks per chain/token and accumulates across calls (moreAvailable/filtersRemaining say if another call helps). source='relay' reads the on-chain bridge instead (every chain in one query, usd at trade time AND usdNow, needs the trader resolved first; 409 retryable while resolving; keep calling while moreAvailable).

| Input | Type | Required | Description |
|---|---|---|---|
| `trader` | string | yes | Trader handle (case-insensitive, optional @) or userId (UUID). Prefer userId when known: handles can be renamed. |
| `limit` | integer | no |  |
| `cursor` | string | no | nextCursor from the previous page |
| `tokenAddress` | string | no | Scope to one token contract (reaches further back) |
| `deep` | boolean | no | Accumulate more fills across chain/token filters |
| `source` | `relay` | no | 'relay' = on-chain source across all chains |

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

## Tracked trader's live portfolio by handle (all chains)

`stalkchain_fomo_trader_balances` · **250 credits**

> Ask: *"What is unipcs holding across all chains, by value?"*

What is this tracked trader holding in their wallet right now, looked up by FOMO handle or userId. Answers 'what is in his bags', 'current holdings', 'what does he hold now'. For a raw wallet address, or anyone the platform does not track, use stalkchain_wallet_portfolio instead. Live portfolio and current bags across Robinhood Chain, Solana, Ethereum, Base, BSC, Monad in ONE call: token {symbol,address,networkId}, chain, amount, priceUsd, valueUsd, change24h; plus totalValueUsd, byChain rollup, and livePerpPnl / hyperliquidPerps when present. 250 credits. Use chain= to narrow. Use for portfolio concentration and 'what are they holding right now'.

| Input | Type | Required | Description |
|---|---|---|---|
| `trader` | string | yes | Trader handle (case-insensitive, optional @) or userId (UUID). Prefer userId when known: handles can be renamed. |
| `chain` | `robinhood` \| `solana` \| `base` \| `bsc` \| `eth` \| `monad` \| `hyperliquid` | no | Narrow to one chain |
| `limit` | integer | no | Max holdings rows returned (sorted by valueUsd desc) |

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

## Who a trader follows (discovery)

`stalkchain_fomo_trader_following` · **250 credits**

> Ask: *"Who does frankdegods follow, ranked by 24h PnL?"*

Which accounts does this trader follow — the OUTBOUND direction, who they watch. For their own follower count use stalkchain_fomo_trader_followers. Useful for discovering traders you had no other way to find. Each account they watch, each annotated with followers, trades, volumeUsd, pnl24h, twitter, verified, accountAgeDays. 250 credits flat. Upstream caps at 200 names (truncated/sourceCapped flag it); partial+retryable=true means call again to resume. No wallets here - resolve a handle separately. Great for finding traders you had no other way to discover.

| Input | Type | Required | Description |
|---|---|---|---|
| `trader` | string | yes | Trader handle (case-insensitive, optional @) or userId (UUID). Prefer userId when known: handles can be renamed. |
| `limit` | integer | no |  |

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

## Who follows a trader (sample of 200)

`stalkchain_fomo_trader_followers` · **250 credits**

> Ask: *"Who follows theveeman, and are they real traders?"*

How many people follow this trader, and who are they — the follower count and audience quality. This is the INBOUND direction; for the accounts they follow instead, use stalkchain_fomo_trader_following. A sample of the follower list, same per-person shape as following. Upstream serves at most 200 followers with no cursor, so this is a SAMPLE (sourceCapped=true), useful to judge the quality of a trader's backing, not to enumerate it. 250 credits flat.

| Input | Type | Required | Description |
|---|---|---|---|
| `trader` | string | yes | Trader handle (case-insensitive, optional @) or userId (UUID). Prefer userId when known: handles can be renamed. |
| `limit` | integer | no |  |

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

## Trader's best trades and best theses (FOMO's pick)

`stalkchain_fomo_trader_spotlight` · **250 credits**

> Ask: *"What are frankdegods' best trades and most-liked theses?"*

This trader's best ever trades and best written calls, as picked by the platform. The fastest way to judge someone you just came across. bestTrades[] and bestTheses[]: token, chain, entry/exit, cost basis, realized/unrealized PnL, openedAt/closedAt, the written thesis and its likes, tradeId. 250 credits. Fastest way to judge a trader you just found.

| Input | Type | Required | Description |
|---|---|---|---|
| `trader` | string | yes | Trader handle (case-insensitive, optional @) or userId (UUID). Prefer userId when known: handles can be renamed. |

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

## Research a trader before following them

`stalkchain_fomo_trader_report` · **1,000 credits** · Search + spotlight + balances + closed positions; +1,250 with theses; +2,500 with full=true.

> Ask: *"Research unipcs before I follow him."*

Should I follow or copy this trader. START HERE for any question about whether a trader is worth trusting, copying or following — it replaces four separate calls. One-call due diligence: identity + wallets + PnL windows (cheap via search when you pass a HANDLE; a userId cannot be searched and forces the 2,500-credit live profile, so prefer the handle from the leaderboard row), or full live profile with full=true at 2,500 credits), the provider's spotlight (best trades/theses), live portfolio (total value, top holdings, concentration), and a sample of closed positions (win rate, realized PnL, best/worst). Optional most-liked theses (+1,250). ~1,000 credits with full=false. Every metric states its sample size; missing data is null, never 0.

| Input | Type | Required | Description |
|---|---|---|---|
| `trader` | string | yes | Handle or userId |
| `full` | boolean | no | Use the full live profile (~35 fields, 2,500 credits) instead of search (250) |
| `includeTheses` | boolean | no | Add the trader's most-liked theses (+1,250) |
| `closedSample` | integer | no | Closed positions to sample (default 100) |

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

## Compare 2-4 traders on comparable metrics

`stalkchain_fomo_compare_traders` · **250 credits** · Per trader (2,500 each with full=true).

> Ask: *"Compare frankdegods, unipcs and theveeman."*

Side-by-side of PnL (per window when available), volume, trade count, followers, account age, verified flag and wallets. Uses search (250 each) by default; full=true uses the live profile (2,500 each) which adds pnl per window, swapCount, averageHoldTimeSeconds. Fields the provider did not return are null - never treat null as 0.

| Input | Type | Required | Description |
|---|---|---|---|
| `traders` | array of string | yes |  |
| `full` | boolean | no |  |

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