Registry / blockchain / near-amount-formatter

near-amount-formatter

library1.0.0jsnpmunverified

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.

blockchain

npm install near-amount-formatter

package ↗

INSTALL

IMPORT

SIG · NEAR-AMOUNT-FORMAT

near-amount-formatter

blockchainjavascriptv1.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

formatNearAmount

✓ import { formatNearAmount } from 'near-amount-formatter'

✗ const formatNearAmount = require('near-amount-formatter').formatNearAmount

Package is ESM-only; named import from default export

parseNearAmount

✓ import { parseNearAmount } from 'near-amount-formatter'

Works with string inputs only; returns string yocto amount

getFormattedBalance

✓ import { getFormattedBalance } from 'near-amount-formatter'

✗ import nearAmountFormatter from 'near-amount-formatter'

Async function that requires near-api-js to be installed

formatTokenAmount

✓ import { formatTokenAmount } from 'near-amount-formatter'

✗ import { formatTokenAmount } from 'near-amount-formatter/dist/index'

For generic token amounts; tokenDecimals must match contract precision

getFormattedTokenBalance

✓ import { getFormattedTokenBalance } from 'near-amount-formatter'

Async: requires contractId and accountId; returns raw and formatted strings

Shows how to format yoctoNEAR to NEAR, parse NEAR to yoctoNEAR, and fetch an account balance (async).

import { formatNearAmount, parseNearAmount, getFormattedBalance } from 'near-amount-formatter'; const yocto = '1000000000000000000000000'; const near = formatNearAmount(yocto, 5); console.log('Formatted NEAR:', near); // '1.00000' const parsedYocto = parseNearAmount('1.5'); console.log('Parsed yocto:', parsedYocto); // '1500000000000000000000000' // Requires near-api-js and a connection to NEAR network // const balance = await getFormattedBalance('alice.near'); // console.log('Balance:', balance);

Debug

Known issues

breakingNearAmountFormatter renamed to near-amount-formatter in v1.0.0

fix

Update package name in package.json and imports: 'near-amount-formatter'

affects: <1.0.0

deprecatedgetFormattedTokenBalance contract parameter changed from string to object in v0.5.0

fix

Use { contractId, accountId, tokenDecimals, displayDecimals } object

affects: >=0.5.0 <1.0.0

gotchaparseNearAmount expects string input, not number

fix

Always pass a string: parseNearAmount('1.5'), not parseNearAmount(1.5)

affects: >=0.0.0

gotchaformatNearAmount returns a string with trailing zeros based on decimals parameter

fix

Use decimals param to control fractional places; default is 5

affects: >=0.0.0

gotchagetFormattedBalance and getFormattedTokenBalance require near-api-js v2.x exactly

fix

Install near-api-js@2.x as a dependency

affects: >=1.0.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM: require() of ES Module not supported

Using CommonJS require() with ESM-only package

fix

Use import instead of require() in your project's ESM context or switch to dynamic import

TypeError: parseNearAmount is not a function

Incorrect import: using default import instead of named import

fix

Use import { parseNearAmount } from 'near-amount-formatter'

Error: Could not connect to NEAR RPC at https://rpc.mainnet.near.org

Missing near-api-js or network misconfiguration

fix

Install near-api-js and check that your environment has access to NEAR RPC endpoints

Cannot find module 'near-amount-formatter'

Package not installed or package.json missing

fix

Run npm install near-amount-formatter

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

near-api-jsrequiredRequired for getFormattedBalance and getFormattedTokenBalance to interact with NEAR RPC

Agent activity

31 hits · last 30 days

node

OpenAI (training)

Resources

packagenear-amount-formatter ↗