Custom Fee Schedule
Last updated
Was this helpful?
Last updated
Was this helpful?
The Hedera Token Service (HTS) enables token issuers to set up to 10 automated, protocol-enforced custom fees per token. These fees apply automatically during token transfer transactions, facilitating revenue generation, royalty distribution, or incentive structures without the need for additional coding or smart contracts. This page will walk you through each token and how it operates and interacts with the network.
HTS supports three types of custom fees, allowing token issuers to design flexible fee structures that align with various use cases and business models:
Fixed Fee: Paid by the sender of the fungible or non-fungible tokens. A fixed fee transfers a set amount to a fee collector account each time a token is transferred, independent of the transfer size. This fee can be collected in HBAR or another Hedera token but not in NFTs.
Fractional Fee: Take a specific portion of the transferred fungible tokens, with optional minimum and maximum limits. The token receiver (fee collector account) pays these fees by default. However, if is set to true, the sender pays the fees and the receiver collects the full token transfer amount. If this field is set to false, the receiver pays for the token custom fees and gets the remaining token balance.
Royalty Fee: Paid by the receiver account that is exchanging the fungible value for the NFT. When the NFT sender does not receive any fungible value, the is charged to the NFT receiver.
📝 Example Breakdown:
Fixed Fee
Sender
HBAR or HTS FT
Fractional Fee
Sender (or recipient if configured)
HTS FT
Royalty Fee
NFT Buyer (if exchanged for FTs)
HBAR or HTS FT
Royalty Fallback
NFT Receiver (if no fungible value received)
Fixed fee in HBAR
In addition to the custom token fee payment, the sender account must pay for the token transfer transaction fee in HBAR. The "" section below covers the distinction between custom fees and transaction fees.
A fixed fee is a predetermined amount collected by a designated fee collector each time a token transfer occurs. This fee is independent of the transfer volume and is always paid by the sender. It can be collected in HBAR or an HTS fungible token (FT), but NFTs cannot be used as a fee payment type. Fixed fees can be applied to both fungible and non-fungible tokens, ensuring consistent fee collection per transaction.
A fractional fee deducts a percentage of the transferred amount and credits it to a designated fee collector account. This fee is only applicable to HTS fungible tokens (FTs) and must be ≤1 while staying within the fractional range of a 64-bit signed integer. By default, the recipient covers the fee, meaning the deducted amount is taken from what they receive. However, if net_of_transfers is set to true, the sender pays the fee, ensuring the recipient gets the full intended amount.
In essence, a fractional fee deducts a percentage of the transferred amount, with configurable payer responsibility (sender or recipient) and optional minimum and maximum limits to enforce boundaries on the deducted amount.
A 1% fractional fee applies to token transfers, with a minimum of 1 token and a maximum of 50 tokens.
A 1,000-token transfer incurs a 10-token fee (1% of 1000).
A 20-token transfer incurs the minimum fee of 1 token since 1% of 20 is less than 1.
Key Points:
Royalty fees apply only to non-fungible tokens (NFTs).
Fees are paid in HBAR or an HTS fungible token.
If the transfer includes no fungible value, a fallback fee is imposed.
An NFT with a 5% royalty fee on a 1,000 HBAR sale results in a 50 HBAR fee to the fee collector. If the NFT is transferred without a sale, a fixed fallback fee (e.g., 10 HBAR) is charged to the recipient.
Royalty fees function as a convenience feature, but the network cannot enforce royalties if users split the NFT exchange into separate transactions. To ensure proper application, the NFT sender and receiver must both sign a single CryptoTransfer transaction. There is an ongoing HIP discussion about expanding automatic royalty collection.
Understanding the difference between custom fees and standard transaction fees in HBAR is crucial for token issuers and developers working with Hedera.
Custom fees are designed to enforce complex fee structures, such as royalties and fractional ownership. These fees can be fixed, fractional, or royalty-based and are usually paid in the token being transferred, although other Hedera tokens or HBAR can also be used. You can configure up to 10 custom fees to be automatically disbursed to designated fee collector accounts.
On the other hand, transaction fees in HBAR serve a different purpose: they compensate network nodes for processing transactions. These fees are uniform across all transaction types and are paid exclusively in HBAR. Unlike custom fees, which can be configured by the user, transaction fees are fixed by the network.
The table below summarizes the key differences between custom fees and transaction fees.
Purpose
Enforce token-specific fee structures (e.g., royalties, taxes)
Compensate network nodes for transaction processing
Who Collects?
Designated fee collector(s)
Hedera network nodes
Currency
HBAR or HTS fungible tokens
HBAR only
Configurability
Fully configurable by token issuer
Fixed by the network
When it comes to setting custom fees, there are a few limits and constraints to keep in mind:
First, fees cannot be set to a negative value.
Each token can have up to 10 different custom fees.
Additionally, the treasury account for a given token is automatically exempt from paying these custom transaction fees.
The system also permits, at most, two "levels" of custom fees. That means a token being transferred might require fees in another token that also has its own fee schedule; however, this can only be nested two layers deep to prevent excessive complexity.
A royalty fee applies when an NFT is transferred in exchange for fungible tokens (e.g. when an NFT is sold). The receiver pays the royalty fee, which is deducted as a percentage of the fungible amount exchanged. If no fungible tokens are involved in the transfer (i.e., the NFT is gifted or moved without payment), a fixed is instead charged to the NFT recipient.
Fee collector accounts can be exempt from paying custom fees. To enable this, you need to set the exemption during the creation of the custom fees (). If not enabled, custom fees will only be exempt for an account if that account is set as a fee collector.