NEAR RPC Calls

Metapool utilities for querying historical NEAR blockchain data using archival RPC endpoints.

Features

• Query account balances at specific historical blocks
• Query validator stakes at specific epochs
• Automatic retry and failover between multiple RPC providers
• Converts yoctoNEAR to human-readable NEAR amounts

Installation

npm install

Commands

Balance at Block

Query an account's balance at a specific historical block height.

Usage:

npm run balance-at-block <account_id> <block_height>

Example:

npm run balance-at-block bisontrails2.poolv1.near 183318705

Sample Results:

Block Height	Account Balance	Staked Balance	Notes
183270236	9,541.23 NEAR	31,553,713.64 NEAR	✓ Success
183318705	9,541.28 NEAR	31,554,978.11 NEAR	✓ Success
183361803	10,592.70 NEAR	31,555,181.31 NEAR	✓ Success
183405043	10,741.10 NEAR	31,556,307.47 NEAR	✓ Success
183444893	-	-	⚠️ Garbage collected

Note: Block 183444893 is too old and has been garbage collected on most nodes. Use a dedicated archival node for very old blocks.

What it does:

• Queries the specified NEAR account (bisontrails2.poolv1.near)
• At the specific block height (183318705)
• Uses NEAR archival RPC endpoints with automatic retry/fallback

Output:

📊 Account Balance for "bisontrails2.poolv1.near" at block 183318705:
Block Height: 183318705
Account Balance: [amount] NEAR
Staked Balance: [amount] NEAR

The command displays:

• Block Height: Confirms the block that was queried
• Account Balance: Total NEAR tokens (converted from yoctoNEAR)
• Staked Balance: Locked NEAR tokens used for staking

Use cases:

• Analyze historical validator balances
• Track staking activity at specific points in time
• Audit account states for historical analysis

Balance at Epoch

Query a validator's stake at a specific historical epoch.

Usage:

npm run balance-at-epoch <validator_id> <epoch>

Example:

npm run balance-at-epoch bisontrails2.poolv1.near 4016

Technical Details

RPC Endpoints

The utilities use multiple archival RPC endpoints with automatic failover:

• https://archival-rpc.mainnet.near.org - Official NEAR archival
• https://rpc.mainnet.near.org - NEAR mainnet
• https://near.lava.build - Lava Network

Data Conversion

Balances are returned in yoctoNEAR (1 NEAR = 10^24 yoctoNEAR) and converted to human-readable NEAR amounts using the yton.ts utility.

Development

Build the TypeScript code:

npm run build

License

ISC

Author

lucio@metapool.app