Merge pull request #149 from olegsta/add_balance

Feature: Retrieve All Balances in a Single Call #10

Author: dmytro-samoylenko

README.md

@@ -342,6 +342,11 @@ curl --location --request GET
 Use the `crypto_list` array; the `crypto` array exists only for backward compatibility. In the `crypto_list` array:
 - `name` is used when forming the endpoint for invoice creation requests,
 - `display_name` is the cryptocurrency human-readable format.
+
+**Notes & caveats**
+
+SHKeeper uses a short-lived in-memory TTL cache to speed up the /crypto endpoints. Cached data about available cryptocurrencies and node status may be slightly outdated (up to 60 seconds). In multi-process deployments, each instance keeps its own cache, which may cause minor differences between responses. The cache reduces short-term node or network fluctuations but may briefly delay reflecting real-time status changes.
+
 <a name="invoice-creation"></a>
 #### 5.2.3. Invoice Creation
 
@@ -810,6 +815,68 @@ curl --location --request GET 'https://demo.shkeeper.io/api/v1/ETH/balance' \
 }
 ```
 
+<a name="get-all-balances"></a>
+##### 5.2.11.5. Get All Crypto Balances
+
+**Endpoint:** `/api/v1/crypto/balances`.    
+**Authorization:** ApiKey.       
+**HTTP request method:** GET.       
+**Query Parameters: (optional)**.       
+includes — Comma-separated list of crypto identifiers to return balances for (e.g., BTC,ETH,TRX). Case-insensitive. If omitted or empty, returns balances for all enabled cryptos. Unknown/disabled cryptos are ignored.
+
+**Curl Example:**
+```
+curl --location --request GET 'https://demo.shkeeper.io/api/v1/crypto/balances' \
+--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY' \
+--header 'Content-Type: application/json'
+```
+Example Request (subset of cryptos):
+```
+curl --location --request GET 'https://demo.shkeeper.io/api/v1/crypto/balances?includes=BTC,ETH'
+--header 'X-Shkeeper-API-Key: nApijGv8djih7ozY' \
+--header 'Content-Type: application/json'
+```
+Successful Response:
+```
+[
+  {
+    "name": "BTC",
+    "display_name": "Bitcoin",
+    "amount_crypto": "0.12345678",
+    "rate": "70616.07",
+    "fiat": "USD",
+    "amount_fiat": "8700.12",
+    "server_status": "online"
+  },
+  {
+    "name": "ETH",
+    "display_name": "Ethereum",
+    "amount_crypto": "1.2345",
+    "rate": "3015.50",
+    "fiat": "USD",
+    "amount_fiat": "3721.05",
+    "server_status": "online"
+  }
+]
+```
+Failure Response (invalid includes / no valid cryptos requested):
+```
+{
+    "status": "error",
+    "message": "No valid cryptos requested"
+}
+```
+
+**Notes & caveats**
+
+The response is always a plain JSON array, no extra envelope or metadata.
+The order of items is deterministic:
+If includes is provided → preserves order from request (valid entries only)
+If includes is absent → sorted alphabetically by name.
+Partial failures (e.g., RPC error for a coin) result in that coin being omitted; no new error fields are introduced.
+
+SHKeeper uses a short-lived in-memory TTL cache to speed up the /crypto/balances endpoints. Cached data about available cryptocurrencies and node status may be slightly outdated (up to 60 seconds). In multi-process deployments, each instance keeps its own cache, which may cause minor differences between responses. The cache reduces short-term node or network fluctuations but may briefly delay reflecting real-time status changes.
+
 <a name="receiving-callback"></a>
 ### 5.3 Receiving callback
 

shkeeper/api_v1.py

@@ -33,7 +33,8 @@
     WalletEncryptionRuntimeStatus,
 )
 from shkeeper.exceptions import NotRelatedToAnyInvoice
-
+from shkeeper.services.crypto_cache import get_available_cryptos
+from shkeeper.services.balance_service import get_balances
 
 bp = Blueprint("api_v1", __name__, url_prefix="/api/v1/")
 
@@ -46,39 +47,25 @@
 
 @bp.route("/crypto")
 def list_crypto():
-    filtered_list = []
-    crypto_list = []
-    disable_on_lags = app.config.get("DISABLE_CRYPTO_WHEN_LAGS")
-    cryptos =  Crypto.instances.values()
-    filtered_cryptos = []
-
-    for crypto in cryptos:
-        if crypto.wallet.enabled:
-            filtered_cryptos.append(crypto)
-
-    def get_crypto_status(crypto):
-        return crypto, crypto.getstatus()
-
-    with ThreadPoolExecutor() as executor:
-        results = list(executor.map(get_crypto_status, filtered_cryptos))
-
-    for crypto, status in results:
-        if status == "Offline":
-            continue
-        if disable_on_lags and status != "Synced":
-            continue
-        filtered_list.append(crypto.crypto)
-        crypto_list.append({
-            "name": crypto.crypto,
-            "display_name": crypto.display_name
-        })
-
+    data = get_available_cryptos()
     return {
         "status": "success",
-        "crypto": sorted(filtered_list),
-        "crypto_list": sorted(crypto_list, key=itemgetter("name")),
+        "crypto": data["filtered"],
+        "crypto_list": data["crypto_list"],
     }
 
+@bp.get("/crypto/balances")
+@api_key_required
+def get_all_balances():
+    includes = request.args.get("includes")
+    if includes:
+        includes = includes.split(",")
+    else:
+        includes = None
+    balances, error = get_balances(includes)
+    if error:
+        return {"status": "error", "message": error}, 400
+    return balances
 
 @bp.get("/<crypto_name>/generate-address")
 @login_required

shkeeper/services/balance_service.py

@@ -0,0 +1,50 @@
+from concurrent.futures import ThreadPoolExecutor
+from decimal import Decimal
+from shkeeper.services.crypto_cache import get_available_cryptos
+from shkeeper.modules.classes.crypto import Crypto
+from shkeeper.utils import format_decimal
+from shkeeper.models import ExchangeRate
+from flask import current_app
+
+def _build_balance(crypto_name: str, logger, app):
+    with app.app_context():
+        crypto = Crypto.instances.get(crypto_name)
+        if not crypto:
+            return None
+        fiat = "USD"
+        try:
+            rate = ExchangeRate.get(fiat, crypto_name).get_rate()
+            crypto_amount = Decimal(crypto.balance() or 0)
+            amount_fiat = crypto_amount * Decimal(rate)
+            server_status = crypto.getstatus()
+        except Exception as e:
+            logger.exception(f"_build_balance exception for {crypto_name}")
+            return None
+        return {
+            "name": crypto.crypto,
+            "display_name": crypto.display_name,
+            "amount_crypto": format_decimal(crypto_amount),
+            "rate": format_decimal(rate),
+            "fiat": fiat,
+            "amount_fiat": format_decimal(amount_fiat),
+            "server_status": server_status,
+        }
+
+def get_balances(includes: list[str] | None):
+    app = current_app._get_current_object()
+    logger = app.logger
+    data = get_available_cryptos()
+    available_coins = data["filtered"]
+    if includes:
+        includes = [c.strip().upper() for c in includes if c.strip()]
+        target = [c for c in includes if c in available_coins]
+        if not target:
+            return None, "No valid cryptos requested"
+    else:
+        target = sorted(available_coins)
+    with ThreadPoolExecutor() as executor:
+        results = list(
+            executor.map(lambda c: _build_balance(c, logger, app), target)
+        )
+    balances = [x for x in results if x]
+    return balances, None

shkeeper/services/cache_service.py

@@ -0,0 +1,18 @@
+import time
+from typing import Callable, Any
+
+class TTLCache:
+    def __init__(self):
+        self._cache = {}
+
+    def remember(self, key: str, ttl: int, callback: Callable[[], Any]):
+        entry = self._cache.get(key)
+        if entry and entry["expires"] > time.time():
+            return entry["value"]
+        value = callback()
+        self._cache[key] = {
+            "value": value,
+            "expires": time.time() + ttl
+        }
+        return value
+cache = TTLCache()

shkeeper/services/crypto_cache.py

@@ -0,0 +1,38 @@
+from concurrent.futures import ThreadPoolExecutor
+from operator import itemgetter
+from flask import current_app as app
+from shkeeper.modules.classes.crypto import Crypto
+from shkeeper.services.cache_service import cache
+
+CACHE_TTL = 60  # seconds
+
+def _fetch_available_cryptos():
+    disable_on_lags = app.config.get("DISABLE_CRYPTO_WHEN_LAGS")
+    cryptos = [c for c in Crypto.instances.values() if c.wallet.enabled]
+    def check_status(crypto):
+        return crypto, crypto.getstatus()
+
+    with ThreadPoolExecutor() as executor:
+        results = list(executor.map(check_status, cryptos))
+
+    filtered = []
+    crypto_list = []
+
+    for crypto, status in results:
+        if status == "Offline":
+            continue
+        if disable_on_lags and status != "Synced":
+            continue
+
+        filtered.append(crypto.crypto)
+        crypto_list.append({
+            "name": crypto.crypto,
+            "display_name": crypto.display_name
+        })
+    return {
+        "filtered": sorted(filtered),
+        "crypto_list": sorted(crypto_list, key=itemgetter("name")),
+    }
+
+def get_available_cryptos():
+    return cache.remember("available_cryptos", CACHE_TTL, _fetch_available_cryptos)