search_near_fungible_tokens
Search NEAR blockchain for fungible token contract details using specific account ID, symbol, or name terms. Limit results to manage API load efficiently.
Instructions
Search for fungible token contract information for the NEAR blockchain, based on search terms. This tool works by 'grepping' through a list of contract information JSON objects. Be careful with this tool, it can return a lot of results. Ensure that your query is specific.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accountIDSearchTerm | No | The grep-like search term to use for finding fungible token contract information by account ID. | |
| maxNumberOfResults | No | The maximum number of results to return. This is a limit to the number of results returned by the API. Keep this number low to avoid overwhelming the API. | |
| nameSearchTerm | No | The grep-like search term to use for finding fungible token contract information by name. | |
| symbolSearchTerm | No | The grep-like search term to use for finding fungible token contract information by symbol. |
Implementation Reference
- src/services.ts:803-855 (handler)Handler function that searches for fungible tokens using searchFungibleTokens helper, enriches results with contract info from getFungibleTokenContractInfo, and returns formatted content.
async (args, __) => { const tokenContractsSearchResult = await searchFungibleTokens( args.accountIDSearchTerm, args.symbolSearchTerm, args.nameSearchTerm, args.maxNumberOfResults, ); if (!tokenContractsSearchResult.ok) { return { content: [ { type: 'text', text: `Error: ${tokenContractsSearchResult.error}`, }, ], }; } const tokenContracts = tokenContractsSearchResult.value; // get the contract info for each contract const contractInfoResults = await mapSemaphore( tokenContracts, 4, async ( contract, ): Promise<[string, FungibleTokenContract, Result<object, Error>]> => { return [ contract.contract, contract, await getFungibleTokenContractInfo(contract.contract), ]; }, ); const contractInfos = contractInfoResults.map( ([_, contract, contractInfoResult]) => { if (contractInfoResult.ok) { return contractInfoResult.value; } else { return contract; } }, ); return { content: [ { type: 'text', text: stringify_bigint(contractInfos), }, ], }; }, - src/services.ts:775-802 (schema)Zod input schema defining parameters for searching fungible tokens: optional search terms for account ID, symbol, name, and max results.
{ accountIDSearchTerm: z .string() .optional() .describe( 'The grep-like search term to use for finding fungible token contract information by account ID.', ), symbolSearchTerm: z .string() .optional() .describe( 'The grep-like search term to use for finding fungible token contract information by symbol.', ), nameSearchTerm: z .string() .optional() .describe( 'The grep-like search term to use for finding fungible token contract information by name.', ), maxNumberOfResults: z .number() .min(1) .max(8) .default(4) .describe( 'The maximum number of results to return. This is a limit to the number of results returned by the API. Keep this number low to avoid overwhelming the API.', ), }, - src/services.ts:770-856 (registration)MCP tool registration call including name, description, input schema, and handler function.
'search_near_fungible_tokens', noLeadingWhitespace` Search for fungible token contract information for the NEAR blockchain, based on search terms. This tool works by 'grepping' through a list of contract information JSON objects. Be careful with this tool, it can return a lot of results. Ensure that your query is specific.`, { accountIDSearchTerm: z .string() .optional() .describe( 'The grep-like search term to use for finding fungible token contract information by account ID.', ), symbolSearchTerm: z .string() .optional() .describe( 'The grep-like search term to use for finding fungible token contract information by symbol.', ), nameSearchTerm: z .string() .optional() .describe( 'The grep-like search term to use for finding fungible token contract information by name.', ), maxNumberOfResults: z .number() .min(1) .max(8) .default(4) .describe( 'The maximum number of results to return. This is a limit to the number of results returned by the API. Keep this number low to avoid overwhelming the API.', ), }, async (args, __) => { const tokenContractsSearchResult = await searchFungibleTokens( args.accountIDSearchTerm, args.symbolSearchTerm, args.nameSearchTerm, args.maxNumberOfResults, ); if (!tokenContractsSearchResult.ok) { return { content: [ { type: 'text', text: `Error: ${tokenContractsSearchResult.error}`, }, ], }; } const tokenContracts = tokenContractsSearchResult.value; // get the contract info for each contract const contractInfoResults = await mapSemaphore( tokenContracts, 4, async ( contract, ): Promise<[string, FungibleTokenContract, Result<object, Error>]> => { return [ contract.contract, contract, await getFungibleTokenContractInfo(contract.contract), ]; }, ); const contractInfos = contractInfoResults.map( ([_, contract, contractInfoResult]) => { if (contractInfoResult.ok) { return contractInfoResult.value; } else { return contract; } }, ); return { content: [ { type: 'text', text: stringify_bigint(contractInfos), }, ], }; }, ); - src/utils.ts:262-339 (helper)Helper function that fetches token list from Ref Finance API and filters by account ID, symbol, or name using regex, limiting results.
export const searchFungibleTokens = async ( accountIDSearchTerm: string | undefined, symbolSearchTerm: string | undefined, nameSearchTerm: string | undefined, maxNumberOfResults: number, ): Promise<Result<FungibleTokenContract[], Error>> => { try { const url = 'https://api.ref.finance/list-token'; const response = await fetch(url); const data = (await response.json()) as Record< string, { spec: string; name: string; symbol: string; icon: string; reference: string; reference_hash: string; decimals: number; } >; if (!Object.keys(data).length) { return { ok: false, error: new Error('No tokens found'), }; } // Filter tokens based on search term const filteredTokens = Object.entries(data) .filter(([contractId, tokenInfo]) => { // filter by account ID if ( accountIDSearchTerm && !new RegExp(accountIDSearchTerm, 'i').test(contractId) ) { return false; } // filter by symbol if ( symbolSearchTerm && !new RegExp(symbolSearchTerm, 'i').test(tokenInfo.symbol) ) { return false; } // filter by name if ( nameSearchTerm && !new RegExp(nameSearchTerm, 'i').test(tokenInfo.name) ) { return false; } return true; }) .slice(0, maxNumberOfResults) .map(([contractId, tokenInfo]) => ({ contract: contractId, ...tokenInfo, })); if (filteredTokens.length === 0) { return { ok: false, error: new Error('No matching tokens found'), }; } return { ok: true, value: filteredTokens, }; } catch (error) { return { ok: false, error: error as Error }; } }; - src/utils.ts:341-379 (helper)Supporting helper that fetches additional fungible token contract details from NearBlocks API.
export const getFungibleTokenContractInfo = async ( contractId: string, ): Promise<Result<object, Error>> => { try { const url = `https://api.nearblocks.io/v1/fts/${contractId}`; const response = await fetch(url); const data = (await response.json()) as { contracts?: { contract: string; name: string; symbol: string; decimals: number; description: string; website: string; }[]; }; const contracts = data?.contracts; if (!contracts) { return { ok: false, error: new Error('No fungible token contracts found'), }; } const contractInfo = contracts.map((contract) => ({ contract: contract.contract, name: contract.name, symbol: contract.symbol, decimals: contract.decimals, description: contract.description, website: contract.website, })); return { ok: true, value: contractInfo, }; } catch (error) { return { ok: false, error: error as Error }; } };