Skip to main content
Type definitions for the NEAR API client interface and related functionality.

​
Client

The main client interface for interacting with the NEAR blockchain. 
type Client = {
  // Account methods
  getAccountInfo: GetAccountInfo;
  getAccountAccessKey: GetAccountAccessKey;
  getAccountAccessKeys: GetAccountAccessKeys;
  safeGetAccountInfo: SafeGetAccountInfo;
  safeGetAccountAccessKey: SafeGetAccountAccessKey;
  safeGetAccountAccessKeys: SafeGetAccountAccessKeys;

  // Contract methods
  callContractReadFunction: CallContractReadFunction;
  safeCallContractReadFunction: SafeCallContractReadFunction;

  // Block methods
  getBlock: GetBlock;
  safeGetBlock: SafeGetBlock;

  // Transaction methods
  sendSignedTransaction: SendSignedTransaction;
  safeSendSignedTransaction: SafeSendSignedTransaction;

  // Cache methods
  getRecentBlockHash: GetRecentBlockHash;
  safeGetRecentBlockHash: SafeGetRecentBlockHash;
};

​
Properties

Each method has two variants:
  • Throwable variant: Throws errors on failure (e.g., getAccountInfo)
  • Safe variant: Returns Result<T, E> type (e.g., safeGetAccountInfo)

​
Client Creation

​
CreateClient

import { createClient } from '@near-api/universal';

const client = createClient({
  networkId: 'testnet',
  rpcEndpoint: 'https://rpc.testnet.near.org'
});
See Client Creation for more details.

​
Account Methods

​
GetAccountInfo

Retrieve account information. 
type GetAccountInfo = (
  accountId: AccountId,
  options?: {
    blockReference?: BlockReference;
    signal?: AbortSignal;
  }
) => Promise<GetAccountInfoOutput>;

type GetAccountInfoOutput = {
  accountId: AccountId;
  balance: string;
  locked: string;
  codeHash: string;
  storageUsage: number;
  storagePaidAt: number;
  blockHeight: number;
  blockHash: BlockHash;
};
Example: 
const account = await client.getAccountInfo('alice.near');
console.log('Balance:', account.balance);

​
GetAccountAccessKey

Get a specific access key for an account. 
type GetAccountAccessKey = (
  accountId: AccountId,
  publicKey: PublicKey,
  options?: {
    blockReference?: BlockReference;
    signal?: AbortSignal;
  }
) => Promise<GetAccountAccessKeyOutput>;

​
GetAccountAccessKeys

Get all access keys for an account. 
type GetAccountAccessKeys = (
  accountId: AccountId,
  options?: {
    blockReference?: BlockReference;
    signal?: AbortSignal;
  }
) => Promise<GetAccountAccessKeysOutput>;

​
Contract Methods

​
CallContractReadFunction

Call a read-only contract function. 
type CallContractReadFunction = <R = unknown>(
  args: {
    contractId: AccountId;
    functionName: ContractFunctionName;
    functionArgs?: MaybeJsonLikeValue;
    blockReference?: BlockReference;
    signal?: AbortSignal;
  } & {
    options?: {
      serializeArgs?: BaseSerializeArgsFn;
      deserializeResult?: BaseDeserializeResultFn<R>;
    };
  }
) => Promise<CallContractReadFunctionOutput<R>>;

type CallContractReadFunctionOutput<R> = {
  result: R;
  blockHeight: number;
  blockHash: BlockHash;
  logs: string[];
};
Example: 
const result = await client.callContractReadFunction({
  contractId: 'contract.near',
  functionName: 'get_balance',
  functionArgs: { account_id: 'alice.near' }
});

console.log('Result:', result.result);

​
Block Methods

​
GetBlock

Retrieve block information. 
type GetBlock = (
  blockReference: BlockReference,
  options?: {
    signal?: AbortSignal;
  }
) => Promise<GetBlockOutput>;
Example: 
// Get latest block
const block = await client.getBlock('LatestFinalBlock');

// Get specific block by height
const block2 = await client.getBlock({ blockHeight: 12345 });

// Get block by hash
const block3 = await client.getBlock({ 
  blockHash: 'DkZgMd8T7K3Y...' 
});

​
Transaction Methods

​
SendSignedTransaction

Send a signed transaction to the network. 
type SendSignedTransaction = (
  signedTransaction: SignedTransaction,
  options?: {
    signal?: AbortSignal;
  }
) => Promise<SendSignedTransactionOutput>;

type SendSignedTransactionOutput = {
  transactionHash: CryptoHash;
  // ... additional transaction result fields
};
Example: 
import { sendSignedTransaction } from '@near-api/universal';

const result = await client.sendSignedTransaction(signedTx);
console.log('Transaction hash:', result.transactionHash);

​
Cache Methods

​
GetRecentBlockHash

Get a recent block hash for transaction signing. 
type GetRecentBlockHash = (
  options?: {
    signal?: AbortSignal;
  }
) => Promise<BlockHash>;
Example: 
const blockHash = await client.getRecentBlockHash();

​
Options

​
BlockReference

Specify which block to query. 
type BlockReference = 
  | 'LatestOptimisticBlock'  // Latest block (may not be final)
  | 'LatestNearFinalBlock'   // Near-final block
  | 'LatestFinalBlock'       // Latest finalized block (recommended)
  | 'EarliestAvailableBlock' // Earliest available
  | 'GenesisBlock'           // Genesis block
  | { blockHash: BlockHash }  // Specific block by hash
  | { blockHeight: number };  // Specific block by height

​
BaseOptions

type BaseOptions = {
  signal?: AbortSignal; // For request cancellation
};
Example: 
const controller = new AbortController();

try {
  const account = await client.getAccountInfo('alice.near', {
    signal: controller.signal
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request cancelled');
  }
}

// Cancel the request
controller.abort();

​
Error Registry

interface ClientPublicErrorRegistry
  extends CreateClientPublicErrorRegistry,
    GetAccountInfoPublicErrorRegistry,
    GetAccountAccessKeyPublicErrorRegistry,
    GetAccountAccessKeysPublicErrorRegistry,
    CallContractReadFunctionPublicErrorRegistry,
    GetBlockPublicErrorRegistry,
    GetRecentBlockHashPublicErrorRegistry,
    SendSignedTransactionPublicErrorRegistry {}
Each method can throw or return errors from its respective error registry.

​
Examples

​
Basic Client Usage

import { createClient } from '@near-api/universal';

const client = createClient({
  networkId: 'testnet',
  rpcEndpoint: 'https://rpc.testnet.near.org'
});

// Get account info
const account = await client.getAccountInfo('alice.near');

// Call contract
const result = await client.callContractReadFunction({
  contractId: 'contract.near',
  functionName: 'get_data'
});

// Get block
const block = await client.getBlock('LatestFinalBlock');

​
Safe Variant Usage

const result = await client.safeGetAccountInfo('alice.near');

if (result.ok) {
  console.log('Balance:', result.value.balance);
} else {
  console.error('Error:', result.error.kind);
}

​
With Abort Signal

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

try {
  const account = await client.getAccountInfo('alice.near', {
    signal: controller.signal
  });
  clearTimeout(timeout);
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request timed out');
  }
}