@near-js/jsonrpc-client

@near-js/jsonrpc-client

This package provides a fully-typed, dynamic client for the NEAR Protocol JSON-RPC API. All methods and types are automatically generated from the official OpenAPI specification.

Installation

npm install @near-js/jsonrpc-client

Usage

Create a new client instance and use the available RPC functions:

import { NearRpcClient, status } from '@near-js/jsonrpc-client';

const client = new NearRpcClient({
  endpoint: 'https://rpc.mainnet.near.org',
});

async function getNetworkStatus() {
  const result = await status(client);
  console.log('Network status:', result);
}

getNetworkStatus();

Handling Responses

All method calls return a promise that resolves to a fully typed result object based on the JSON-RPC API specification.

import { NearRpcClient, block } from '@near-js/jsonrpc-client';

const client = new NearRpcClient({
  endpoint: 'https://rpc.mainnet.near.org',
});

async function getLatestBlock() {
  const result = await block(client, { finality: 'final' });
  console.log('Latest block height:', result.header?.height);
}

getLatestBlock();

Convenience Methods

The client includes convenience methods for common query operations:

import { viewAccount, viewFunction, viewAccessKey } from '@near-js/jsonrpc-client';

// View account information
const account = await viewAccount(client, {
  accountId: 'example.near',
  finality: 'final',
});
console.log('Account balance:', account.amount);
console.log('Storage used:', account.storageUsage);

// Call view functions
const result = await viewFunction(client, {
  accountId: 'contract.near',
  methodName: 'get_balance',
  finality: 'final',
});

// View access keys
const accessKey = await viewAccessKey(client, {
  accountId: 'example.near',
  publicKey: 'ed25519:...',
  finality: 'final',
});

JSON Parsing Utilities

Many NEAR contracts return JSON data as byte arrays. We provide convenient utilities to parse these:

import { viewFunction, viewFunctionAsJson, parseCallResultToJson } from '@near-js/jsonrpc-client';

// Manual parsing
const result = await viewFunction(client, {
  accountId: 'contract.near',
  methodName: 'get_status',
});
const data = parseCallResultToJson(result); // Converts byte array to JSON

// Or use the convenience function that does both
const data = await viewFunctionAsJson(client, {
  accountId: 'contract.near', 
  methodName: 'get_status',
});

// With TypeScript types
interface Status {
  version: string;
  uptime: number;
}
const status = await viewFunctionAsJson<Status>(client, {
  accountId: 'contract.near',
  methodName: 'get_status',
});
console.log(status.version); // Fully typed!

Runtime Validation

The client supports runtime validation using Zod schemas to ensure both request parameters and server responses conform to the NEAR RPC specification.

Default Usage (With Validation)

By default, all functions include validation for maximum safety:

import { NearRpcClient, status, block } from '@near-js/jsonrpc-client';

// Just create a client - validation is built into the functions
const client = new NearRpcClient({
  endpoint: 'https://rpc.mainnet.near.org',
});

// Request parameters are validated before sending
try {
  await block(client, { blockId: 'invalid' }); // ❌ Throws validation error
  await block(client, { finality: 'final' }); // ✅ Valid parameters
} catch (error) {
  console.error('Validation error:', error.message);
  // "Invalid block request: Expected finality or block_id"
}

// Server responses are also validated
const result = await status(client);
// You can trust that 'result' matches the expected schema

Minimal Bundle Size (No Validation)

For applications where bundle size is critical, use the /no-validation export:

import { NearRpcClient, status, block } from '@near-js/jsonrpc-client/no-validation';

// Same API, but no runtime validation
const client = new NearRpcClient({
  endpoint: 'https://rpc.mainnet.near.org'
});

// No validation = smaller bundle size
await block(client, { finality: 'final' });

Bundle Size Comparison

The new validation approach uses per-function schema imports for optimal tree-shaking:

• With validation: ~60KB for 2 functions (only includes schemas for used functions)
• No validation: ~7KB (no Zod schemas included)
• Old approach: ~150KB+ (included all schemas even for unused functions)

Benefits of Validation

• Request Safety: Catch parameter errors before making network requests
• Response Integrity: Ensure server responses match the expected schema
• Better Error Messages: Get clear, descriptive errors instead of cryptic failures
• Development Speed: Find API usage mistakes immediately during development
• Runtime Protection: Guard against malformed or unexpected server responses
• Optimal Tree-Shaking: Only pay for validation of functions you actually use

Features

• 🔧 Dynamic methods: All 28+ RPC methods automatically available
• 📝 Fully typed: Complete TypeScript support with proper request/response types
• 🔄 Auto-updating: New API methods appear automatically without code changes
• ✅ Runtime validation: Validates both request parameters and server responses
• 🎯 Convenience methods: Simplified methods for common operations like viewAccount
• 🌳 Tree-shakable: Validation is modular - only included when used