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

# General Overview

> Overview of the Utexo SDK family — Web, React Native, and WDK (Node.js / Bare) client libraries for RGB asset operations and Lightning.

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.

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

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

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

## Further Reading

* [Product Suite](/getting-started/product-suite) — How the SDK fits into the full Utexo product surface.
* [Architecture](/getting-started/architecture) — The Bitcoin + RGB stack the SDK operates on.
* [Quickstart](/getting-started/quickstart) — Step-by-step guide to your first Utexo integration.

## Platform SDKs

| Page | Package | Platform |
| - | - | - |
| [wdk-rgb-lightning](/sdk/wdk-rgb-lightning) | `@utexo/wdk-rgb-lightning` | Node.js & Bare — current RGB Lightning module |
| [React Native SDK](/sdk/react-native-sdk) | `@utexo/rgb-sdk-rn` | iOS and Android — full on-device Lightning node |
| [Web SDK](/sdk/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](/sdk/wdk-overview) | — | Shared architecture and `dataDir` coordination |
| [wdk-wallet-rgb](/sdk/wdk-wallet-rgb) | `@utexo/wdk-wallet-rgb` | Stable — RGB asset management |
| [wdk-rgb-lightning](/sdk/wdk-rgb-lightning) | `@utexo/wdk-rgb-lightning` | Pre-1.0 beta — RGB Lightning channels and payments |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.