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

# Web Quickstart

> Initialize a browser wallet and prepare an RGB transfer using @utexo/rgb-sdk-web.

<Info>
  This guide covers browser applications. For Node.js, see the [Node.js guide](/getting-started/quickstart/node-js). For iOS and Android, see the [React Native guide](/getting-started/quickstart/react-native).
</Info>

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

<Warning>
  This guide uses the `utexo` network profile for Utexo's hosted signet infrastructure. Never use mainnet keys or real funds while following this guide.
</Warning>

## Step 1: Install the SDK

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

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

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

## Step 3: Fund the Wallet

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

```javascript theme={null}
const address = await wallet.getAddress();
console.log('Deposit address:', address);
```

Wait for the required confirmation before creating RGB UTXOs.

## Step 4: Create RGB UTXOs

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

```javascript theme={null}
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:

```javascript theme={null}
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()`.

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

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

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

## Implementation References

* [Web wallet implementation](https://github.com/UTEXO-Protocol/rgb-sdk-web/blob/dev/src/utexo/utexo-wallet.ts)
* [Web network defaults](https://github.com/UTEXO-Protocol/rgb-sdk-web/blob/dev/src/binding/RlnDefaults.ts)
* [Shared wallet models](https://github.com/UTEXO-Protocol/rgb-sdk-core/blob/dev/src/types/wallet-model.ts)
* [Shared on-chain transfer interface](https://github.com/UTEXO-Protocol/rgb-sdk-core/blob/dev/src/interfaces/wallet/IOnchainTransfers.ts)

## Next Steps

* [SDK Reference](/product-suite/sdk)
* [Architecture](/getting-started/architecture)
* [Glossary](/getting-started/glossary)