RGB Web lN Provider API Documentation

Using rgb-webln-sdk

Typed client for working with the injected provider.

Installation

npm i rgb-webln-sdk

Quick Start

import { rgbweblnClient, waitForrgbwebln } from 'rgb-webln-sdk';

const provider = await waitForrgbwebln();
const rgbwebln = new rgbweblnClient(provider);
await rgbwebln.enable();

const info = await rgbwebln.getInfo();
const { address } = await rgbwebln.getAddress();

React Hook Example

import { useEffect, useState } from 'react';
import { rgbweblnClient, waitForrgbwebln } from 'rgb-webln-sdk';

export function usergbwebln() {
  const [client, setClient] = useState<rgbweblnClient | null>(null);
  const [ready, setReady] = useState(false);

  useEffect(() => {
    (async () => {
      try {
        const provider = await waitForrgbwebln();
        const rgbwebln = new rgbweblnClient(provider);
        await rgbwebln.enable();
        setClient(rgbwebln);
        setReady(true);
      } catch (e) {
        console.error('rgbwebln init failed', e);
      }
    })();
  }, []);

  return { client, ready };
}

Raw Request (Forward Compatibility)

const state = await rgbwebln.request('request.listchannels');

TypeScript Types

All request/response interfaces are exported:

import type { ListAssetsResponse, SendRGBAsset, InvoiceDecoded } from 'rgbwebln-sdk';

Tip: Always call enable() before making requests that require user consent.

rgbwebln.enable()

To begin interacting with rgbwebln APIs you'll first need to enable the provider. Calling rgbwebln.enable() will prompt the user for permission to use the wallet capabilities of the browser. After that you are free to call any of the other API methods.

Method

async function enable(origin?: string): Promise<void>;

Example

if (typeof window.rgbwebln !== 'undefined') {
  await window.rgbwebln.enable();
  console.log("rgbwebln enabled!");
}

rgbwebln.isEnabled()

Check if the current origin has already been approved to use rgbwebln APIs.

Method

async function isEnabled(): Promise<boolean>;

Example

const approved = await rgbwebln.isEnabled();
console.log("Approved?", approved);

rgbwebln.getInfo()

Get information about the connected node and which rgbwebln methods it supports.

Method

async function getInfo(): Promise<GetInfoResponse>;

Response

interface GetInfoResponse {
  node: {
    alias: string;
    pubkey: string;
    color?: string;
  };
  methods: string[]; // e.g. "rgbInvoice", "sendAsset"
}

Example

await rgbwebln.enable();
const info = await rgbwebln.getInfo();
console.log(info.node.alias, info.methods);

rgbwebln.getAddress()

Request a Bitcoin address from the wallet.

Method

async function getAddress(): Promise<AddressResponse>;

Response

interface AddressResponse {
  address: string;
}

Example

const { address } = await rgbwebln.getAddress();
console.log("Receive BTC at:", address);

rgbwebln.rgbInvoice()

Create an RGB invoice for a specific asset and amount.

Method

async function rgbInvoice(params: RGBInvoiceRequest): Promise<RgbInvoiceResponse>;

Request

interface RGBInvoiceRequest {
  asset_id?: string;
  amount?: number;
  duration_seconds: number;
  min_confirmations: number;
}

Response

interface RgbInvoiceResponse {
  invoice: string;
}

Example

const invoice = await rgbwebln.rgbInvoice({
  asset_id: 'rgb:icfqnK9y...',
  amount: 42,
  duration_seconds: 900,
  min_confirmations: 1,
});
console.log(invoice.invoice);

rgbwebln.decodeRgbInvoice()

Decode an RGB invoice into its structured details.

Method

async function decodeRgbInvoice(params: DecodeInvoiceRequest): Promise<InvoiceDecoded>;

Request

interface DecodeInvoiceRequest {
  invoice: string;
}

Response

interface InvoiceDecoded {
  recipient_id: string;
  asset_id: string;
  assignment: Assignment;
  transport_endpoints: string[];
  asset_schema: string;
  network: string;
  expiration_timestamp: number;
}

Example

const decoded = await rgbwebln.decodeRgbInvoice({ invoice: invoice.invoice });
console.log(decoded.asset_id, decoded.assignment.value);

rgbwebln.sendAsset()

Send an RGB asset to a recipient.

Method

async function sendAsset(params: SendRGBAsset): Promise<TXIdResponse>;

Request

interface SendRGBAsset {
  recipient_id: string;
  asset_id: string;
  assignment: Assignment;
  transport_endpoints: string[];
  donation: boolean;
  fee_rate: number;
  min_confirmations: number;
  skip_sync: boolean;
}

Response

interface TXIdResponse {
  txid: string;
}

Example

const tx = await rgbwebln.sendAsset({
  recipient_id: decoded.recipient_id,
  asset_id: decoded.asset_id,
  assignment: decoded.assignment,
  transport_endpoints: decoded.transport_endpoints,
  donation: false,
  fee_rate: 2,
  min_confirmations: 1,
  skip_sync: false,
});
console.log("TXID:", tx.txid);

rgbwebln.listTransfers()

List transfers for a given asset.

Method

async function listTransfers(params: { assetId: string }): Promise<ListTransfersResponse>;

Response

interface ListTransfersResponse {
  transfers: RgbTransfer[];
}

interface RgbTransfer {
  idx: number;
  created_at: number;
  updated_at: number;
  status: string;
  txid: string;
  recipient_id: string;
}

Example

const transfers = await rgbwebln.listTransfers({ assetId: 'rgb:icfqnK9y...' });
console.log(transfers.transfers);

rgbwebln.listAssets()

List assets managed by the wallet.

Method

async function listAssets(): Promise<ListAssetsResponse>;

Response

interface ListAssetsResponse {
  nia: NiaAsset[];
  uda: UdaAsset[];
  cfa: CfaAsset[];
}

Example

const assets = await rgbwebln.listAssets();
console.log(assets.nia, assets.uda, assets.cfa);

rgbwebln.getNetworkInfo()

Get current network information (network type and block height).

Method

async function getNetworkInfo(): Promise<NetworkInfoResponse>;

Response

interface NetworkInfoResponse {
  network: string;
  height: number;
}

Example

const net = await rgbwebln.getNetworkInfo();
console.log(net.network, net.height);

rgbwebln.getBTCBalance()

Get the Bitcoin balance for the wallet.

Method

async function getBTCBalance(): Promise<BTCBalance>;

Response

interface BTCBalance {
  vanilla: {
    settled: number;
    future: number;
    spendable: number;
  };
  colored: {
    settled: number;
    future: number;
    spendable: number;
  };
}

Example

const bal = await rgbwebln.getBTCBalance();
console.log("BTC balance:", bal.vanilla.spendable, "sats");

Events

Wallets can emit events to notify dapps about changes. Subscribe with rgbwebln.on(event, listener) and unsubscribe with rgbwebln.off(event, listener).

Methods

function on(event: string, listener: (payload: any) => void): void;
function off(event: string, listener: (payload: any) => void): void;

Supported Events

• rgbwebln_ready – Provider injected and ready.

  • Payload: { version: string }

• rgbwebln_nodeChanged – Active node scope changed.

  • Payload: {} (reserved for future use)

• rgbwebln_networkChanged – Network switched (e.g., Testnet → Mainnet).

  • Payload: { network: 'Mainnet' | 'Testnet' | 'Regtest' }

• rgbwebln_transferUpdated – RGB transfer state progressed.

  • Payload: { assetId: string; transfer: RgbTransfer }

• rgbwebln_permissionRevoked – User revoked this origin’s permission.

  • Payload: {}

Example

const onTransfer = (p: { assetId: string; transfer: RgbTransfer }) => {
  console.log('Transfer update:', p.transfer.status);
};

rgbwebln.on('rgbwebln_transferUpdated', onTransfer);

// Later
rgbwebln.off('rgbwebln_transferUpdated', onTransfer);