Skip to content

Blocks

Portfolio

Token holdings with total value, sorted largest first, with spam kept out.

Holdings for a token list: total value on top, then one row per token with amount and value, largest first. Likely spam, tokens without a price and dust are collapsed under “Hidden tokens”. All balances are read in one batch.

vitalik.eth

Loading tokens

Tokens use the token list standard. The demo uses a short fixed list and fixed holdings, behind a pretend one-second load so you see the skeleton first. Open “Hidden tokens” to see one of each kind: dust, no price, likely spam and not on the list.

Terminal window
npx shadcn@latest add @0xui/portfolio
import { Portfolio } from "@/components/portfolio";
<Portfolio tokens={tokenList.tokens} prices={prices} />;

It shows the connected account’s holdings, or pass address for anyone’s. Only tokens on chainId (the current chain by default) are read.

Headless: usePortfolio({ tokens, prices }) returns the shown rows, the hidden ones (each with its reason), and the total.

Key prices by chainId:address (or plain address) when you can:

const prices = {
"1:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48": 1, // USDC on Ethereum
"1:0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE": 3150, // ETH
};

Symbol keys ({ USDC: 1 }) also work and are handy for demos, but a symbol is whatever the token’s deployer typed: a fake “USDC” would get the real one’s price. Address keys win when both are given. The same lookup, getTokenPrice(prices, token), is used by Token Select, Token Input, Send and Swap.

Wallets collect junk: airdropped tokens that advertise a “claim” site, copies of real tokens, and worthless dust. Portfolio hides a holding when, checked in this order:

Reason Shown as Rule
spam “Likely spam” isSpam(token) is true. Defaults to looksLikeSpam.
unpriced “No price” No price for the token. Turn off with hideUnpriced={false}.
dust “Under $0.50” Worth less than minValue (default 0.5).

Hidden rows are left out of the total, and listed with their reason under a collapsed “Hidden tokens (N)” so a false positive costs a click, not a missing balance. Spam rows show the symbol’s letters instead of the token’s logo. The chain’s native currency is never hidden.

Before any of this, only tokens in your list are shown at all, so tokens airdropped outside the list never appear. Spam can still come from the list itself or from tokens you add.

looksLikeSpam (from @/lib/token-list) is a cheap check for the common cases: names with links or “claim”/“airdrop”/“rewards”, a domain as the symbol, invisible characters, and Latin text mixed with lookalike letters (a Cyrillic “С” in “USDС”). It flags none of the 1,600 tokens on Uniswap’s default list. It can’t spot a well-named copy, which is why prices matter most: a copy has no price under its own address, so it’s hidden as unpriced.

For wallet-grade filtering, check tokens against a scanning service, or rules in your indexer, from your server (they need an API key), and pass the verdicts in:

const { data: flagged = new Set<string>() } = useQuery({
queryKey: ["spam", chainId, address],
queryFn: async () => {
const addresses: string[] = await fetch(`/api/spam/${chainId}/${address}`).then((r) => r.json());
return new Set(addresses.map((a) => a.toLowerCase()));
},
});
<Portfolio
tokens={tokens}
prices={prices}
isSpam={(token) => looksLikeSpam(token) || flagged.has(token.address.toLowerCase())}
/>;

Keep looksLikeSpam in the check unless you mean to replace it. Other filters: a blocklist on useTokenList removes tokens everywhere, not just here, and minValue={0} with hideUnpriced={false} turns hiding off.

balances only covers tokens on your list. An indexer usually knows more: every token the address holds, with a name, symbol and decimals. Pass those as holdings:

<Portfolio
tokens={tokens}
holdings={rows.map((row) => ({
token: { chainId: 1, address: row.token, symbol: row.symbol, name: row.name, decimals: row.decimals },
balance: BigInt(row.balance),
}))}
prices={prices}
/>

While your query runs, pass isLoading. Portfolio shows its skeleton and doesn’t read from RPC in the meantime:

<Portfolio tokens={tokens} holdings={query.data} isLoading={query.isLoading} prices={prices} />

The token list stays the allowlist. A holding on the list uses the list’s name and logo. A holding off the list goes under “Hidden tokens” as “Not on the token list”, out of the total.

Set showUnlisted to show them as normal rows instead. The spam, price and dust filters still apply. Key prices by address when you do: a price keyed by symbol also values every copy of that symbol.

<Portfolio holdings={holdings} prices={pricesByAddress} showUnlisted />
data-phase What the user sees
idle “Connect a wallet to see its tokens.”
loading A skeleton measured from the rows themselves when they are known, from three sample rows otherwise.
ready Total and rows, and “Hidden tokens (N)” when some are hidden.
empty “No tokens from this list in this wallet.”
error Couldn’t load balances.

Each row has data-hidden set to its reason when it’s hidden.

Prop Type Default Description
tokens Token[] [] Tokens to check. With holdings, the allowlist.
prices Record<string, number> — Prices by chainId:address, address or symbol.
address Address connected Whose holdings.
chainId number current Chain to read.
hideZero boolean true Hide empty balances.
isSpam (token) => boolean looksLikeSpam Flags scam tokens.
hideUnpriced boolean true Hide tokens without a price.
minValue number 0.5 Hide holdings worth less than this.
currency string "USD" Currency for values.
locale string runtime locale Locale for amounts and values. Set it when rendering on a server, so server and browser agree.
balances Record<address, bigint> — Balances from your own source. Skips RPC reads.
holdings { token, balance }[] — Holdings from your own source, with each token’s metadata. Skips RPC reads.
showUnlisted boolean false Show holdings that aren’t on tokens.
isLoading boolean false Your own balances or holdings are still loading. Shows the skeleton and skips RPC reads.
pageSize number 10 Rows per page, with “Show more”.
title ReactNode "Portfolio" Heading. null hides it.