React components

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.

DataExample
Every token near.com listsSymbol, name, decimals, icon, chain, the group one asset's copies share across chains, and tags
Every network's name and badgeeth reads as Ethereum, with a light and a dark mark where one would vanish
The market listing behind each traded tickerSo 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:

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:

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:

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

kindFieldWhat it is
tokenassetIdAn agent wallet asset, by the same asset_… id Get balances uses
solanamintA token in the agent's Solana account, by its mint address
solnoneNative SOL in the agent's Solana account
polymarkettokenIdShares of a Polymarket outcome, by the assetId prediction orders use
usdnoneUS 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

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

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>;
}
MemberReturns
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.

Fin documentation Built from the API contract · v1

Search all documentation