Utexo SDK Reference

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();

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

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

Vanilla vs Colored Addresses

The wallet manages two address types:

Vanilla — Standard Bitcoin addresses for receiving on-chain BTC. Also used as the change address for Bitcoin transactions that anchor RGB state transitions.
Colored — Addresses associated with UTXOs that hold RGB asset allocations. These UTXOs are reserved exclusively for RGB state transitions and should not be spent directly as BTC.

Never manually spend a colored UTXO as regular BTC — doing so will permanently destroy the RGB asset allocation anchored to it.

Networks

The available environments for the network field in the init config are:

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`

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.

UTXO Management

Before issuing or receiving RGB assets, prepare colored UTXOs:

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

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

Asset Methods

listAssets() — List all RGB assets held by the wallet
getAsset(assetId) — Get metadata and balance for a specific asset
issueAssetNia(params) — Issue a new NIA (Non-Inflatable Asset) RGB asset
issueAssetCfa(params) — Issue a new CFA (Collectible) RGB asset
blindReceive(params) — Generate a blinded invoice to receive an RGB asset
send(params) — Send RGB assets to a blinded invoice
listTransfers(assetId) — List all transfers for a given asset
refreshWallet() — Sync wallet state with the chain and transport layer
failTransfers(params) — Expire stale pending transfers
deleteTransfers(params) — Remove transfer records

BTC Methods

getAddress() — Get the current vanilla Bitcoin deposit address
getBtcBalance() — Get the BTC balance (vanilla and colored paths)
sendBtc(params, mnemonic?) — Send BTC from the vanilla wallet
drainBtc(params, mnemonic?) — Drain the entire vanilla BTC balance to an address

Key Derivation and Backup

generateKeys(network) — Generate a new BIP-39 mnemonic and derive xpub
deriveKeysFromMnemonic(network, mnemonic) — Re-derive keys from an existing mnemonic
backup(backupPath, password) — Create an encrypted wallet backup
restore(mnemonic, backupPath, password) — Restore a wallet from a backup file

PSBT Methods

For advanced use cases where signing must happen externally:

createUtxosBegin(params) — Create an unsigned PSBT for UTXO creation
createUtxosEnd(params) — Finalise UTXO creation with a signed PSBT
sendBegin(params) — Create an unsigned PSBT for an RGB send
sendEnd(params) — Finalise an RGB send with a signed PSBT
sendBtcBegin(params) — Create an unsigned PSBT for a BTC send
sendBtcEnd(params, mnemonic?) — Finalise a BTC send with a signed PSBT

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);

What Utexo Is

Getting Started

Product Suite

Installation

Initialisation

Networks

Vanilla vs Colored Addresses

Vanilla vs Colored Addresses

Networks

UTXO Management

Asset Methods

BTC Methods

Key Derivation and Backup

PSBT Methods

Lightning Methods

On-chain Methods

Security

Further Reading

​Installation

​Initialisation

​Networks

​Vanilla vs Colored Addresses

​Vanilla vs Colored Addresses

​Networks

​UTXO Management

​Asset Methods

​BTC Methods

​Key Derivation and Backup

​PSBT Methods

​Lightning Methods

​On-chain Methods

​Security

​Further Reading

Installation

Initialisation

Networks

Vanilla vs Colored Addresses

Vanilla vs Colored Addresses

Networks

UTXO Management

Asset Methods

BTC Methods

Key Derivation and Backup

PSBT Methods

Lightning Methods

On-chain Methods

Security

Further Reading