# Tokens and chains

Fin names tokens by their exact NEAR Intents id, such as
`nep141:17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1`, and the agent
wallet's holdings by an opaque id derived from it. `@nearai/financial-agents-react` turns those ids into what a
person reads: USDC's symbol and icon, its network and that network's badge.

## What the package carries

`DEFAULT_TOKENS` is near.com's production token list as a `TokenResolver`. Every block uses it
unless you pass your own.

| Data | Example |
| --- | --- |
| Every token near.com lists | Symbol, name, decimals, icon, chain, the group one asset's copies share across chains, and tags |
| Every network's name and badge | `eth` reads as Ethereum, with a light and a dark mark where one would vanish |
| The market listing behind each traded ticker | So an asset a reply names gets its icon even when the wallet doesn't hold it |

> [!NOTE]
> It is display data only. It never changes an amount, decimals or a price. A token the list lacks
> keeps the provider's name and stays visible. A token is never identified by its symbol, so one
> that merely shares a ticker never passes for the one you know.

## Content-Security-Policy

Network badges, data providers' logos and the few token icons near.com hosts itself are inlined
as `data:` URIs, so your app hosts nothing. Every other token icon loads from its public CDN.
If your page sets a Content-Security-Policy, allow them in `img-src`:

```http
Content-Security-Policy: img-src 'self' data: https://s2.coinmarketcap.com https://assets.coingecko.com https://cdn.ondo.finance https://dd.dexscreener.com https://ipfs.sintral.me https://near-intents.org
```

Drawing a reply asks no other third party for anything: a link to any other site shows its host
beside a plain glyph.

## Draw a token

`TokenIcon` draws a token's disc, badged with its network. Read its metadata from the configured
list:

```tsx title="token-label.tsx"
import { TokenIcon } from "@nearai/financial-agents-react";
import { assetChain, getTokenMetadata } from "@nearai/financial-agents-react/model";

export function TokenLabel({ tokenId }: { tokenId: string }) {
  const token = getTokenMetadata(tokenId);
  return (
    <span>
      <TokenIcon
        symbol={token?.symbol ?? "?"}
        iconUrl={token?.icon ?? null}
        size={20}
        network={assetChain(tokenId)}
      />
      {token?.symbol ?? tokenId}
    </span>
  );
}
```

For a holding from `wallets.balances`, `AssetIcon` does this for you, and `holdingDisplay`
returns the holding with the list's name, icon and network.

## Fin's opaque holding ids

Holdings carry Fin's opaque `asset_…` ids, never token ids. `catalogTokenId` finds the token
behind one when the list carries it; `finAssetId` derives Fin's id for a token, exactly as Fin does:

```ts
import { catalogTokenId, finAssetId } from "@nearai/financial-agents-react/model";

const assetId = finAssetId("nep141:wrap.near");
console.log(catalogTokenId(assetId)); // "nep141:wrap.near"
```

## Assets on portfolio rows

[Get portfolio](/wallet-transfers#portfolio-and-its-history) holds assets from every account the
agent owns, so each row's `asset` says which kind of asset it is:

| `kind` | Field | What it is |
| --- | --- | --- |
| `token` | `assetId` | An agent wallet asset, by the same `asset_…` id Get balances uses |
| `solana` | `mint` | A token in the agent's Solana account, by its mint address |
| `sol` | none | Native SOL in the agent's Solana account |
| `polymarket` | `tokenId` | Shares of a Polymarket outcome, by the `assetId` prediction orders use |
| `usd` | none | US dollars: perps account equity, or Polymarket's pUSD |

The row's `account` says where it is held, so two `usd` rows in different accounts are different
holdings. `symbol` is `null` when no source names the asset, as for a Polymarket outcome: show your
own label, such as the market's outcome. A Solana token's `iconUrl` is the path of
[Get a token icon](/api-reference/solana/get-token-icon) on Fin's API.

## Networks

| Function | Returns |
| --- | --- |
| `assetChain(tokenId)` | The chain a token comes from: the list's, or for a token it lacks, the one a canonical bridge id names (`nep141:eth-…`, `base-`, `arb-`, `sol-`). `null` otherwise, never a guess. |
| `assetNetwork(tokenId)` | That chain's display name, such as `Ethereum`. |
| `tokenNetworkName(chain)` | A chain key's display name; an unknown key reads as it is. |
| `networkIcon(chain)` | A chain's badge as `{ light, dark }`, or `null`. |

## Use your own token list

Pass your own `TokenResolver` to `FinUIProvider`, and on a server to `configureFinUI`. It
replaces near.com's list. To add tokens to near.com's list instead, wrap it:

```tsx title="fin-tokens.tsx"
import { FinUIProvider, type TokenInfo, type TokenResolver } from "@nearai/financial-agents-react";
import { DEFAULT_TOKENS } from "@nearai/financial-agents-react/model";
import type { ReactNode } from "react";

const MY_TOKENS = new Map<string, TokenInfo>([
  [
    "nep141:token.example.near",
    {
      tokenId: "nep141:token.example.near",
      symbol: "EXM",
      name: "Example",
      decimals: 18,
      icon: "https://example.com/exm.svg",
      chain: "near",
      unifiedAssetId: null,
      tags: [],
    },
  ],
]);

const tokens: TokenResolver = {
  ...DEFAULT_TOKENS,
  token: (tokenId) => MY_TOKENS.get(tokenId) ?? DEFAULT_TOKENS.token(tokenId),
  tokenIds: () => [...MY_TOKENS.keys(), ...DEFAULT_TOKENS.tokenIds()],
};

export function FinTokens({ children }: { children: ReactNode }) {
  return <FinUIProvider tokens={tokens}>{children}</FinUIProvider>;
}
```

> [!WARNING]
> Treat a resolver as configuration: when your list changes, pass a new resolver object. Fin's
> holding ids are matched against `tokenIds()` once per object, so a list that grows behind the
> same object leaves new holdings unnamed.

| Member | Returns |
| --- | --- |
| `token(tokenId)` | A `TokenInfo`: `tokenId`, `symbol`, `name`, `decimals`, `icon` (a URL or `data:` URI), `chain`, `unifiedAssetId` and `tags`. `undefined` for a token the list lacks, which reads as its shortened id. A Solana token is named by its mint as `solana:<mint>`, since a symbol is not unique on Solana; its `chain` is `solana`, and a mint the list lacks reads as its shortened mint, in a label only, never in full. |
| `tokenIds()` | Every token id the list knows, to match Fin's holding ids. |
| `networkName(chain)` | A chain key's display name. |
| `networkIcon(chain)` | A chain's badge for light and dark, or `null`. |
| `marketId(symbol)` | Optional. A ticker's market listing id, such as its CoinGecko id. |
| `marketIcon(marketId)` | Optional. A market listing's icon. |

The `category:earn-vault` tag marks tokens near.com keeps out of its regular asset lists; Fin's
blocks show whatever the agent wallet holds. The `type:stablecoin` tag marks what prices are
counted in. A limit order that pays with a tagged token reads as a buy of the other asset, priced
per unit bought: `Buy NEAR with 10 USDC at ≤ 4 USDC per NEAR`. Without the tag, an order reads as
the sale 1Click places.
