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 |
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:
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.orgDrawing 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:
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:
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 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 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:
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>;
}| 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.