{"id":41567,"library":"near-amount-formatter","title":"NEAR Amount Formatter","description":"A utility package for formatting and parsing NEAR Protocol token amounts, supporting conversion between yoctoNEAR and NEAR, as well as generic ERC-20-like tokens. Version 1.0.0 is stable, with minimal API surface covering five functions. It differentiates by focusing exclusively on NEAR blockchain, providing both simple formatting and asynchronous balance retrieval from the network.","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","near","blockchain","web3"],"install":[{"cmd":"npm install near-amount-formatter","lang":"bash","label":"npm"},{"cmd":"yarn add near-amount-formatter","lang":"bash","label":"yarn"},{"cmd":"pnpm add near-amount-formatter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for getFormattedBalance and getFormattedTokenBalance to interact with NEAR RPC","package":"near-api-js","optional":false}],"imports":[{"note":"Package is ESM-only; named import from default export","wrong":"const formatNearAmount = require('near-amount-formatter').formatNearAmount","symbol":"formatNearAmount","correct":"import { formatNearAmount } from 'near-amount-formatter'"},{"note":"Works with string inputs only; returns string yocto amount","symbol":"parseNearAmount","correct":"import { parseNearAmount } from 'near-amount-formatter'"},{"note":"Async function that requires near-api-js to be installed","wrong":"import nearAmountFormatter from 'near-amount-formatter'","symbol":"getFormattedBalance","correct":"import { getFormattedBalance } from 'near-amount-formatter'"},{"note":"For generic token amounts; tokenDecimals must match contract precision","wrong":"import { formatTokenAmount } from 'near-amount-formatter/dist/index'","symbol":"formatTokenAmount","correct":"import { formatTokenAmount } from 'near-amount-formatter'"},{"note":"Async: requires contractId and accountId; returns raw and formatted strings","symbol":"getFormattedTokenBalance","correct":"import { getFormattedTokenBalance } from 'near-amount-formatter'"}],"quickstart":{"code":"import { formatNearAmount, parseNearAmount, getFormattedBalance } from 'near-amount-formatter';\n\nconst yocto = '1000000000000000000000000';\nconst near = formatNearAmount(yocto, 5);\nconsole.log('Formatted NEAR:', near); // '1.00000'\n\nconst parsedYocto = parseNearAmount('1.5');\nconsole.log('Parsed yocto:', parsedYocto); // '1500000000000000000000000'\n\n// Requires near-api-js and a connection to NEAR network\n// const balance = await getFormattedBalance('alice.near');\n// console.log('Balance:', balance);","lang":"typescript","description":"Shows how to format yoctoNEAR to NEAR, parse NEAR to yoctoNEAR, and fetch an account balance (async)."},"warnings":[{"fix":"Update package name in package.json and imports: 'near-amount-formatter'","message":"NearAmountFormatter renamed to near-amount-formatter in v1.0.0","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Use { contractId, accountId, tokenDecimals, displayDecimals } object","message":"getFormattedTokenBalance contract parameter changed from string to object in v0.5.0","severity":"deprecated","affected_versions":">=0.5.0 <1.0.0"},{"fix":"Always pass a string: parseNearAmount('1.5'), not parseNearAmount(1.5)","message":"parseNearAmount expects string input, not number","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Use decimals param to control fractional places; default is 5","message":"formatNearAmount returns a string with trailing zeros based on decimals parameter","severity":"gotcha","affected_versions":">=0.0.0"},{"fix":"Install near-api-js@2.x as a dependency","message":"getFormattedBalance and getFormattedTokenBalance require near-api-js v2.x exactly","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'-20':26 '1.0.0':30 'amount':2,14 'api':35 'asynchron':53 'balanc':54 'blockchain':47,61 'convers':16 'cover':37 'differenti':41 'erc':25 'exclus':44 'five':38 'focus':43 'format':8,51 'formatt':3 'function':39 'generic':24 'javascript':59 'like':27 'minim':34 'near':1,11,20,46,60 'network':58 'packag':6 'pars':10 'protocol':12 'provid':48 'retriev':55 'simpl':50 'stabl':32 'support':15 'surfac':36 'token':13,28 'util':5 'version':29 'web3':62 'well':22 'yoctonear':18","created_at":"2026-06-04T18:53:02.541005+00:00","updated_at":"2026-06-04T18:53:02.541005+00:00","problems":[{"fix":"Use import instead of require() in your project's ESM context or switch to dynamic import","cause":"Using CommonJS require() with ESM-only package","error":"ERR_REQUIRE_ESM: require() of ES Module not supported"},{"fix":"Use import { parseNearAmount } from 'near-amount-formatter'","cause":"Incorrect import: using default import instead of named import","error":"TypeError: parseNearAmount is not a function"},{"fix":"Install near-api-js and check that your environment has access to NEAR RPC endpoints","cause":"Missing near-api-js or network misconfiguration","error":"Error: Could not connect to NEAR RPC at https://rpc.mainnet.near.org"},{"fix":"Run npm install near-amount-formatter","cause":"Package not installed or package.json missing","error":"Cannot find module 'near-amount-formatter'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"near-amount-formatter","openapi_spec":null,"status_page":null,"smithery":null,"categories":["blockchain"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-04","next_check":"2026-09-02","install_tag":null}}