Utexo SDK Reference

Complete method reference for the @utexo/rgb-sdk Node.js package — wallet management, RGB asset operations, UTXO management, Lightning payments, on-chain interactions, backup and restore.

The @utexo/rgb-sdk package is the Node.js SDK for applications built on the Utexo stack. It provides a complete set of bindings for wallet management, RGB asset operations, Lightning payments, async payments, and on-chain Bitcoin interactions. It is built on top of @utexo/rgb-sdk-core, the shared foundation used by all three Utexo SDK platforms.

All operations are performed locally using client-side validation. Private keys and mnemonics are never transmitted to remote servers during normal execution.

This SDK is designed for Node.js only and is not browser-compatible. For browser environments use @utexo/rgb-sdk-web; for iOS and Android use @utexo/rgb-sdk-rn.

Installation

npm install @utexo/rgb-sdk

Initialisation

The primary wallet class is UTEXOWallet. Initialise it with a mnemonic and a configuration object, then call await wallet.initialize() before use.

import { UTEXOWallet, generateKeys } from '@utexo/rgb-sdk';

// 1. Generate wallet keys
const keys = await generateKeys('utexo');
console.log('Mnemonic:', keys.mnemonic); // Store securely

// 2. Initialise wallet
const wallet = new UTEXOWallet(keys.mnemonic, {
  network: 'utexo',        // 'mainnet' | 'testnet' | 'utexo'
  dataDir: './wallet',
  lspBaseUrl: '...',       // optional — enables async (offline) payments
  lspBearerToken: '...'   // optional — required when lspBaseUrl is set
});
await wallet.initialize();

// 3. Get a deposit address
const address = await wallet.getAddress();

// 4. Check BTC balance
const balance = await wallet.getBtcBalance();

lspBaseUrl and lspBearerToken are optional. Omitting them has no effect on synchronous payment flows — async payment capability is strictly opt-in.

Networks

Environment	Identifier	RGB Transport Endpoint	Bitcoin Indexer
Mainnet	mainnet	rpcs://rgb-proxy-mainnet.utexo.com/json-rpc	ssl://electrum.iriswallet.com:50003
Testnet	testnet	rpcs://rgb-proxy-testnet3.utexo.com/json-rpc	ssl://electrum.iriswallet.com:50013
Utexo (Signet)	utexo	rpcs://rgb-proxy.utexo.com/json-rpc	https://esplora-api.utexo.com

Pass the identifier string in the network field of the init config. utexo is the default environment for development and testing.

Utexo Network Faucet — To get test BTC and RGB assets on the Utexo network, use the Telegram bot @Utexo_RLN_bot.

Command	Description
/getbtc	Send your Bitcoin address to receive test satoshis
/getasset	Send an RGB invoice to receive test RGB assets
/getinvoice	Get an RGB Lightning invoice to test paying
/getnodeinfo	Get the faucet node URI, asset ID, and ticker

Limited to 2 requests per 24 hours per user.

Vanilla vs Colored Addresses

The SDK maintains two separate derivation paths:

• Vanilla — the standard Bitcoin path. getAddress() returns a vanilla bech32 receive address used for on-chain BTC funding, withdrawals, and fee payments.
• Colored — the RGB-specific path. Colored outputs anchor RGB asset allocations to Bitcoin UTXOs. This path is used internally by createUtxos() and all RGB transfer operations.

getXpub() returns both:

• accountXpubVanilla — the extended public key for the vanilla (BTC) derivation path
• accountXpubColored — the extended public key for the colored (RGB) derivation path

getBtcBalance() returns separate balance objects for each path, each containing:

• settled — confirmed, final balance
• future — expected balance after pending operations confirm
• spendable — currently usable amount for new operations

Address Rotation

By default, each call to getAddress() rotates to a new receive address (new HD derivation index). This improves privacy by reducing address reuse and matches HD wallet best practices. If your application requires a stable deposit address, persist one generated address and reuse it in your UI or service layer.

Wallet Methods

Key Generation and Derivation

• generateKeys(network?) — Generate new wallet keys. Returns mnemonic, xpub, xpriv, accountXpubVanilla, and accountXpubColored.
• deriveKeysFromMnemonic(network, mnemonic) — Derive wallet keys from an existing BIP39 mnemonic
• deriveKeysFromSeed(network, seed) — Derive wallet keys from a BIP39 seed
• restoreKeys(network, mnemonic) — Legacy alias for deriveKeysFromMnemonic
• getXpub() — Get vanilla and colored xpubs (accountXpubVanilla, accountXpubColored)
• getXprivFromMnemonic(network, mnemonic) — Derive the extended private key (xpriv) from a mnemonic. Treat with the same sensitivity as the mnemonic itself.

Wallet State

• getAddress() — Get a receive address; rotates to a new HD index on each call for privacy
• getBtcBalance() — Get on-chain BTC balance split by vanilla and colored paths, each with settled, future, spendable
• refreshWallet() — Update RGB transfer state (consignments and transfer status progression)
• syncWallet() — Update chain and UTXO state (funding confirmations, spendable BTC)
• listUnspents() — List unspent UTXOs
• listAssets() — List RGB assets held in the wallet
• getAssetBalance(assetId) — Get balance for a specific RGB asset
• listTransactions() — List BTC-level transactions
• listTransfers(assetId?) — List RGB transfer history. Transfer statuses: WaitingCounterparty, WaitingConfirmations, Settled, Failed
• dispose() — Clean up wallet resources

Use syncWallet() after funding or UTXO creation to update chain state. Use refreshWallet() after send() to update RGB transfer status on both sender and receiver sides.

Backup and Restore

Backups are recommended after every significant state change: UTXO creation, asset issuance, and transfers.

File Backup

Creates an encrypted local backup containing both layer1 and utexo state files.

await wallet.createBackup({
  backupPath: './backups',
  password: 'strong-password',
});

Restore from a file backup:

import { restoreUtxoWalletFromBackup } from '@utexo/rgb-sdk';

await restoreUtxoWalletFromBackup({
  backupPath: './backups',
  password: 'strong-password',
  targetDir: './restored',
});

VSS Backup

Pushes wallet state to a remote Verifiable Secret Sharing (VSS) server. The backup is keyed to the wallet mnemonic and can be restored on any device.

import { restoreUtxoWalletFromVss } from '@utexo/rgb-sdk';

// Get deterministic VSS config derived from mnemonic and defaults
const vssConfig = await wallet.getDefaultVssConfig();

// Export wallet state to VSS
await wallet.vssBackup(vssConfig);

// Check backup status
const info = await wallet.vssBackupInfo(vssConfig);
console.log(info); // { backupExists, serverVersion, backupRequired }

// Restore from VSS into a fresh local directory
const restored = await restoreUtxoWalletFromVss({
  mnemonic: keys.mnemonic,
  targetDir: './restored-from-vss',
  config: vssConfig,
  networkPreset: 'utexo',
});

// Re-open wallet from restored data
const restoredWallet = new UTEXOWallet(keys.mnemonic, {
  network: 'utexo',
  dataDir: restored.targetDir,
});
await restoredWallet.initialize();

Method	Description
createBackup({ backupPath, password })	Create encrypted local backup
restoreUtxoWalletFromBackup({ backupPath, password, targetDir })	Restore wallet from file backup
vssBackup(config?)	Push wallet state to VSS remote
vssBackupInfo(config?)	Check backup status on VSS server
getDefaultVssConfig()	Get deterministic VSS config from mnemonic
restoreUtxoWalletFromVss({ mnemonic, targetDir, config?, networkPreset })	Restore wallet from VSS

Private Key Export

The SDK exposes a utility to derive the extended private key from a mnemonic:

import { getXprivFromMnemonic } from '@utexo/rgb-sdk';

const xpriv = await getXprivFromMnemonic('utexo', keys.mnemonic);
console.log('xpriv:', xpriv);

xpriv is the account root private key. All child private and public keys can be derived from it. Treat it with the same sensitivity as your mnemonic — never log or transmit it in production.

RGB Asset Methods

Issue a new Non-Inflationary Asset (NIA) on RGB:

const asset = await wallet.issueAssetNia({
  ticker: 'USDT',
  name: 'Tether USD (Test)',
  amounts: [1000000],
  precision: 6
});
const assetId = asset.assetId;

Invoice Types: Blinded vs Witness

RGB receive flows support two invoice styles:

• Blinded invoice (blindReceive) — most common flow. The receiver creates a blinded recipient endpoint; the sender pays the invoice directly. Use for standard app-to-app RGB transfers.
• Witness invoice (witnessReceive) — the receiver binds the transfer to witness data. The sender must provide witnessData (at minimum amountSat) in send(). Use when your integration explicitly requires witness-bound receive semantics.

// Blinded invoice
const receiveData = await receiverWallet.blindReceive({
  assetId,
  amount: 5000,             // RGB asset base units
  minConfirmations: 1,      // minimum Bitcoin confirmation depth
  durationSeconds: 3600,    // invoice lifetime in seconds
});

// Witness invoice
const witnessReceiveData = await receiverWallet.witnessReceive({
  assetId,
  amount: 2000,
  minConfirmations: 1,
  durationSeconds: 3600,
});

Complete an RGB asset transfer:

// Sender: send via blinded invoice
await senderWallet.send({
  invoice: receiveData.invoice,
  assetId,
  amount: 5000,
});

// Sender: send via witness invoice (witnessData required)
await senderWallet.send({
  invoice: witnessReceiveData.invoice,
  assetId,
  amount: 2000,
  witnessData: { amountSat: 1000 },
});

// Refresh both wallets after transfer
await senderWallet.refreshWallet();
await receiverWallet.refreshWallet();

• blindReceive({ assetId, amount, minConfirmations?, durationSeconds? }) — Generate blinded UTXO invoice
• witnessReceive({ assetId, amount, minConfirmations?, durationSeconds? }) — Generate witness UTXO invoice
• send({ invoice, assetId, amount, witnessData? }) — Complete send (begin → sign → end)
• signPsbt(psbt, mnemonic?) — Sign a PSBT using wallet mnemonic

UTXO Management

Before issuing or receiving RGB assets, the wallet must have colored UTXOs prepared. Create them after funding the vanilla address:

const created = await wallet.createUtxos({ num: 5, size: 1000 });
await wallet.syncWallet();
console.log('UTXOs created:', created);

• createUtxos({ num?, size?, upTo? }) — Create colored UTXOs (combines begin, sign, end internally)

Lightning Methods

• createLightningInvoice(params) — Create a standard BOLT11 Lightning invoice for receiving

Synchronous payments follow a begin → sign → end flow:

• payLightningInvoiceBegin(params) — Start Lightning payment (returns unsigned PSBT)
• payLightningInvoiceEnd(params) — Finalise Lightning payment with signed PSBT
• payLightningInvoice(params, mnemonic?) — Complete Lightning payment in a single call

Async payments allow funds to be sent to an offline recipient. The LSP holds the payment via a HODL invoice until the recipient comes online to collect. Requires lspBaseUrl and lspBearerToken in the wallet init config. The inbound leg (receiving while offline) is fully operational; the outbound leg is in active development.

When LSP integration is configured, recipients receive a stable Lightning Address rather than a per-transfer invoice. The address is provisioned automatically — no additional method calls are required.

• getLightningSendRequest(lnInvoice) — Get status of a Lightning send request
• getLightningReceiveRequest(lnInvoice) — Get status of a Lightning receive request
• listLightningPayments() — List all Lightning payments

On-chain Methods

• onchainReceive(params) — Generate an invoice for depositing from mainnet to UTEXO
• onchainSend(params, mnemonic?) — Complete an on-chain withdrawal (begin → sign → end)
• getOnchainSendStatus(invoice) — Get the status of an on-chain withdrawal

Security

By using this SDK, developers have full control over transfer orchestration, UTXO selection, invoice lifecycle, and signing policy. The SDK supports an external signer architecture: key management can be handled entirely outside the node, keeping signing logic isolated from the rest of the application. This is the recommended approach for custody-grade and enterprise deployments where key isolation is a hard requirement.

Private keys and mnemonics should be stored securely and never logged or transmitted. Use environment variables or a secrets manager for mnemonic storage:

const keys = await generateKeys('utexo');
const mnemonic = keys.mnemonic; // Sensitive — protect at rest

// Restore from stored mnemonic
const storedMnemonic = process.env.WALLET_MNEMONIC;
const restoredKeys = await deriveKeysFromMnemonic('utexo', storedMnemonic);

Further Reading

• SDK Overview — SDK family, key concepts, execution model, and network environments.
• Product Suite — How the SDK fits into the full Utexo product surface.
• Architecture — The Bitcoin + RGB stack the SDK operates on.