​
What is a hold?

A hold is a temporary reservation of funds. It’s a way to ensure that funds are available when you need them. When you place a hold on a wallet, the funds are not available for spending, but they are still part of the wallet’s balance.

After being placed, a hold can be confirmed, or it can be canceled. When a hold is confirmed, the funds are no longer available for spending and are transferred to the recipient’s wallet. When a hold is canceled, the funds are released back to the wallet’s balance.

​
Placing a hold

While reading their brand new spellbook acquired earlier, Eryldor found the spell they were looking for. However, they need to buy an extra component to cast it. As it is a rare component, the only way they can get it is by participating in an auction.

Fortunately, at the auction-house, Eryldor found the component they need. They placed a bid of 2 COIN, and the auctioneer placed a hold on Eryldor’s wallet to ensure that the funds are available when the auction ends, if Eryldor wins.

You’ll act as the auctioneer and place a hold on Eryldor’s wallet.

With fctl, you place a hold using the wallets debit command, as if you were debiting the wallet. To create a hold rather than a debit, you use the --pending flag.

fctl wallets debit 2 COIN --pending --name eryldor

You should see the following output:

You are about to debit a wallets.
Do you want to continue [Y/n]: y
 SUCCESS  Wallet debited successfully with hold id '1f0dbe17-4be4-4db0-ab85-72404c059e73'!

​
Inspecting the hold

Let’s inspect Eryldor’s wallet in the Formance Console.

Open the Formance Console and navigate to the Wallets page. You should see a new hold on Eryldor’s wallet.

fctl ui

Originally, assuming you’ve followed the previous tutorials, Eryldor’s wallet had a balance of 5 COIN. After placing the hold, the wallet’s balance became 3 COIN, and the hold was created with an amount of 2 COIN.

Now, should Erlydor win the auction? You choose!

​
Confirming the hold

After the auction ends, Eryldor won the bid. The auctioneer will take the money from the hold placed earlier on Erlydores wallet.

To confirm the hold, you use the fctl wallet hold confirm command.

fctl wallets hold confirm <hold-id> --final

​
Canceling the hold

If Eryldor didn’t win the auction, the hold can be canceled to release the funds back to the wallet’s balance.

To cancel the hold, you use the fctl wallet hold void command.

fctl wallets hold void <hold-id>

​
Partially confirming the hold

In some cases, you may want to confirm only a portion of the hold.

For example, Eryldor is ready to pay up to 4 coins for the auction. The auctioneer placed a hold of 4 coins on Eryldor’s wallet. However, Eryldor won the auction with a bid of 3 coins. The auctioneer can confirm only 3 coins and cancel the remaining 1 coin.

First, you’ll put a hold of 4 coins on Eryldor’s wallet.

fctl wallets debit 4 COIN --pending --name eryldor

You should see the following output:

You are about to debit a wallets.
Do you want to continue [Y/n]: y
 SUCCESS  Wallet debited successfully with hold id '3af573f9-4c92-490b-9919-4848bf51fa33'!

If your wallet doesn’t have enough funds, you can top it up using:

fctl wallets credit <amount> COIN --name eryldor --source account=world

Now, you’ll confirm only 3 coins of the hold.

fctl wallet hold confirm "<hold-id>" --amount 3 --final

You should see the following output:

 SUCCESS  Hold '3af573f9-4c92-490b-9919-4848bf51fa33' confirmed!

​
Summary

In this section, you learned how to manage holds with Formance Wallets. You placed a hold on a wallet, confirmed the hold, canceled the hold, and partially confirmed the hold. You also learned how to inspect a wallet’s holds in the Formance Console.