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.

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, and window.bitcoin
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

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

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.

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

WebLN Provider

Supported Methods

Example Usage

WebBTC Provider

Supported Methods

PSBT Confirmations

Nostr Provider (NIP-07)

Supported Methods

Example Usage

Nostr Connect (NIP-46)

Nostr Wallet Connect (NWC)

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

​WebLN Provider

​Supported Methods

​Example Usage

​WebBTC Provider

​Supported Methods

​PSBT Confirmations

​Nostr Provider (NIP-07)

​Supported Methods

​Example Usage

​Nostr Connect (NIP-46)

​Nostr Wallet Connect (NWC)

​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

WebLN Provider

Supported Methods

Example Usage

WebBTC Provider

Supported Methods

PSBT Confirmations

Nostr Provider (NIP-07)

Supported Methods

Example Usage

Nostr Connect (NIP-46)

Nostr Wallet Connect (NWC)

Permission Prompts and Connected Apps

Nostr Identity

Nostr Key Management

Browser Approval Flow

Security Considerations