> ## Documentation Index
> Fetch the complete documentation index at: https://docs.utexo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node.js Quickstart

> Initialize a server wallet and prepare an RGB transfer using @utexo/rgb-sdk.

<Info>
  This guide covers Node.js server applications. For mobile, see the [React Native guide](/getting-started/quickstart/react-native). For browser applications, see the [Web guide](/getting-started/quickstart/web).
</Info>

<Warning>
  The [`@utexo/rgb-sdk` source repository](https://github.com/UTEXO-Protocol/rgb-sdk) 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`](/sdk/wdk-rgb-lightning)** instead of this package.
</Warning>

## 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

<Warning>
  This guide uses the Node.js package's `testnet` profile. Never use mainnet keys or real funds while following this guide.
</Warning>

## Step 1: Install the SDK

```bash theme={null}
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

```javascript theme={null}
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:

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


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


await wallet.initialize();
```

<Warning>
  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.
</Warning>

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

```javascript theme={null}
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

```javascript theme={null}
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.

```javascript theme={null}
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:

```javascript theme={null}
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.

```javascript theme={null}
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

```javascript theme={null}
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.

<Warning>
  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.
</Warning>

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                       |

## Implementation References

* [Node.js wallet implementation](https://github.com/UTEXO-Protocol/rgb-sdk/blob/dev/src/utexo/utexo-wallet.ts)
* [Node.js package manifest](https://github.com/UTEXO-Protocol/rgb-sdk/blob/dev/package.json)
* [Node.js package's pinned core wallet models](https://github.com/UTEXO-Protocol/rgb-sdk-core/blob/v1.0.0-beta.3/src/types/wallet-model.ts)
* [Current shared conformance contract](https://github.com/UTEXO-Protocol/rgb-sdk-core/blob/dev/src/conformance/index.ts)

## Next Steps

* [SDK Reference](/product-suite/sdk)
* [Architecture](/getting-started/architecture)
* [Glossary](/getting-started/glossary)