Skip to main content
Common type definitions used throughout the NEAR API TypeScript library.

​
Account & Blockchain Types

​
AccountId

NEAR account identifier. 
type AccountId = string;
Examples:
  • "alice.near"
  • "bob.testnet"
  • "app.alice.near" (subaccount)
  • "0x1234567890123456789012345678901234567890" (implicit account)
Validation:
  • Minimum length: 2 characters
  • Maximum length: 64 characters
  • Valid characters: a-z, 0-9, -, _, .
  • Cannot start or end with separator (., -, _)
  • Cannot have consecutive separators

​
CryptoHash

A 32-byte cryptographic hash represented as a base58 string. 
type CryptoHash = string; // 32 bytes
Example: 
const hash: CryptoHash = 'DcA2MzgpJbrUATQLLceocVckhhAqrkingax4oJ9kZ847';

​
BlockHash

Identifier for a specific block. 
type BlockHash = CryptoHash;

​
BlockHeight

Block number in the blockchain. 
type BlockHeight = number;
Example: 
const height: BlockHeight = 123456789;

​
Nonce

Transaction nonce for replay protection. 
type Nonce = number;
Each transaction from an account must have a nonce greater than the previous transaction.

​
Block Reference Types

​
BlockReference

Specifies which block to query. 
type BlockReference = 
  | LatestBlock 
  | SyncCheckpoint 
  | BlockId;

type LatestBlock =
  | 'LatestOptimisticBlock'
  | 'LatestNearFinalBlock'
  | 'LatestFinalBlock';

type SyncCheckpoint = 
  | 'EarliestAvailableBlock' 
  | 'GenesisBlock';

type BlockId = 
  | { blockHash: BlockHash }
  | { blockHeight: BlockHeight };
Examples: 
// Latest finalized block (recommended)
const ref1: BlockReference = 'LatestFinalBlock';

// Specific block by height
const ref2: BlockReference = { blockHeight: 12345 };

// Specific block by hash
const ref3: BlockReference = { 
  blockHash: 'DcA2MzgpJbrUATQLLceocVckhhAqrkingax4oJ9kZ847' 
};

// Near-final block
const ref4: BlockReference = 'LatestNearFinalBlock';

// Genesis block
const ref5: BlockReference = 'GenesisBlock';

​
NativeBlockReference

Internal representation for RPC calls. 
type NativeBlockReference =
  | { block_id: BlockHash | BlockHeight }
  | { finality: 'optimistic' | 'near-final' | 'final' }
  | { sync_checkpoint: 'genesis' | 'earliest_available' };

​
Data Encoding Types

​
Hex

Data represented as hexadecimal string or raw bytes. 
type Hex = Uint8Array | string;
Examples: 
// Hex string
const hex1: Hex = '48656c6c6f'; // "Hello"

// Uint8Array
const hex2: Hex = new Uint8Array([72, 101, 108, 108, 111]);

​
Base58String

Base58-encoded string. 
type Base58String = string;

​
Base64String

Base64-encoded string. 
type Base64String = string;

​
BorshBytes

Borsh-serialized binary data. 
type BorshBytes = Uint8Array;

​
Token & Gas Types

​
Units

Smallest unit of a token (e.g., yoctoNEAR). 
type Units = bigint | string;
Example: 
const yocto: Units = 1000000000000000000000000n; // 1 NEAR

​
Tokens

Human-readable token amount. 
type Tokens = string;
Example: 
const amount: Tokens = '1.5'; // 1.5 NEAR

​
Contract Types

​
ContractFunctionName

Name of a contract function (max 256 characters). 
type ContractFunctionName = string;
Examples: 
const fn1: ContractFunctionName = 'get_balance';
const fn2: ContractFunctionName = 'ft_transfer';
const fn3: ContractFunctionName = 'nft_mint';

​
JsonLikeValue

JSON-serializable values for contract arguments. 
type JsonLikeValue =
  | string
  | number
  | boolean
  | null
  | JsonLikeValue[]
  | { [key: string]: JsonLikeValue | undefined };

type MaybeJsonLikeValue = JsonLikeValue | undefined;
Examples: 
// Simple values
const arg1: JsonLikeValue = 'hello';
const arg2: JsonLikeValue = 42;
const arg3: JsonLikeValue = true;
const arg4: JsonLikeValue = null;

// Arrays
const arg5: JsonLikeValue = [1, 2, 3];

// Objects
const arg6: JsonLikeValue = {
  receiver_id: 'bob.near',
  amount: '100',
  memo: 'Payment'
};

// Nested structures
const arg7: JsonLikeValue = {
  user: {
    name: 'Alice',
    tokens: [10, 20, 30]
  }
};

​
Time Types

​
Milliseconds

Time duration in milliseconds. 
type Milliseconds = number;
Example: 
const timeout: Milliseconds = 5000; // 5 seconds

​
TimeoutId

Identifier returned by setTimeout. 
type TimeoutId = ReturnType<typeof setTimeout>;

​
Result Types

​
Result

Type-safe error handling without exceptions. 
type Result<V, E> = ResultOk<V> | ResultErr<E>;

type ResultOk<V> = {
  ok: true;
  value: V;
};

type ResultErr<E> = {
  ok: false;
  error: E;
};
Examples: 
import { safeNear } from '@near-api/universal';

const result = safeNear('1.5');

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

​
Examples

​
Account ID Validation

function isValidAccountId(accountId: AccountId): boolean {
  if (accountId.length < 2 || accountId.length > 64) {
    return false;
  }
  
  // Implicit account (64 hex chars)
  if (/^[0-9a-f]{64}$/.test(accountId)) {
    return true;
  }
  
  // Named account
  return /^[a-z0-9._-]+$/.test(accountId) &&
    !accountId.startsWith('.') &&
    !accountId.endsWith('.') &&
    !accountId.includes('..');
}

console.log(isValidAccountId('alice.near')); // true
console.log(isValidAccountId('a')); // false (too short)
console.log(isValidAccountId('.alice.near')); // false (starts with .)

​
Working with Block References

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

function getBlockReference(input: string | number): BlockReference {
  if (typeof input === 'number') {
    return { blockHeight: input };
  }
  
  if (input === 'latest') {
    return 'LatestFinalBlock';
  }
  
  return { blockHash: input };
}

const ref1 = getBlockReference('latest');
const ref2 = getBlockReference(12345);
const ref3 = getBlockReference('DcA2MzgpJ...');

​
Using Result Types

import { safeNear, type Result } from '@near-api/universal';

function processTokenAmount(amount: string): string {
  const result = safeNear(amount);
  
  if (result.ok) {
    return `Valid: ${result.value.yoctoNear} yoctoNEAR`;
  } else {
    return `Error: ${result.error.kind}`;
  }
}

console.log(processTokenAmount('1.5'));
console.log(processTokenAmount('invalid'));

​
Contract Arguments

import { functionCall, teraGas } from '@near-api/universal';
import type { JsonLikeValue } from '@near-api/universal';

const args: JsonLikeValue = {
  receiver_id: 'bob.near',
  amount: '1000000',
  memo: 'Payment for services'
};

const action = functionCall({
  functionName: 'ft_transfer',
  functionArgs: args,
  gasLimit: { teraGas: '300' },
  attachedDeposit: { near: '0.000000000000000000000001' } // 1 yoctoNEAR
});

​
Converting Hex

function hexToUint8Array(hex: string): Uint8Array {
  const bytes = new Uint8Array(hex.length / 2);
  for (let i = 0; i < hex.length; i += 2) {
    bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
  }
  return bytes;
}

function uint8ArrayToHex(bytes: Uint8Array): string {
  return Array.from(bytes)
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');
}

const hex = '48656c6c6f';
const bytes = hexToUint8Array(hex);
const hexAgain = uint8ArrayToHex(bytes);

console.log(hex === hexAgain); // true