> For the complete documentation index, see [llms.txt](https://thesium.gitbook.io/thesium-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thesium.gitbook.io/thesium-docs/feature-deep-dives/wallet-intelligence.md).

# Wallet Intelligence

The Holders and KOLs panels are powered by the same wallet graph, making this one of the core data assets behind Thesium.

<div><figure><img src="/files/i7gSyk98WUZ0C74Fe1un" alt=""><figcaption></figcaption></figure> <figure><img src="/files/UdkXYDJ2NgUqZDOHdUc4" alt=""><figcaption></figcaption></figure></div>

## What the wallet graph is

A graph of wallet addresses across every supported chain, annotated with:

* **Identity** - for named wallets: a display name, public handle(s), avatar URL.
* **Tier** - one of **KOL**, **Smart Money**, **Whale**, **Influencer**, or **Insider**. The qualitative classification of why this wallet matters.
* **Behavioral metadata** - historical PnL profile, average position size, hit rate, hold-time distribution, chains active on.

## How wallets enter the graph

* **Identity-first intake.** Public figures with known wallets - inserted with full identity attached and tiered as KOL or Influencer depending on the curation bar.
* **Behavior-first intake.** Wallets that meet quantitative criteria on historical performance are added as Smart Money whether or not they are publicly attributable. Many smart-money wallets remain anonymous; their on-chain track record is the credential.
* **Size-first intake.** Wallets whose typical position sizes are large enough that their entries and exits move thin markets, regardless of skill. Tiered as Whale.
* **Attribution intake.** Wallets linked behaviorally or by direct attribution to a token's deploy, dev team, or pre-launch distribution. Tiered as Insider.

A wallet can carry multiple tier eligibilities but is surfaced with a single dominant tier in the UI. Re-tiering happens continuously based on the wallet's evolving behavior.

## How positions are computed

For any (wallet, token) pair, the backend reconstructs the wallet's full position history on that token from on-chain data:

* Total tokens bought, total USD spent, count of buy transactions.
* Total tokens sold, total USD received, count of sell transactions.
* Current tokens remaining (computed, not naively trusted from current balance - the backend reconciles transfers and burns).
* Current USD value of remaining position at live price.
* Realized PnL, unrealized PnL, total PnL.
* PnL percentage on cost basis.
* Last activity timestamp.

## Why two views for "who holds this"

The **Holders** panel returns the union of tracked wallets that hold the token, in significance order. It is keyed by token mint and presents the broadest view of who's in the trade.

The **KOLs** panel narrows specifically to KOL-identity wallets that have positions in the **pool** the user is currently viewing. It is keyed by pool address rather than token mint, which matters on chains and DEXes where the same token can exist across multiple pools with different liquidity profiles - a KOL holding a different pool of the same token is a different signal from a KOL holding *this* pool.

The two views share the same underlying data but answer different questions: Holders is *"who's tracked on this token"*; KOLs is *"which named accounts care about this specific pool"*.

## Limits and honesty

The wallet graph is not omniscient. Three explicit limits:

* **Coverage decreases with chain age.** Solana, Ethereum, Base and BSC have full graph parity. Newer chains have structural wallet metrics but lighter named-wallet coverage.
* **Newly-active wallets are not retroactively tiered.** A wallet that achieves smart-money behavior over the next 30 days will not appear as smart money until the backend re-tiers it.
* **Identity is asserted, not crypto-verified.** Wallet-to-handle mappings rely on public claims, on-chain signaling, and our own attribution work. Disputed attributions are removed.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://thesium.gitbook.io/thesium-docs/feature-deep-dives/wallet-intelligence.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.