General Overview

The Utexo SDK provides programmatic access to the Utexo execution layer, enabling applications to issue, transfer, and receive RGB assets on Bitcoin without operating nodes, managing channels, or handling protocol-level infrastructure. It exposes a clean set of async methods organised around wallet management, RGB asset operations, on-chain Bitcoin interactions, and Lightning payments. All operations are performed locally using client-side validation — no shared state is sent to a central server during normal execution.

SDK Family

The Utexo SDK is available across three application platforms. @utexo/rgb-sdk (Node.js) is archived; new Node.js integrations should use @utexo/wdk-rgb-lightning. A separate Wallet Development Kit (WDK) layer is available for builders who need lower-level wallet abstractions:

Package	Platform	Use case
`@utexo/wdk-rgb-lightning`	Node.js & Bare	Current Node.js / Bare path — RGB Lightning channels, invoices, payments, LSP
`@utexo/rgb-sdk-web`	Browser / JS/TS	Web apps, embedded wallets, in-browser RLN via WASM
`@utexo/rgb-sdk-rn`	React Native	iOS and Android — full on-device Lightning node via RLN
`@utexo/wdk-wallet-rgb`	Node.js & Bare	WDK-compatible on-chain RGB asset management
`@utexo/rgb-sdk`	Node.js (archived)	Legacy server-side SDK — do not use for new integrations

@utexo/rgb-sdk-rn and @utexo/rgb-sdk-web ship with full Lightning support via an on-device / in-browser RLN node. The archived @utexo/rgb-sdk Node.js package does not. The Web and React Native SDKs share @utexo/rgb-sdk-core, which contains common interfaces, base classes, unified types, transport configuration, and UTEXO network mappings. This page covers the SDK family. Refer to the platform reference pages for method-level details.

What the SDK Provides

Wallet management — key generation, derivation, initialisation, backup, and restore (including VSS cloud backup); address rotation following HD wallet best practices
RGB asset operations — asset issuance, blinded and witness invoices, asset transfers, and balance queries
Lightning payments — invoice creation, synchronous payment execution (begin → sign → end flow), HODL invoice support for offline recipients, Lightning Address integration, and payment status queries
Async payments — LSP-routed delivery so recipients can collect payments when they come online; inbound leg fully operational, outbound leg in active development
On-chain interactions — deposit address generation, BTC balance queries, on-chain withdrawal
UTXO management — UTXO creation, listing, and state sync

Key Concepts

Vanilla vs Colored Addresses

The SDK operates two distinct address and key derivation paths:

Vanilla — the standard Bitcoin derivation path. Vanilla outputs hold regular BTC and are used for fee payments, on-chain withdrawals, and funding operations. getAddress() returns a vanilla bech32 receive address.
Colored — the RGB-specific derivation path. Colored outputs carry RGB asset allocations anchored to Bitcoin UTXOs. This path is used internally when creating UTXOs for RGB operations.

getXpub() returns both the vanilla xpub (accountXpubVanilla) and the colored xpub (accountXpubColored). getBtcBalance() returns separate balances for each path, each with settled, future, and spendable fields.

Before issuing or receiving RGB assets, the wallet must have colored UTXOs prepared. Call createUtxos() after funding the vanilla address to set up the UTXO structure required for RGB allocations.

Invoice Types: Blinded vs Witness

RGB receive flows support two invoice styles:

Blinded invoice — most common. The receiver creates a blinded endpoint; the sender pays the invoice directly. Use this for standard app-to-app RGB transfers.
Witness invoice — the receiver binds the transfer to witness data. The sender must provide witnessData (at minimum amountSat on Web/RN, amountSats on WDK) when sending. Use this when the integration requires witness-bound receive semantics.

On Web and React Native, receive with onchainReceive({ witness: false }) for blinded or the default witness invoice, then send with onchainSend(). On @utexo/wdk-rgb-lightning, receive with createRgbInvoice({ witness: false | true, ... }) and send with transfer().

Backup and Restore

The SDK provides two backup mechanisms for wallet state. Backups are recommended after every significant state change (UTXO creation, asset issuance, transfer):

File backup (createBackup) — creates an encrypted local backup containing both layer1 and utexo state files. Restore with restoreUtxoWalletFromBackup().
VSS backup (vssBackup) — pushes wallet state to a remote Verifiable Secret Sharing server. The backup is keyed to the wallet mnemonic. Restore with restoreUtxoWalletFromVss(). Call vssBackupInfo() to check backup existence and whether a new backup is required.

Private Key Export

The SDK exposes getXprivFromMnemonic(network, mnemonic) to derive the extended private key (xpriv) from a mnemonic. This is the account root private key material from which all child keys can be derived. Treat xpriv with the same sensitivity as the mnemonic itself — do not log or transmit it in production.

Execution Model

New Node.js integrations use @utexo/wdk-rgb-lightning. The primary entry point is WalletManagerRgbLightning, which takes the seed mnemonic at construction and unlocks a single Lightning account:

const manager = new WalletManagerRgbLightning(mnemonic, {
  network: 'utexo',
  dataDir: './wallet',
  lspBaseUrl: '...',  // optional — enables async payments
  lspBearerToken: '...' // optional — required when lspBaseUrl is set
})
const account = await manager.getAccount(0)
await account.unlock({ indexer_url, proxy_endpoint, announce_addresses: [], announce_alias: 'my-node' })

The Web and React Native packages use UTEXOWallet (init() then unlock()). See the platform reference pages for that lifecycle. Key execution properties:

All operations are non-custodial — the SDK never transmits private keys or mnemonics
All API calls execute with predefined costs and latency — no fee auction or gas estimation required
Web uses @utexo/rgb-sdk-web (WASM); React Native uses @utexo/rgb-sdk-rn; Node.js uses @utexo/wdk-rgb-lightning
External signer support — the Lightning node runs in external-signer mode; the mnemonic stays in the host secret manager
Async payments are opt-in via lspBaseUrl and lspBearerToken

Networks

The SDK supports three environments. Pass the identifier in the network field of the init config.

Environment	Identifier	RGB Transport	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`

The utexo identifier maps to the Utexo-operated signet environment. It is the default network for development and testing.

In This Section

Platform references for @utexo/wdk-rgb-lightning (Node.js / Bare), @utexo/rgb-sdk-web (browser), @utexo/rgb-sdk-rn (iOS and Android), and the WDK on-chain module @utexo/wdk-wallet-rgb.

Platform SDKs

Page	Package	Platform
wdk-rgb-lightning	`@utexo/wdk-rgb-lightning`	Node.js & Bare — current RGB Lightning module
React Native SDK	`@utexo/rgb-sdk-rn`	iOS and Android — full on-device Lightning node
Web SDK	`@utexo/rgb-sdk-web`	Browser — WASM RLN, including Lightning

Wallet Development Kit (WDK)

The WDK packages expose RGB capabilities through standard wallet abstraction interfaces for builders who already use WDK-compatible account and signing layers.

Page	Package	Status
WDK Overview	—	Shared architecture and `dataDir` coordination
wdk-wallet-rgb	`@utexo/wdk-wallet-rgb`	Stable — RGB asset management
wdk-rgb-lightning	`@utexo/wdk-rgb-lightning`	Pre-1.0 beta — RGB Lightning channels and payments

What Utexo Is

Getting Started

Product Suite

API Reference

SDK Family

What the SDK Provides

Key Concepts

Vanilla vs Colored Addresses

Invoice Types: Blinded vs Witness

Backup and Restore

Private Key Export

Execution Model

Networks

In This Section

Further Reading

Platform SDKs

Wallet Development Kit (WDK)

​SDK Family

​What the SDK Provides

​Key Concepts

​Vanilla vs Colored Addresses

​Invoice Types: Blinded vs Witness

​Backup and Restore

​Private Key Export

​Execution Model

​Networks

​In This Section

​Further Reading

​Platform SDKs

​Wallet Development Kit (WDK)

SDK Family

What the SDK Provides

Key Concepts

Vanilla vs Colored Addresses

Invoice Types: Blinded vs Witness

Backup and Restore

Private Key Export

Execution Model

Networks

In This Section

Further Reading

Platform SDKs

Wallet Development Kit (WDK)