@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

``bash
npm install @near-js/jsonrpc-client
`

Usage

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

`typescript
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();
`

$3

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

`typescript
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();
`

$3

The client includes convenience methods for common query operations:

`typescript
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',
});
`

$3

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

`typescript
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(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.

$3

By default, all functions include validation for maximum safety:

`typescript
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
`

$3

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

`typescript
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' });
`

$3

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)

$3

- 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