Installation

Prerequisites

• Node.js ≥ 18.0.0
• An API key from Orbis1 services

Install

npm

npm install orbis1-sdk-node

yarn

yarn add orbis1-sdk-node

pnpm

pnpm add orbis1-sdk-node

The package ships a prebuilt N-API native addon for the following targets. No Rust toolchain or build step is required in your application:

Platform	Architecture
macOS	x64, arm64
Linux	x64, arm64
Windows	x64

Verify installation

import { generateKeys, BitcoinNetwork } from 'orbis1-sdk-node';

const keys = await generateKeys(BitcoinNetwork.TESTNET4);
console.log('Keys generated:', keys.masterFingerprint);

If this logs a fingerprint without error, the native binding loaded correctly.

Troubleshooting native binding load failures

If you see Error: Failed to load module or a native binding error:

Check Node.js version

node --version  # must be >= 18.0.0

Rebuild native addons (required after switching Node versions)

npm rebuild
# or
npx node-pre-gyp rebuild

Check architecture match

On Apple Silicon Macs running Node.js via Rosetta 2, ensure you run a native arm64 build:

node --version --arch  # should show arm64 on M-series Macs

Lock file stale

If a previous process crashed, a stale rgb_runtime.lock file may block wallet initialization. The SDK removes stale locks automatically at startup; if you encounter persistent lock errors, delete rgb-data/{masterFingerprint}/rgb_runtime.lock manually.

Data directory

By default, the SDK stores wallet data in .orbis1-wallet-data/ at your project root (the directory containing node_modules/). This directory:

• ✅ Is created automatically
• ✅ Survives npm install, npm ci, and rm -rf node_modules
• ✅ Persists across package updates

For production deployments, you can specify a custom location via wallet.dataDir in the SDK configuration (see Configuration). Ensure the directory is persisted across restarts (e.g., Docker volume, EBS mount).

You can verify the path your wallet uses:

const wallet = sdk.getWallet()!;
const dir = await wallet.getWalletDir();
console.log('Wallet data at:', dir);