Skip to main content
author: fiatjaf discussion: https://t.me/lnurl/9729

​
balanceCheck

This optional property is meant to allow a WALLET to check and display users’ balances on a SERVICE and also enable automatic delivery of funds from services to wallets. It works as follows:
  • If LN WALLET supports the balanceCheck scheme and sees a balanceCheck property from a withdrawal it performs, it may store that URL locally and call it later (for example, at its next startup, or after 24 hours).
  • The URL is to be treated exactly as the URL from an LNURL QR code after bech32-decoding step.
  • The goal of doing this is to see if there is some balance waiting to be withdrawn on that LN SERVICE. If there is any, the wallet may decide to withdraw it automatically.
  • After calling the balanceCheck URL LN WALLET must check the response for the presence of a new balanceCheck property and replace the previous with the new one — just erase the previous if there is not a new one.
  • To support this flow LN SERVICE only needs to implement a scheme for renewing the balanceCheck URL on every call it receives, returning the next URL every time. Then proceed to redeem withdraw requests when they come. LN SERVICE may also choose to offer a static LNURL-withdraw endpoint for each user, which can be less safe, but also simplifies implementation. In this case it would just indicate that same endpoint every time as the balanceCheck value.
The callback JSON response is modified as such: 
 {
   "tag": "withdrawRequest",
   "callback": string,
   "k1": string,
   "defaultDescription": string,
   "minWithdrawable": number,
   "maxWithdrawable": number,
+  "balanceCheck": string
 }
The value of balanceCheck here is an URL that can be called next time the wallet wants to perform a balance check, the call will be the same as performed in this step and the expected response is the same.

​
currentBalance

In any balanceCheck response, maxWithdrawable can be interpreted by WALLET as corresponding to the current user’s balance in the SERVICE. Unless the optional currentBalance field is present. In that case currentBalance should take priority. It is useful in case maxWithdrawable corresponds to less than the total balance due to any reason.