DApp Connectivity

Overview

The KaleidoSwap Extension injects standard wallet providers into browser pages so DApps can interact with wallet capabilities after user approval. It follows the same provider conventions as other browser wallets (e.g., Alby), so most existing WebLN, WebBTC, and Nostr apps work without any KaleidoSwap-specific integration. The extension injects:

window.webln — WebLN provider for Lightning (invoices, payments, message signing, keysend, LNURL).
window.webbtc — WebBTC provider for on-chain Bitcoin (addresses, PSBT signing, BIP-322 message signing, broadcasting).
window.nostr — full NIP-07 provider for Nostr event signing and encryption.
window.bitcoin — a Bitcoin Wallet Standard provider (Unisat/OKX/Leather-style) that some DApps probe for on-chain accounts.
window.rgb — a KaleidoSwap-specific provider for RGB assets: issue, receive, send and track assets, and, with a Lightning node, pay and receive them over Lightning.

How It Works

The KaleidoSwap Extension’s content script is injected into web pages
The content script loads an injected script that adds window.webln, window.webbtc, window.nostr, window.bitcoin, and window.rgb
DApps call methods on those providers
Requests are routed to the KaleidoSwap Extension background service worker
Sensitive operations trigger a confirmation or permission prompt

Provider Ready Events

The injected script dispatches ready events (both with and without the colon, for SDK parity) once the providers are installed:

webln:ready / weblnReady
webbtc:ready / webbtcReady
nostr:ready
bitcoin:ready
rgb:ready

Error Codes

Every provider rejects with an Error that carries a code property, so a DApp can tell a user’s “no” from a wallet fault:

Code	Meaning
`USER_REJECTED`	The user declined the connection or the confirmation prompt
`NOT_ENABLED`	The provider was called before `enable()` resolved for this origin
`METHOD_NOT_SUPPORTED`	The connected wallet cannot serve this method (for example RGB over Lightning on a node-less RGB wallet)
`INTERNAL_ERROR`	Anything else, with the wallet’s message in `error.message`

WebLN Provider

window.webln follows the WebLN spec and can be used to:

Request node information
Create Lightning invoices
Send Lightning payments
Sign and verify messages
Send keysend payments
Handle LNURL requests
Read balance details

Supported Methods

Method	Description
`enable()`	Connect the DApp and request approval for the origin
`getInfo()`	Get node information and supported methods
`sendPayment(paymentRequest)`	Pay a BOLT-11 invoice
`makeInvoice(args)`	Create a Lightning invoice
`signMessage(message)`	Sign a message with the node key
`verifyMessage(signature, message)`	Verify a signed message
`keysend(args)`	Send a spontaneous (keysend) payment
`lnurl(input)`	Handle an LNURL request
`getBalance()`	Get wallet balance details
`request(method, params)`	Low-level passthrough request

Example Usage

window.addEventListener('webln:ready', async () => {
  await window.webln.enable();

  const info = await window.webln.getInfo();

  const { paymentRequest } = await window.webln.makeInvoice({
    amount: 1000,
    defaultMemo: 'Coffee'
  });

  const { preimage } = await window.webln.sendPayment('lnbc...');
});

WebBTC Provider

window.webbtc is an on-chain Bitcoin provider that can:

Return a receive address
Sign and finalize PSBTs
Sign messages (BIP-322)
Broadcast raw transactions
Send on-chain payments

Supported Methods

Method	Description
`enable()`	Connect the DApp and request approval for the origin
`getInfo()`	Get node/network information and supported methods
`getAddress()`	Get an on-chain receive address
`signPsbt(psbtHex)`	Sign wallet-owned inputs in a PSBT
`finalizePsbt(psbtHex)`	Finalize a signed PSBT into broadcastable hex
`broadcastTransaction(txHex)`	Broadcast a raw, signed transaction
`signMessage(message, address?)`	Sign a message (BIP-322)
`sendPayment(paymentRequest)`	Pay a BIP-21 or BOLT-11 request
`sendTransaction(address, amount)`	Send an on-chain payment

Some DApps probe window.bitcoin (a Bitcoin Wallet Standard provider) instead of, or alongside, window.webbtc. It exposes connect(), getAccounts(), getPublicKey(), signMessage(), signPsbt(), pushPsbt(), and sendBitcoin() over the same wallet keys.

PSBT Confirmations

Approving signPsbt, finalizePsbt, or pushPsbt is never blind-signing: the confirmation prompt decodes the PSBT and shows the destinations, amounts, and network fee before you approve. If the amounts cannot be decoded from the PSBT, the prompt shows an explicit warning instead.

PSBT signing confirmation decoding the transaction total, each output with its destination and amount, and the network fee

RGB Provider

window.rgb exposes the wallet’s RGB runtime to DApps — the node-less RGB wallet or a connected RGB Lightning node, whichever the wallet is configured with — so an app can issue, receive, send and track RGB assets without running its own RGB backend. Every funds-touching call confirms in the extension popup, and the connect prompt lets the user restrict an origin to specific capabilities (minting is gated by its own issueAsset capability).

window.rgb ships from extension 0.3.0 on. It is not present in 0.2.0 builds; feature-detect it with the rgb:ready event rather than assuming it exists.

TypeScript Support

The @kaleidorg/webrgb package ships the window.rgb declarations and a requestProvider() helper that waits for the rgb:ready event when the page runs before the wallet:

npm install @kaleidorg/webrgb

import { requestProvider } from "@kaleidorg/webrgb";

const rgb = await requestProvider(); // typed RgbProvider, or rejects with METHOD_NOT_SUPPORTED
await rgb.enable();

Supported Methods

Method	Description
`enable()`	Connect the DApp; shares the origin approval with the other providers
`getInfo()`	`{ ready, network, protocol, methods }` — `ready` is `false` when no RGB wallet is connected
`getAddress()`	Bitcoin address of the RGB wallet, used to anchor RGB state
`blindReceive(args)`	Blinded-UTXO receive invoice for an asset (`assetId`, optional `amount`, `durationSeconds`, `minConfirmations`)
`issueAsset(args)`	Issue a new asset (`schema: "nia"`, `ticker`, `name`, `amounts`, `precision`); listed in `methods` only when the wallet can mint
`listAssets()`	Assets held by the wallet
`getAssetBalance(assetId)`	`{ assetId, balance }` for one asset
`sendAsset(args)`	Send against a receiver’s RGB invoice (`{ invoice }`) or explicitly (`assetId`, `amount`, `recipientId`)
`listTransfers(assetId?)`	Transfer history, optionally filtered by asset
`getTransferStatus(id, assetId?)`	One transfer by index, recipient id or txid
`makeLnInvoice(args)`	BOLT-11 invoice carrying an asset (`assetId`, optional `assetAmount`, `amountSats`, `description`, `expirySeconds`); RGB Lightning wallets only
`payLnInvoice(args)`	Pay a BOLT-11 invoice that carries an asset (`{ invoice }`); RGB Lightning wallets only
`on(event, listener)` / `off(event, listener)`	Subscribe to `transferReceived` and `transferSettled`

Example Usage

window.addEventListener("rgb:ready", async () => {
  await window.rgb.enable();

  const info = await window.rgb.getInfo();
  // { ready: true, network: "signet", protocol: "RGB_L1" | "RGB_LN", methods: [...] }

  const { invoice } = await window.rgb.blindReceive({
    assetId: "rgb:…",
    amount: 1, // omit for an any-amount invoice
  });

  // Preferred: send against the receiver's RGB invoice
  await window.rgb.sendAsset({ invoice: "rgb:…/…utxob:…" });
});

RGB over Lightning

When the wallet’s RGB runtime is a Lightning node, getInfo().protocol is "RGB_LN" and methods also lists makeLnInvoice and payLnInvoice. On a node-less RGB wallet both reject with METHOD_NOT_SUPPORTED.

// Receive: a BOLT-11 invoice that carries the asset. `amountSats` is the
// Bitcoin the HTLC carries; the node enforces a floor and the wallet
// raises the figure to it, which is what the confirmation shows.
const { invoice, paymentHash } = await window.rgb.makeLnInvoice({
  assetId: "rgb:…",
  assetAmount: 5, // omit for an any-amount invoice
  description: "tickets",
});

// Pay: the invoice must carry an asset with an explicit amount. Plain
// Bitcoin invoices are refused — use window.webln.sendPayment() for those.
const { preimage, assetId, assetAmount } = await window.rgb.payLnInvoice({ invoice: "lnbc…" });

Both calls confirm in the popup with the asset, its units and the sats the HTLC carries. Spending allowances do not apply to asset payments: every payLnInvoice prompts.

Events

window.rgb.on("transferReceived", (t) => { /* new incoming transfer seen */ });
window.rgb.on("transferSettled", (t) => { /* a known transfer reached Settled */ });

The payload is { assetId, transferId, status, kind, amount, recipientId, txid }. Events are pushed by a background poll that runs about once a minute while a subscribed origin has an open tab, so there is no need to poll listTransfers() in a loop — but do not expect sub-minute latency.

Nostr Provider (NIP-07)

The KaleidoSwap Extension injects a full NIP-07 provider at window.nostr, so Nostr web apps can request the wallet’s public key, sign events, and encrypt or decrypt direct messages. The Nostr identity is derived from the wallet recovery phrase (or an imported identity, when set).

Supported Methods

Method	Description
`getPublicKey()`	Return the wallet’s Nostr public key (hex)
`signEvent(event)`	Sign a Nostr event
`getRelays()`	Return the configured relays
`signSchnorr(sigHash)`	Sign a 32-byte hash with the Nostr key
`nip04.encrypt(pubkey, plaintext)` / `nip04.decrypt(pubkey, ciphertext)`	NIP-04 encryption
`nip44.encrypt(pubkey, plaintext)` / `nip44.decrypt(pubkey, ciphertext)`	NIP-44 encryption

Example Usage

window.addEventListener('nostr:ready', async () => {
  const pubkey = await window.nostr.getPublicKey();

  const signed = await window.nostr.signEvent({
    kind: 1,
    content: 'Hello from KaleidoSwap',
    tags: [],
    created_at: Math.floor(Date.now() / 1000)
  });
});

Nostr Connect (NIP-46)

Beyond in-page NIP-07 signing, the extension can act as a remote signer for Nostr apps that support NIP-46 (nsecBunker). From Settings > Nostr Connect, generate a bunker:// connection string and paste it into the client app; signing requests then travel over Nostr relays and are approved in the extension. Active NIP-46 sessions appear in Connected Apps, where they can be reviewed and revoked.

Nostr Connect remote signing screen with a listening status, the generated bunker connection string, and a revoke action

Nostr Wallet Connect (NWC)

The extension can also expose the wallet to external apps over Nostr Wallet Connect: pair an app by scanning the pairing QR code, then control what it can do with amount-aware budgets. Zap payments (NIP-57) made through NWC are validated and correlated with wallet activity.

For Developers

NWC is the integration path for anything that is not a web page in the same browser — mobile apps, desktop clients, bots and backends. The extension acts as the NIP-47 wallet service; any NIP-47 client library works against it, so nothing KaleidoSwap-specific is required. The pairing string generated in Settings > Nostr Wallet Connect has the standard shape:

nostr+walletconnect://<wallet-pubkey>?relay=<wss-relay-url>&secret=<client-secret>

The service announces NIP-47 version 1.0 with nip04 and nip44_v2 encryption and supports these methods:

Method	Notes
`get_info`	Node alias, network, supported methods and encryptions
`get_balance`	Spendable Lightning balance
`make_invoice`	Create a BOLT-11 invoice
`pay_invoice`	Pay a BOLT-11 invoice; prompts unless the request fits the client’s budget
`multi_pay_invoice`	Pay several invoices in one request, each judged against the budget
`lookup_invoice`	Look up an invoice by payment hash or BOLT-11
`list_transactions`	Recent incoming and outgoing payments
`sign_message`	Sign a message with the node key

Each paired client gets its own spending budget, visible and revocable under Settings > Connected Apps. A payment within budget settles without a prompt; anything over it opens the same confirmation window the in-page providers use.

Permission Prompts and Connected Apps

When a connected site makes a sensitive request, the KaleidoSwap Extension asks the user to approve or deny the action. Connected Nostr clients start from a “Reasonable” consent default (comparable to other NIP-07 wallets): routine, low-risk operations are allowed for a connected app, while payments and other sensitive actions still prompt.

Connection approval prompt showing the requesting site origin, the access it asks for, and the Reasonable consent default with Deny and Allow actions

Settings > Connected Apps lists every site and app connected to the wallet, showing which capabilities each one has been granted. You can revoke individual capabilities or disconnect a site entirely at any time.

Connected Apps screen listing connected apps, Nostr Wallet Connect sessions, and a field to block a site

Always review what a DApp is requesting before approving. Only approve payments, invoices, asset sends, and signing requests from sites you trust.

Nostr Identity

The KaleidoSwap Extension derives a Nostr identity from the wallet recovery phrase (or an imported identity) and exposes it both to web pages through window.nostr and in the extension settings.

Nostr Key Management

Your Nostr keypair is managed in Settings > Nostr Account:

View your public key (npub)
View/copy the session private key when the wallet is unlocked
Re-derive identity from the wallet recovery phrase

By default the identity is derived from the recovery phrase (NIP-06). If you already have a Nostr identity, you can import your own key (nsec1… or 64-character hex) during onboarding or later from Settings; it is stored encrypted and used everywhere the derived identity would be.

Browser Approval Flow

The KaleidoSwap Extension keeps DApp approvals user-driven:

A trusted site requests a connection, payment, invoice, asset, or signing action
The KaleidoSwap Extension routes the request through the content script and background service worker
The user reviews the details and approves or rejects the action

This keeps wallet-side actions explicit while still allowing DApps to use the KaleidoSwap Extension as a browser provider.

Security Considerations

Practice	Description
Verify the site	Check the URL before approving wallet connections
Review requests	Read invoice, asset, and signing details before approving
Lock when done	Lock the KaleidoSwap Extension when you are finished using DApps
Limit exposure	Only connect to trusted sites

Access the Beta

Request access to the KaleidoSwap Extension closed beta.

Introduction

Features

Reference

Overview

How It Works

Provider Ready Events

Error Codes

WebLN Provider

Supported Methods

Example Usage

WebBTC Provider

Supported Methods

PSBT Confirmations

RGB Provider

TypeScript Support

Supported Methods

Example Usage

RGB over Lightning

Events

Nostr Provider (NIP-07)

Supported Methods

Example Usage

Nostr Connect (NIP-46)

Nostr Wallet Connect (NWC)

For Developers

Permission Prompts and Connected Apps

Nostr Identity

Nostr Key Management

Browser Approval Flow

Security Considerations

Access the Beta

​Overview

​How It Works

​Provider Ready Events

​Error Codes

​WebLN Provider

​Supported Methods

​Example Usage

​WebBTC Provider

​Supported Methods

​PSBT Confirmations

​RGB Provider

​TypeScript Support

​Supported Methods

​Example Usage

​RGB over Lightning

​Events

​Nostr Provider (NIP-07)

​Supported Methods

​Example Usage

​Nostr Connect (NIP-46)

​Nostr Wallet Connect (NWC)

​For Developers

​Permission Prompts and Connected Apps

​Nostr Identity

​Nostr Key Management

​Browser Approval Flow

​Security Considerations

Access the Beta

Overview

How It Works

Provider Ready Events

Error Codes

WebLN Provider

Supported Methods

Example Usage

WebBTC Provider

Supported Methods

PSBT Confirmations

RGB Provider

TypeScript Support

Supported Methods

Example Usage

RGB over Lightning

Events

Nostr Provider (NIP-07)

Supported Methods

Example Usage

Nostr Connect (NIP-46)

Nostr Wallet Connect (NWC)

For Developers

Permission Prompts and Connected Apps

Nostr Identity

Nostr Key Management

Browser Approval Flow

Security Considerations