Spendable balance
Permission Required
This feature requires the
Pay
permission.
Spending Limit
HandCash users have a global limit for how much they're willing to spend on apps on a daily basis.

Daily spend limit in the HandCash app.
If an attempt is made to spend more than their limit allows, the SDK will throw an error with this message:
{ "message": "Request exceeds users global connect spend limit." }
You can control this error with a piece of color similar to this:
try {
// omitted code...
const paymentResult = await account.wallet.pay(paymentParameters);
} catch(error) {
if (error.message === 'Request exceeds users global connect spend limit.') {
// Show spend limit reached dialog
}
}
See the errors section to find out more details
Get spendable balance
Developers can check how much money they can spend based on the limit set by the user and the amount already spent that day. This balance is called spendable balance.
This limit can be changed or reset only by users at any time.
You can fetch the user's spendable balance with the wallet.getSpendableBalance
function.
const {HandCashConnect} = require('@handcash/handcash-connect');
const handCashConnect = new HandCashConnect({
appId: '<app-id>',
appSecret: '<secret>',
});
const account = handCashConnect.getAccountFromAuthToken(token);
var spendableBalance = await account.wallet.getSpendableBalance();
console.log(spendableBalance);
// balance
{
spendableSatoshiBalance: 1260000,
spendableFiatBalance: 2.96,
currencyCode: 'CAD'
}
If you need to customize the local currency conversion, you can pass any currency code through the function:
var balance = await account.wallet.getSpendableBalance("USD");
console.log(balance);
// balance
{
spendableSatoshiBalance: 1260000,
spendableFiatBalance: 2.03,
currencyCode: 'USD'
}
Reset spendable balance
Occasionally, users might reach the daily spendable limit. In that situation, they would need to reset the daily limit from the HandCash app.
In order to reduce friction and make this process as convenient as possible, you can redirect them to HandCash to the exact screen where spend limits are managed:
const changeSpendLimitsUrl = handCashConnect.getChangeSpendLimitsUrl('https://my-app.com');
// Redirect user to "changeSpendLimitsUrl"
After changing the spending limit, users will be redirected to the URL specified (<https://my-app.com>
in the example above).
For example, you can show a dialog to inform the user when the daily limit has been reached and include the changeSpendLimitsUrl
in the primary action.
Keep the experience frictionless
Event thought the
redirectUrl
parameter is optional we encourage you to use it to keep the experience as frictionless as possible.If you follow the best practices you can achieve the following with 1-2 user clicks:
- The user is redirected from your app to HandCash
- The user resets the spending limit
- The user is redirect from HandCash back to your app

Spend limits prompt example with redirection action.
Why can't developers reset the limit from the SDK?
Daily spend limits is a feature to help users manage their balance by controlling how much they exepect to spend. This is why user should manually reset the limit to ensure they are aware. If developers were able to reset the limit then users wouldn't be aware when the limit is reached.
Updated 6 months ago