Overview

Most FIO Chain transactions require an on-chain fee. The fees are dynamic and set by the Block Producers on a continuous basis. The calling account is charged the fee amount current for the specific action at the time of the call.

In order to avoid the account being charged a fee without knowing what it is, most FIO Chain transactions require a max_fee parameter to be set. This parameter defines the maximum amount of FIO Tokens in SUFs, the caller is willing to pay. If the current fee amount is greater than what was supplied in max_fee, the transaction will fail with Fee exceeds supplied maximum error message.

Setting max_fee

Use bundled gas-free transaction

Some transactions can be made without paying a fee as long as the calling account owns a FIO Handle, passes it in the fio_address field and has enough bundled gas-free transactions. In that case the max_fee can be set to 0.

See On-chain Fees for actions which can use bundled gas-free transactions.

You can call /get_fio_addresses to find out how many bundled transaction a FIO Handle has left.

Set it very high

If you are fine being charged whatever the current fee is, just set max_fee very high, e.g. 100000000000000. You will only pay whatever is the current fee for the action you are calling. However, you risk that you may be charged a fee which is higher than you are comfortable with.

Run get_fee before submitting a transaction

The best practice is to run /get_fee before every transaction for the specific action which you will be executing. Then showing the fee amount to the user, to ensure they approve it and inserting it into max_fee to prevent the chain from charging more.

📘

/get_fee takes end_point parameter

The /get_fee call takes end_point name as a parameter, not the action name. See On-chain Fees for mapping.

Because the fees can change by the second, a yet better approach is to increase the amount you get from /get_fee by a buffer your users may be comfortable with, e.g. 10% to avoid the transaction failing because the fee went up by a fraction of a cent.

Finally, /get_fee also takes a FIO Handle and will check the available bundled gas-free transactions and return 0 if bundled transactions can be used for payment of the fee.

Example

User wants to register FIO Handle using regaddress action

1. Call /get_fee with:
   JSON

   {
     "fio_address": "",
     "end_point": "register_fio_address"
   }
   

   and receive:

   {
      "fee": 23254732338
   }
   

2. Compute the fee
   1. 23254732338/1000000000 = 23.25 FIO
3. Add buffer
   1. 23.25 * 1.1 = 25.58 FIO
4. Display maximum fee to user: 25.58 FIO before transaction.
5. Set max_fee to 25580000000
6. Display the fee_collected to the user as the actual fee paid after the transaction.

User wants to map blockchain public addresses to their FIO Handle using addaddress action

1. Call /get_fee with:
   JSON

   {
     "fio_address": "vitalik@safu",
     "end_point": "add_pub_address"
   }
   

   and receive:

   {
      "fee": 0
   }
   

2. There is no fee being charged, because the user has gas-free bundled transactions
3. Display to user that transaction is free
4. Set max_fee to 0