# Portfolio

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

- Install: `npx shadcn@latest add @0xui/portfolio`
- Registry JSON: https://0xui.io/r/portfolio.json
- Source: https://github.com/fimbul-lab/0xui/blob/main/registry/default/components/portfolio.tsx

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.

Tokens use the [token list standard](https://0xui.io/getting-started/token-lists.md). The demo uses a short fixed list and fixed [holdings](#tokens-from-your-indexer), 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.

## Installation

```bash
npx shadcn@latest add @0xui/portfolio
```

## Usage

```tsx
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`.

## Prices

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

```tsx
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.

## Spam

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.

### Adding your own verdicts

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:

```tsx
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`](https://0xui.io/getting-started/token-lists.md) removes tokens everywhere, not just here, and `minValue={0}` with `hideUnpriced={false}` turns hiding off.

> **Tip: In production**
>
> Over RPC, a portfolio costs one balance read per token, per user, per chain. We recommend an [index of the chain](https://0xui.io/getting-started/indexed-data.md), either your own (Postgres + ClickHouse) or a service like Goldsky. Pass its balances in:
>
> ```tsx
> <Portfolio tokens={tokens} address={address} balances={balancesFromYourIndex} prices={prices} />
> ```

## Tokens from your indexer

`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`:

```tsx
<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:

```tsx
<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.

```tsx
<Portfolio holdings={holdings} prices={pricesByAddress} showUnlisted />
```

## States

| `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.

## Props

| 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. |
