Web Quickstart

This guide covers browser applications. For Node.js, see the Node.js guide. For iOS and Android, see the React Native guide.

Prerequisites

A modern browser with WebAssembly support
A bundler that supports WebAssembly, such as Vite
Bitcoin test funds for transaction fees
A separately initialized sender wallet that already holds the RGB asset for an end-to-end transfer

This guide uses the utexo network profile for Utexo’s hosted signet infrastructure. Never use mainnet keys or real funds while following this guide.

Step 1: Install the SDK

npm install @utexo/rgb-sdk-web

The package targets browser environments and stores wallet state in browser storage. It is not interchangeable with @utexo/wdk-rgb-lightning or @utexo/rgb-sdk-rn.

Step 2: Initialize the Wallet

Initialize the RLN WebAssembly module once, generate keys, then create and unlock the wallet.

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

await initRlnWasm();

const keys = await generateKeys('utexo');
const password = await getPasswordFromSecureInput();

const wallet = new UTEXOWallet({
  mnemonic: keys.mnemonic,
  password,
  network: 'utexo',
});

await wallet.init();
await wallet.unlock();

getPasswordFromSecureInput() represents an application-owned password prompt. Do not hard-code the password, log the mnemonic, or store either value unencrypted in localStorage.

The current Web constructor accepts one parameter object. The older new UTEXOWallet(mnemonic, options) form and initialize() lifecycle shown in previous versions of this page do not match the current implementation.

Step 3: Fund the Wallet

Get a Bitcoin address and send signet BTC to it for transaction fees.

const address = await wallet.getAddress();
console.log('Deposit address:', address);

Wait for the required confirmation before creating RGB UTXOs.

Step 4: Create RGB UTXOs

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

Both num and size are integers. size is denominated in satoshis.

Step 5: 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.

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 asset ID and precision from the funded sender or an authoritative asset registry. Do not use the removed assets.find(...).id pattern.

Step 6: Create a Receive Invoice

Run this on the receiver wallet initialized in Step 2:

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 is 10 ** precision base units.

Step 7: Send From the Funded Wallet

The current Web API uses onchainSend(), not send().

const sendResult = await senderWallet.onchainSend({
  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 signet BTC and a spendable balance of the asset.

Step 8: Refresh and Verify

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. Refresh both wallets before treating a missing settled balance as a failure.

Lightning Payments

Lightning requires usable peer and channel state in addition to an initialized wallet. For a BTC-only invoice, omit the asset field.

const invoice = await wallet.createLightningInvoice({
  amountSats: 3000,
  expirySeconds: 900,
});

const payment = await senderWallet.payLightningInvoice({
  lnInvoice: invoice.lnInvoice,
});

const status = await senderWallet.getLightningSendStatus(payment.txid);
console.log('Lightning payment status:', status);

For an RGB-asset Lightning invoice, pass asset: { assetId, amount } when creating the invoice. Do not pass an empty asset object for a BTC-only invoice.

Web-Specific Notes

Call initRlnWasm() before constructing a wallet.
Persist wallet state and secrets according to the SDK’s backup guidance. Clearing site data can remove local wallet state.
Use HTTPS in production so browser storage and secure-context APIs are available.
Endpoint defaults are resolved by the utexo network profile. Override them only when operating compatible infrastructure.

Troubleshooting

Issue	Likely cause	Check
WebAssembly fails to load	Bundler or MIME configuration	Verify the generated `.wasm` asset is served and allowed by CSP
`init()` or `unlock()` fails	Endpoint, password, or stored-state problem	Check the browser console and network requests without exposing secrets
`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`
`onchainSend()` fails	Invoice, amount, balance, or transport problem	Confirm the invoice is unexpired and the amount is in base units

What Utexo Is

Getting Started

Product Suite

API Reference

Prerequisites

Step 1: Install the SDK

Step 2: Initialize the Wallet

Step 3: Fund the Wallet

Step 4: Create RGB UTXOs

Step 5: Resolve the Asset From the Sender

Step 6: Create a Receive Invoice

Step 7: Send From the Funded Wallet

Step 8: Refresh and Verify

Lightning Payments

Web-Specific Notes

Troubleshooting

Implementation References

Next Steps

​Prerequisites

​Step 1: Install the SDK

​Step 2: Initialize the Wallet

​Step 3: Fund the Wallet

​Step 4: Create RGB UTXOs

​Step 5: Resolve the Asset From the Sender

​Step 6: Create a Receive Invoice

​Step 7: Send From the Funded Wallet

​Step 8: Refresh and Verify

​Lightning Payments

​Web-Specific Notes

​Troubleshooting

​Implementation References

​Next Steps

Prerequisites

Step 1: Install the SDK

Step 2: Initialize the Wallet

Step 3: Fund the Wallet

Step 4: Create RGB UTXOs

Step 5: Resolve the Asset From the Sender

Step 6: Create a Receive Invoice

Step 7: Send From the Funded Wallet

Step 8: Refresh and Verify

Lightning Payments

Web-Specific Notes

Troubleshooting

Implementation References

Next Steps