From 644d4d22eae0d033200fae49770c3aba2905644c Mon Sep 17 00:00:00 2001
From: Roland Bewick <roland.bewick@gmail.com>
Date: Thu, 5 Feb 2026 23:00:14 +0700
Subject: [PATCH] feat: add refresh balance to the API

---
 README.md                     | 14 ++++++++++++--
 demos/html/bc-api-usage.html  |  2 +-
 demos/html/bc-button.html     |  2 +-
 demos/html/bc-pay-button.html |  2 +-
 package.json                  |  2 +-
 react/package.json            |  4 ++--
 react/src/index.ts            |  1 +
 react/yarn.lock               |  8 ++++----
 src/api.ts                    |  8 ++++++++
 src/components/bc-balance.ts  |  4 ++++
 10 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 5a04dd5..82a3c0a 100644
--- a/README.md
+++ b/README.md
@@ -36,13 +36,13 @@ You can use Bitcoin Connect without any build tools:
 
 ```html
 <script type="module">
-  import {launchModal} from 'https://esm.sh/@getalby/bitcoin-connect@^3.11.0'; // jsdelivr.net, skypack.dev also work
+  import {launchModal} from 'https://esm.sh/@getalby/bitcoin-connect@^3.12.0'; // jsdelivr.net, skypack.dev also work
 
   // use Bitcoin connect API normally...
   launchModal();
 
   // or if you just want access to the web components:
-  import 'https://esm.sh/@getalby/bitcoin-connect@^3.11.0';
+  import 'https://esm.sh/@getalby/bitcoin-connect@^3.12.0';
 </script>
 
 <!-- Bitcoin Connect components are now available -->
@@ -356,6 +356,16 @@ if (connectorConfig) {
 }
 ```
 
+#### Refresh balance
+
+Programmatically trigger a balance refresh for all `<bc-balance>` components on the page. Useful after making a payment or receiving funds to update the displayed balance.
+
+```ts
+import {refreshBalance} from '@getalby/bitcoin-connect';
+
+refreshBalance();
+```
+
 #### Events
 
 ##### onConnected
diff --git a/demos/html/bc-api-usage.html b/demos/html/bc-api-usage.html
index 220521e..4ab4497 100644
--- a/demos/html/bc-api-usage.html
+++ b/demos/html/bc-api-usage.html
@@ -65,7 +65,7 @@ <h1>Programmatic Access Demo</h1>
         launchPaymentModal,
         requestProvider,
         disconnect,
-      } from 'https://esm.sh/@getalby/bitcoin-connect@^3.11.0';
+      } from 'https://esm.sh/@getalby/bitcoin-connect@^3.12.0';
       import {LightningAddress} from 'https://esm.sh/@getalby/lightning-tools@^5.2.0';
 
       // Initialize Bitcoin Connect with your app name
diff --git a/demos/html/bc-button.html b/demos/html/bc-button.html
index 3bfca99..469d83d 100644
--- a/demos/html/bc-button.html
+++ b/demos/html/bc-button.html
@@ -5,7 +5,7 @@
     <meta charset="utf-8" />
     <title>bc-button Demo</title>
     <script type="module">
-      import {onConnected} from 'https://esm.sh/@getalby/bitcoin-connect@^3.11.0';
+      import {onConnected} from 'https://esm.sh/@getalby/bitcoin-connect@^3.12.0';
       onConnected((provider) => {
         console.log('Connected with provider', provider);
       });
diff --git a/demos/html/bc-pay-button.html b/demos/html/bc-pay-button.html
index 5d6259a..a94939c 100644
--- a/demos/html/bc-pay-button.html
+++ b/demos/html/bc-pay-button.html
@@ -7,7 +7,7 @@
 
     <script type="module">
       // Import necessary modules from esm.sh CDN
-      import {init} from 'https://esm.sh/@getalby/bitcoin-connect@^3.11.0';
+      import {init} from 'https://esm.sh/@getalby/bitcoin-connect@^3.12.0';
       import {LightningAddress} from 'https://esm.sh/@getalby/lightning-tools@^5.2.0';
 
       // Initialize Bitcoin Connect with your app name
diff --git a/package.json b/package.json
index 5f31868..48a64f8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getalby/bitcoin-connect",
-  "version": "3.11.5",
+  "version": "3.12.0",
   "description": "Web components to connect to a lightning wallet and power a website with WebLN",
   "type": "module",
   "source": "src/index.ts",
diff --git a/react/package.json b/react/package.json
index c8ff557..f407ed7 100644
--- a/react/package.json
+++ b/react/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@getalby/bitcoin-connect-react",
-  "version": "3.11.5",
+  "version": "3.12.0",
   "type": "module",
   "source": "src/index.ts",
   "main": "./dist/index.cjs",
@@ -28,7 +28,7 @@
     "dts": "dts-bundle-generator dist/index.d.ts -o dist/bundle.d.ts --project tsconfig.dts.json --no-check"
   },
   "dependencies": {
-    "@getalby/bitcoin-connect": "^3.11.5"
+    "@getalby/bitcoin-connect": "^3.12.0"
   },
   "devDependencies": {
     "@types/react": "^18.2.21",
diff --git a/react/src/index.ts b/react/src/index.ts
index 0b3fea9..b47860c 100644
--- a/react/src/index.ts
+++ b/react/src/index.ts
@@ -18,6 +18,7 @@ export {
   onModalOpened,
   onModalClosed,
   getConnectorConfig,
+  refreshBalance,
   WebLNProviders,
   PaymentMethods,
 } from '@getalby/bitcoin-connect';
diff --git a/react/yarn.lock b/react/yarn.lock
index 713da3a..2506ba1 100644
--- a/react/yarn.lock
+++ b/react/yarn.lock
@@ -1018,10 +1018,10 @@
     "@babel/helper-validator-identifier" "^7.22.5"
     to-fast-properties "^2.0.0"
 
-"@getalby/bitcoin-connect@^3.11.5":
-  version "3.11.5"
-  resolved "https://registry.yarnpkg.com/@getalby/bitcoin-connect/-/bitcoin-connect-3.11.5.tgz#9ae3a467e28cb3288bff576c227d90d585e60d34"
-  integrity sha512-8HLJyBoh/uBdho5QV9XxPx+A6d2rXHyJK7hvL2FvKjBZrtPK3Zylg4V8mkrUM0OM96Cz7tCemJM/Xi5tEBqcUg==
+"@getalby/bitcoin-connect@^3.12.0":
+  version "3.12.0"
+  resolved "https://registry.yarnpkg.com/@getalby/bitcoin-connect/-/bitcoin-connect-3.12.0.tgz#146ac63e1b2f12c21973ab9236c6f1db81c18c52"
+  integrity sha512-0Zc3BjNDZOQv/zXZHxpLpE2ZO0NKJ85NT0WWjkhvDID4ZWhO9iNfzTZ4AFjT4qAWPKOxnad+F1du+cRHwZ8KEQ==
   dependencies:
     "@getalby/lightning-tools" "^6.0.0"
     "@getalby/sdk" "^6.0.2"
diff --git a/src/api.ts b/src/api.ts
index 6faab21..1bf0ec2 100644
--- a/src/api.ts
+++ b/src/api.ts
@@ -175,6 +175,14 @@ export function init(config: BitcoinConnectConfig = {}) {
   store.getState().setBitcoinConnectConfig(config);
 }
 
+/**
+ * Refresh the balance of the connected wallet
+ */
+
+export function refreshBalance() {
+  window.dispatchEvent(new CustomEvent('bc:balancerefresh'));
+}
+
 /**
  * Programmatically launch the Bitcoin Connect modal
  */
diff --git a/src/components/bc-balance.ts b/src/components/bc-balance.ts
index a838142..da7eace 100644
--- a/src/components/bc-balance.ts
+++ b/src/components/bc-balance.ts
@@ -27,6 +27,10 @@ export class Balance extends withTwind()(BitcoinConnectElement) {
 
     this._loadBalance();
 
+    window.addEventListener('bc:balancerefresh', () => {
+      this._loadBalance();
+    });
+
     this._selectedCurrency = store.getState().currency;
     store.subscribe((currentState, prevState) => {
       this._selectedCurrency = currentState.currency;