getAccountInfo

Retrieve account information including balance, storage usage, and contract data

Overview

Retrieves comprehensive information about a NEAR account, including total and available balance, storage usage, and contract deployment details.

Method Signatures

Throwable Variant

client.getAccountInfo(args: GetAccountInfoArgs): Promise<GetAccountInfoOutput>

Throws an error if the operation fails.

Safe Variant

client.safeGetAccountInfo(args: GetAccountInfoArgs): Promise<Result<GetAccountInfoOutput, GetAccountInfoError>>

Returns a Result object that contains either the success value or error, never throws.

Parameters

accountId · AccountId · required

The account ID to query information for.

atMomentOf · BlockReference

Query account state at a specific block. Can be:

• 'LatestOptimisticBlock' - Latest optimistic block (default)
• 'LatestNearFinalBlock' - Latest near-final block
• 'LatestFinalBlock' - Latest final block
• { blockHash: BlockHash } - Specific block by hash
• { blockHeight: BlockHeight } - Specific block by height
• 'EarliestAvailableBlock' - Earliest available block
• 'GenesisBlock' - Genesis block

policies · object

Configuration for transport behavior.

policies.transport · PartialTransportPolicy

Transport-specific policies like retry behavior and timeout settings.

options · object

Additional execution options.

options.signal · AbortSignal

AbortSignal to cancel the request.

Return Type

blockHash · BlockHash

Hash of the block where the account state was queried.

blockHeight · BlockHeight

Height of the block where the account state was queried.

accountId · AccountId

The queried account ID.

accountInfo · object

Detailed account information.

accountInfo.balance · object

Balance breakdown for the account.

accountInfo.balance.total · NearToken

Total balance including locked funds.

accountInfo.balance.available · NearToken

Available balance that can be transferred or used.

accountInfo.balance.locked · object

Locked balance details.

accountInfo.balance.locked.amount · NearToken

Total locked amount.

accountInfo.balance.locked.breakdown · object

Breakdown of locked funds.

accountInfo.balance.locked.breakdown.validatorStake · NearToken

Amount locked in validator stake.

accountInfo.balance.locked.breakdown.storageDeposit · NearToken

Amount locked for storage deposit.

accountInfo.usedStorageBytes · number

Number of bytes used for account storage.

accountInfo.contractHash · CryptoHash

Hash of the deployed contract code (if account has a contract).

accountInfo.globalContractHash · CryptoHash

Hash of the global contract (if using shared contract).

accountInfo.globalContractAccountId · AccountId

Account ID of the global contract owner (if using shared contract).

rawRpcResult · RpcQueryViewAccountResult

Raw RPC result from the NEAR node.

Error Codes

When using safeGetAccountInfo, the following error codes may be returned:

Client Errors

• Client.GetAccountInfo.Args.InvalidSchema - Invalid arguments provided
• Client.GetAccountInfo.StoragePricePerByte.NotLoaded - Storage price data not loaded
• Client.GetAccountInfo.PreferredRpc.NotFound - Preferred RPC endpoint not found
• Client.GetAccountInfo.Timeout - Request timed out
• Client.GetAccountInfo.Aborted - Request was aborted
• Client.GetAccountInfo.Exhausted - All retry attempts exhausted

RPC Errors

• Client.GetAccountInfo.Rpc.Account.NotFound - Account does not exist at specified block
• Client.GetAccountInfo.Rpc.NotSynced - Node is not synced
• Client.GetAccountInfo.Rpc.Shard.NotTracked - Shard is not tracked by this node
• Client.GetAccountInfo.Rpc.Block.GarbageCollected - Block has been garbage collected
• Client.GetAccountInfo.Rpc.Block.NotFound - Block not found

Internal Errors

• Client.GetAccountInfo.Internal - Internal library error

Examples

Basic Usage (Throwable)

const accountInfo = await client.getAccountInfo({
  accountId: 'alice.near'
});

console.log(`Total balance: ${accountInfo.accountInfo.balance.total.near} NEAR`);
console.log(`Available: ${accountInfo.accountInfo.balance.available.near} NEAR`);
console.log(`Storage used: ${accountInfo.accountInfo.usedStorageBytes} bytes`);

Safe Variant with Error Handling

const result = await client.safeGetAccountInfo({
  accountId: 'alice.near'
});

if (result.ok) {
  const { accountInfo } = result.value;
  console.log(`Total: ${accountInfo.balance.total.near} NEAR`);
  console.log(`Available: ${accountInfo.balance.available.near} NEAR`);
  console.log(`Locked: ${accountInfo.balance.locked.amount.near} NEAR`);
  console.log(`Staked: ${accountInfo.balance.locked.breakdown.validatorStake.near} NEAR`);
} else {
  if (result.error.kind === 'Client.GetAccountInfo.Rpc.Account.NotFound') {
    console.log('Account does not exist');
  } else {
    console.error('Error:', result.error.kind);
  }
}

Query at Specific Block

const result = await client.getAccountInfo({
  accountId: 'alice.near',
  atMomentOf: {
    blockHeight: 123456789
  }
});

console.log(`Balance at block ${result.blockHeight}: ${result.accountInfo.balance.total.near} NEAR`);

Check for Contract Deployment

const info = await client.getAccountInfo({
  accountId: 'contract.near'
});

if (info.accountInfo.contractHash) {
  console.log(`Contract deployed with hash: ${info.accountInfo.contractHash}`);
} else {
  console.log('No contract deployed');
}

With Request Timeout

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000); // 5 second timeout

const result = await client.safeGetAccountInfo({
  accountId: 'alice.near',
  options: {
    signal: controller.signal
  }
});

if (!result.ok && result.error.kind === 'Client.GetAccountInfo.Aborted') {
  console.log('Request was aborted');
}

Query at Latest Final Block

const info = await client.getAccountInfo({
  accountId: 'alice.near',
  atMomentOf: 'LatestFinalBlock'
});

console.log(`Final block height: ${info.blockHeight}`);
console.log(`Balance: ${info.accountInfo.balance.total.near} NEAR`);