Allowances grant another account (spender) the right to transfer HBAR, fungible tokens, and non-fungible tokens from your account (owner). The ability to approve allowances is important because it enables applications like exchanges and wallets to perform transfers on behalf of their customers without requiring a customer to sign every single transaction in advance. You can approve allowances and perform approved transfers on Hedera as you build things like NFT exchanges, marketplaces for carbon assets, games, and more.
This tutorial shows you how to approve HBAR allowances using the Hedera JavaScript SDK.
Example: Alice Spends HBAR on Behalf of the Treasury
This example guides you through the following steps:
Creating additional Hedera accounts (Treasury, Alice, and Bob)
Treasury approving an allowance of 10 HBAR for Alice
Alice performing an approved transfer of 8 HBAR from Treasury to Bob
Treasury deleting the HBAR allowance for Alice
After completing all steps, your console should look something like this:
1. Create Accounts
There are four entities in this scenario: Operator, Treasury, Alice, and Bob. Your testnet credentials from the Hedera portal should be used for the operator variables, which are used to initialize the Hedera client that submits transactions to the network and gets confirmations.
Create new accounts for Treasury, Alice, and Bob. Start by specifying the initial balance of each new account (initBalance) to be 10 HBAR
Generate and record the private key for each account. Hedera supports ED25519
and ECDSA
keys
Use the function accountCreateFcn to create the new accounts
The function returns the status of the transaction (treasurySt) and the new account ID (treasuryId)
The inputs are the newly generated private key (treasuryKey), initBalance, and the client object
Output to the console a link to the mirror node explorer, HashScan, showing information about the new accounts
Using accountCreateFcn simplifies the account creation process and is reusable in case you need to create more accounts in the future. This function uses the AccountCreateTransaction() class of the SDK. We’ll use this modular approach throughout the article.
From the account creation in the previous step, Treasury has a balance of 10 HBAR.
That’s also the allowance amount that is approved for Alice to spend on behalf of Treasury (allowBal)
Use the function approvals.hbarAllowanceFcn
to approve the allowance
The function returns the receipt object of the transaction (allowanceApproveHbarRx)
The inputs are the owner account ID (treasuryId), the spender account ID (aliceId), allowBal, the private key of the owner for transaction authorization (treasuryKey), and client
The function approvals.hbarAllowanceFcn uses AccountAllowanceApproveTransaction()
from the SDK to grant the allowance for the spender from an owner’s account balance. The function queries.balanceCheckerFcn uses AccountBalanceQuery()
to check and display the HBAR balance (and optionally a token balance) for a given account ID or contract ID.
- Balance of account 0.0.48520992: 10 ℏ + undefined unit(s) of token
- Balance of account 0.0.48520993: 10 ℏ + undefined unit(s) of token
- Balance of account 0.0.48520995: 10 ℏ + undefined unit(s) of token
3. Perform Approved Transfer
In this step, Alice spends 8 HBAR (sendBal) from the allowance granted by Treasury. This means that Alice transfers 8 HBAR from Treasury to Bob.
Use the function transfers.hbarAllowanceFcn
to perform the approved transfer
The function returns the receipt object of the transaction (allowanceSendHbarRx)
The inputs are the owner account ID (treasuryId), the receiver account ID (bobId), sendBal, the spender account ID (aliceId), the private key of the spender for transaction authorization (aliceKey), and client
Output to the console:
The status of the approved transfer transaction
Account balances using queries.balanceCheckerFcn
console.log(`\nSTEP 3 ===================================\n`);
console.log(`- Alice performing allowance transfer from Treasury to Bob...\n`);
const sendBal = new Hbar(8); // Spender must generate the TX ID or be the client
const allowanceSendHbarRx = await transfers.hbarAllowanceFcn(treasuryId, bobId, sendBal, aliceId, aliceKey, client);
console.log(`- Allowance transfer status: ${allowanceSendHbarRx.status} \n`);
await queries.balanceCheckerFcn(treasuryId, [], client);
await queries.balanceCheckerFcn(aliceId, [], client);
await queries.balanceCheckerFcn(bobId, [], client);
The function transfers.hbarAllowanceFcn uses TransferTransaction()
from the SDK to enable a spender to use an allowance approved by an owner. Notice the following:
The method .addApprovedHbarTransfer()
is used to specify the amount that is coming out of the owner’s account
The spender must either generate the transaction ID or be the client submitting the transaction for the approved transfer to be successful
In this case, .setTransactionId(TransactionId.generate(spender))
generates the transaction ID with the spender and sets it for the transfer transaction
The transaction must be signed with the spender’s private key
export async function hbarAllowanceFcn(owner, receiver, sendBal, spender, spenderPvKey, client) {
const approvedSendTx = new TransferTransaction()
.addApprovedHbarTransfer(owner, sendBal.negated())
.addHbarTransfer(receiver, sendBal)
.setTransactionId(TransactionId.generate(spender)) // Spender must generate the TX ID or be the client
.freezeWith(client);
const approvedSendSign = await approvedSendTx.sign(spenderPvKey);
const approvedSendSubmit = await approvedSendSign.execute(client);
const approvedSendRx = await approvedSendSubmit.getReceipt(client);
return approvedSendRx;
}
Console Output:
STEP 3 ===================================
- Alice performing allowance transfer from Treasury to Bob...
- Allowance transfer status: SUCCESS
- Balance of account 0.0.48520992: 2 ℏ + undefined unit(s) of token
- Balance of account 0.0.48520993: 9.9971708 ℏ + undefined unit(s) of token
- Balance of account 0.0.48520995: 18 ℏ + undefined unit(s) of token
4. Delete HBAR Allowance
In this step, Treasury removes the HBAR allowance for Alice. HBAR allowances are removed by simply setting the allowance value to zero. The function approvals.hbarAllowanceFcn from before is used again, but now passing a value of 0 HBAR.
Now you know how to approve HBAR allowances on Hedera using the JavaScript SDK. You can try this example with the other officially supported SDKs for Java, Go, and Swift.
