Nimiq Albatross RPC Client for TypeScript

Fully typed RPC client with HTTP and WebSocket support. Tree-shaking works automatically.

pnpm add nimiq-rpc-client-ts

import * as rpc from 'nimiq-rpc-client-ts'

rpc.initRpcClient({ url: 'https://rpc.nimiq-testnet.com' })

// HTTP - supports both array and object destructuring
// See: https://antfu.me/posts/destructuring-with-object-or-array
const [ok, err, block] = await rpc.getBlockNumber()
const { success, error, data } = await rpc.getBlockNumber()

if (!success)
  console.error(error)

// WebSocket subscription
const sub = await rpc.subscribeForHeadBlock(true, { autoReconnect: true })
sub.addEventListener('data', e => console.log('Block:', e.detail.data.number))
sub.addEventListener('error', e => console.error('WS error:', e.detail))
sub.addEventListener('close', () => console.log('Disconnected'))

Configuration

rpc.initRpcClient({
  url: 'https://rpc.nimiq-testnet.com',
  auth: { username: 'user', password: 'pass' }, // Optional
  validation: { validateBody: true, validationLevel: 'error' } // Optional
})

Using environment variables

export ALBATROSS_RPC_NODE_URL=https://rpc.nimiq-testnet.com
export ALBATROSS_RPC_NODE_USERNAME=your-username
export ALBATROSS_RPC_NODE_PASSWORD=your-password

Per-request configuration

const [ok, err, result] = await rpc.getBlockNumber({
  url: new URL('https://other-node.com'),
  auth: { username: 'user', password: 'pass' }
})

HTTP Options

All HTTP methods return an isomorphic destructurable result supporting both patterns:

// Array destructuring
const [ok, err, block, meta] = await rpc.getBlockByNumber({ blockNumber: 123 })

// Object destructuring
const { success, error, data, metadata } = await rpc.getBlockByNumber({ blockNumber: 123 })

The last parameter is always an options object:

const { success, data } = await rpc.getBlockByNumber({ blockNumber: 123 }, {
  url: new URL('...'), // Override URL
  auth: { username, password }, // Override auth
  validation: { validateBody: true, validationLevel: 'warning' } // Per-request validation
})

WebSocket Options

const sub = await rpc.subscribeForHeadBlock(true, {
  once: false, // Auto-unsubscribe after first message
  filter: block => block.number > 100, // Filter events
  timeout: 30000, // Timeout in ms (default: 30000, false to disable)
  autoReconnect: true, // Auto reconnect on disconnect
  onError: e => console.error(e) // Error callback
})

Response Validation

Optional runtime validation using Valibot schemas. Disabled by default.

rpc.initRpcClient({
  url: '...',
  validation: { validateBody: true, validationLevel: 'error' } // 'error' throws, 'warning' logs
})

// Or per-request
const [ok, err, data] = await rpc.getAccountByAddress({ address: 'NQ...' }, {
  validation: { validateBody: true, validationLevel: 'warning' }
})

View available schemas

Custom RPC Methods

// HTTP
const [ok, err, data] = await rpc.rpcCall<MyType>('customMethod', ['param1', 'param2'])

// WebSocket
const sub = await rpc.rpcSubscribe<MyEvent>('subscribeCustom', ['param1'], { /* options */ })

Type Augmentation

declare module 'nimiq-rpc-client-ts' {
  interface Block {
    myCustomProperty: string
  }
}

Alternative: Subpath Imports

import type { Block } from 'nimiq-rpc-client-ts/types'
import { getBlockNumber } from 'nimiq-rpc-client-ts/http'
import { BlockSchema } from 'nimiq-rpc-client-ts/schemas'
import { subscribeForHeadBlock } from 'nimiq-rpc-client-ts/ws'