BIVVY DOCS

A small, familiar API.

A focused bridge to the things your app needs.

Bivvy

Method	Returns
`bivvy.connect()`	{ pubkey }
`bivvy.disconnect()`	void
`bivvy.destroy()`	void; removes the iframe and rejects pending requests

Bitcoin

Method	Returns
`bivvy.bitcoin.getBalance()`	{ balance: string }
`bivvy.bitcoin.getOnchainAddress()`	string
`bivvy.bitcoin.getTransfers(limit?, offset?)`	{ transfers, offset }
`bivvy.bitcoin.createLightningInvoice({ amountSats, memo? })`	{ id, invoice, status }
`bivvy.bitcoin.payLightningInvoice({ invoice, maxFeeSats? })`	{ id, status, paymentPreimage? }
`bivvy.bitcoin.estimateOnchainFee({ address, amountSats, speed? })`	{ feeSats, expiresAt }
`bivvy.bitcoin.sendOnchain({ address, amountSats, maxFeeSats, speed? })`	{ id, status, amountSats, feeSats, txid? }

Nostr

Method	Returns
`bivvy.nostr.getPublicKey()`	string
`bivvy.nostr.signEvent(event)`	signed Nostr event
`bivvy.nostr.getRelays()`	relay preferences
`bivvy.nostr.nip44.encrypt(pubkey, text)`	ciphertext
`bivvy.nostr.nip44.decrypt(pubkey, ciphertext)`	plaintext
`bivvy.nostr.nip04.encrypt(pubkey, text)`	ciphertext (legacy)
`bivvy.nostr.nip04.decrypt(pubkey, ciphertext)`	plaintext (legacy)

Errors

Requests reject with a BivvyError containing a code and message. Handle errors without assuming a payment failed before submission.

JavaScript

try {
  await bivvy.nostr.getPublicKey();
} catch (error) {
  if (error.code === "BUSY") {
    // Finish the current request first.
  } else {
    showError(error.message);
  }
}

`REJECTED`	User declined, closed the popup, or the operation failed.
`INVALID_REQUEST`	Unknown method, invalid parameters, or prohibited values.
`BUSY`	Another request is being reviewed or executed.
`REPLAY`	The request ID was already received.
`TIMEOUT`	No response within 3 minutes; payment outcome may be unknown.
`UNAVAILABLE`	Bivvy could not load within 20 seconds.
`DISCONNECTED`	The iframe was removed and pending requests were cancelled.
`PAYMENT_PENDING`	WebLN has no settled payment preimage yet.

Events and globals

The script dispatches bivvy:ready after creating window.bivvy. It installs window.nostr and window.webln only when those globals are absent. Requests mount the iframe lazily.

Amounts and limits

Satoshi inputs must be positive safe integers. Bivvy returns balances as decimal strings to avoid precision loss. The default Lightning fee cap is 100 sats. Supply a smaller explicit cap if your app requires one.

Made to be understood. Built to be yours.View the source