Node.js Quickstart

This guide covers Node.js server applications. For mobile, see the React Native guide. For browser applications, see the Web guide.

The @utexo/rgb-sdk source repository was archived on July 28, 2026 and is read-only. This guide documents the last committed package version, 1.0.0-beta.9. New Node.js integrations should use @utexo/wdk-rgb-lightning instead of this package.

Prerequisites

Node.js 20, the version used by the package’s publish and end-to-end workflows
Bitcoin test funds for transaction fees
A separately initialized sender wallet that already holds the RGB asset for an end-to-end transfer
Secure server-side storage for the mnemonic and wallet data

This guide uses the Node.js package’s testnet profile. Never use mainnet keys or real funds while following this guide.

Step 1: Install the SDK

npm install @utexo/rgb-sdk

The package is designed for Node.js and uses filesystem and native cryptographic dependencies. It is not browser-compatible.

Step 2: Generate Wallet Keys

const { generateKeys } = require('@utexo/rgb-sdk');

const keys = await generateKeys('testnet');

Store the mnemonic securely. Do not log it in production or commit it to source control.

Step 3: Initialize the Wallet

The archived 1.0.0-beta.9 Node.js package retains its legacy constructor and lifecycle:

const { UTEXOWallet } = require('@utexo/rgb-sdk');


const wallet = new UTEXOWallet(keys.mnemonic, {
  network: 'testnet',
  dataDir: './wallet-data',
});


await wallet.initialize();

Do not copy the Web or React Native init() and unlock() lifecycle into this guide. The archived Node.js source did not migrate to that runtime surface.

Use a persistent, access-controlled data directory. A mnemonic is necessary for key recovery, but it does not replace a backup of all wallet state required by RGB.

Step 4: Fund the Wallet

const address = await wallet.getAddress();
console.log('Deposit address:', address);

Send testnet BTC to this address and wait for the required confirmation before creating RGB UTXOs.

Step 5: Create RGB UTXOs

await wallet.createUtxos({ num: 5, size: 1000 });
await wallet.refreshWallet();

size is denominated in satoshis.

Step 6: Resolve the Asset From the Sender

listAssets() returns an object grouped by asset schema. NIA assets are in the nia array and use the assetId field.

const { nia } = await senderWallet.listAssets();
const usdt = nia.find((asset) => asset.ticker === 'USDT');


if (!usdt) {
  throw new Error('The sender wallet does not hold the requested NIA asset');
}


const usdtAssetId = usdt.assetId;
const amount = 10 ** usdt.precision; // one displayed unit in base units

A new receiver wallet will not list an asset it has never received. Resolve the ID and precision from the funded sender or an authoritative asset registry. The previous assets.find(...).id example used the wrong response shape and field name.

Step 7: Create a Receive Invoice

Run this on the receiver wallet initialized above:

const receiveData = await wallet.blindReceive({
  assetId: usdtAssetId,
  amount,
  minConfirmations: 1,
  durationSeconds: 3600,
});


console.log('RGB invoice:', receiveData.invoice);

The amount is an integer in asset base units. One displayed unit equals 10 ** precision base units; it is not always equal to 1.

Step 8: Send From the Funded Wallet

The archived Node.js package’s 1.0.0-beta.9 API uses the legacy send() method.

const sendResult = await senderWallet.send({
  invoice: receiveData.invoice,
  assetId: usdtAssetId,
  amount,
  donation: false,
  feeRate: 7,
  minConfirmations: 1,
});


console.log('Transfer transaction:', sendResult.txid);

The sender wallet must be a separately initialized UTEXOWallet with sufficient testnet BTC and a spendable asset balance.

Step 9: Refresh and Verify

await senderWallet.refreshWallet();
await wallet.refreshWallet();


const receiverAssets = await wallet.listAssets();
const receivedAsset = receiverAssets.nia.find(
  (asset) => asset.assetId === usdtAssetId
);


console.log('Receiver asset balance:', receivedAsset?.balance);

A transfer can remain pending while its consignment is delivered and its Bitcoin anchor reaches the required confirmation state.

Lightning Payments

The archived 1.0.0-beta.9 Node.js package pins @utexo/rgb-sdk-core 1.0.0-beta.3; the current Web and React Native packages pin 1.0.0-beta.5. Its Lightning request and status types therefore differ from the current cross-platform conformance interface.

Do not copy the Web or React Native getLightningSendStatus() example into a Node.js integration without first checking the installed package’s type declarations. Lightning also requires configured peer and channel state; wallet initialization alone does not make a payment route available.

This Quickstart does not include a Lightning code sample because the archived Node.js package does not implement the current conformance contract. Check the installed package’s type declarations before building a version-pinned integration.

Troubleshooting

Issue	Likely cause	Check
`initialize()` fails	Data directory or endpoint problem	Confirm the directory is writable and network services are reachable
`createUtxos()` fails	Insufficient confirmed BTC	Fund the wallet and wait for confirmation
Asset cannot be found	Wrong response shape or unfunded sender	Read `listAssets().nia` and use `assetId`
`send()` fails	Invoice, amount, balance, or transport problem	Confirm the invoice is unexpired and the amount is in base units
Balance does not update	Transfer is pending or wallet is stale	Refresh both wallets and check transfer status

What Utexo Is

Getting Started

Product Suite

API Reference

Prerequisites

Step 1: Install the SDK

Step 2: Generate Wallet Keys

Step 3: Initialize the Wallet

Step 4: Fund the Wallet

Step 5: Create RGB UTXOs

Step 6: Resolve the Asset From the Sender

Step 7: Create a Receive Invoice

Step 8: Send From the Funded Wallet

Step 9: Refresh and Verify

Lightning Payments

Troubleshooting

Implementation References

Next Steps

​Prerequisites

​Step 1: Install the SDK

​Step 2: Generate Wallet Keys

​Step 3: Initialize the Wallet

​Step 4: Fund the Wallet

​Step 5: Create RGB UTXOs

​Step 6: Resolve the Asset From the Sender

​Step 7: Create a Receive Invoice

​Step 8: Send From the Funded Wallet

​Step 9: Refresh and Verify

​Lightning Payments

​Troubleshooting

​Implementation References

​Next Steps

Prerequisites

Step 1: Install the SDK

Step 2: Generate Wallet Keys

Step 3: Initialize the Wallet

Step 4: Fund the Wallet

Step 5: Create RGB UTXOs

Step 6: Resolve the Asset From the Sender

Step 7: Create a Receive Invoice

Step 8: Send From the Funded Wallet

Step 9: Refresh and Verify

Lightning Payments

Troubleshooting

Implementation References

Next Steps