> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fomoscan.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet labels

> Name the trader behind a wallet in a trade feed, holder list or alert.

**For:** trade feeds, holder tables, whale alerts and copy-trading tools.

A raw address becomes `@tradername` with an avatar and an X link, so a user
sees who bought before they decide to follow. Only verified matches come back.
A label is never a guess.

## How it works

1. Your feed already holds the wallet address of each trade.
2. The backend asks `GET /v2/user/wallet/{address}` once per address and
   caches the answer.
3. The UI renders the label next to the trade row.

## Starter code

```js labels.js theme={null}
const API = "https://api.fomoscan.sh";
const headers = { Authorization: `Bearer ${process.env.FOMOSCAN_KEY}` };
const cache = new Map();
const HIT_TTL = 24 * 60 * 60_000;
const MISS_TTL = 60 * 60_000;

export async function labelFor(address) {
  const cached = cache.get(address);
  if (cached && cached.expires > Date.now()) return cached.label;

  const res = await fetch(`${API}/v2/user/wallet/${address}`, { headers });
  let label = null;
  if (res.ok) {
    const user = await res.json();
    label = {
      id: user.id,
      handle: user.handle,
      name: user.name,
      avatar: user.profilePicture,
      twitter: user.twitter,
    };
  } else if (res.status !== 404) {
    throw new Error(`FomoScan ${res.status}`);
  }

  cache.set(address, { label, expires: Date.now() + (label ? HIT_TTL : MISS_TTL) });
  return label;
}
```

```js theme={null}
const label = await labelFor(trade.wallet);
row.trader = label ? `@${label.handle}` : shorten(trade.wallet);
```

## Details that matter

* **Store `id`, display `handle`.** Handles get renamed. The id stays.
* **A `404` means no verified link today**, and costs 200 CU. Cache it for an
  hour and ask again later.
* **A found wallet costs 30,000 CU** and counts as a reveal. Label the wallets
  a user sees, such as the visible rows or trades above a size, rather than
  every address in the stream.
* Persist the cache in Redis or your database so a restart does not pay for the
  same wallets twice.

> **Build it with us**
>
> We build these projects together with the teams that ship them. Tell us what
> you are building on [Telegram](https://t.me/fomoscan_support) or at
> [fomoscan-support@proton.me](mailto:fomoscan-support@proton.me) and we will
> help you scope it, size the credits and get it live.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.