diff --git a/docs.json b/docs.json index 60a51cc5..e125e06c 100644 --- a/docs.json +++ b/docs.json @@ -343,6 +343,7 @@ }, "hedera/core-concepts/keys-and-signatures", "hedera/core-concepts/scheduled-transaction", + "hedera/core-concepts/fee-model", { "group": "Smart Contracts", "pages": [ @@ -638,6 +639,12 @@ "hedera/sdks-and-apis/sdks/client", "hedera/sdks-and-apis/sdks/set-up-your-local-network", "hedera/sdks-and-apis/sdks/address-book", + { + "group": "Fees", + "pages": [ + "hedera/sdks-and-apis/sdks/fees/fee-estimation" + ] + }, { "group": "Keys", "pages": [ @@ -682,6 +689,7 @@ }, "hedera/sdks-and-apis/sdks/queries", "hedera/sdks-and-apis/sdks/general-errors", + { "group": "Accounts and HBAR", "pages": [ diff --git a/hedera/core-concepts/fee-model.mdx b/hedera/core-concepts/fee-model.mdx new file mode 100644 index 00000000..1f190378 --- /dev/null +++ b/hedera/core-concepts/fee-model.mdx @@ -0,0 +1,371 @@ +--- +title: "Fee Model" +description: "Understand the simplified base-fee-plus-extras model for Hedera transaction and query fees introduced by HIP-1261." +--- + +## Overview + +Hedera uses a simplified fee model where every transaction cost is calculated as a **base fee plus extras**. Introduced in [HIP-1261](https://hips.hedera.com/hip/hip-1261), this model replaces the previous resource-weighted fee schedule with transparent, predictable pricing. + +All fees are defined in **USD as tinycents** and converted to HBAR at the current network exchange rate before being charged. The fee schedule is stored as a JSON document in system file `0.0.113` on the network. + + +**What is a tinycent?** One cent USD = 10⁸ tinycents. One dollar USD = 10¹⁰ tinycents. Tinycents provide high precision for fee calculations without floating-point math. + + + + +| Term | Definition | +| --- | --- | +| **Base Fee** | The fixed minimum fee in tinycents for a transaction or query before any extras are applied. | +| **Extras** | Additional cost factors on top of the base fee, such as signatures, bytes, keys, or gas. Each has a per-unit fee and an optional included count. | +| **Included Count** | Units of an extra included for free in the base fee before additional charges apply. | +| **Tinycent** | The smallest fee unit. 10⁸ tinycents = 1 cent USD. 10¹⁰ tinycents = 1 USD. | +| **Node Fee** | Fee paid to the submitting node. Same calculation for all transaction types. | +| **Network Fee** | A multiplier of the node fee covering consensus and storage. | +| **Service Fee** | Covers execution costs. Varies by transaction type. | + + + +## Fee Components + +Every transaction fee is split into three components: + +| Component | What It Covers | How It's Calculated | +|-----------|---------------|---------------------| +| **Node** | Compensates the submitting node for pre-checking and forwarding the transaction | `baseFee` + extras (processing bytes, signatures). Identical formula for **all** transaction types. | +| **Network** | Covers gossip, consensus, signature verification, and blockchain storage | A configurable multiplier of the node fee (default: 9×). | +| **Service** | Covers execution costs, state changes, and blockstream output | `baseFee` + transaction-specific extras (keys, token types, gas, etc.). Varies by transaction type. | + +```text +totalFee = nodeFee + networkFee + serviceFee +``` + +The node and network fees are uniform across all transaction types — only the service fee varies per transaction. + +## Extras + +Extras are additional cost factors applied on top of a base fee. Each extra has a **name**, a **per-unit fee** (in tinycents), and an optional **included count** — the number of units included for free before additional charges apply. + +The following extras are defined in the fee schedule: + +| Extra | Counted By | +|-------|-----------| +| `Signatures` | Number of signature verifications on the transaction | +| `Keys` | Number of keys defined (nested key structures count all keys) | +| `Accounts` | Number of accounts loaded during handling | +| `TokenTypes` | Number of token types referenced by the transaction | +| `Gas` | Gas cost (includes execution of hook programs) | +| `Allowances` | Number of allowances | +| `Airdrops` | Number of airdrops executed | +| `HookUpdates` | Number of hook create/delete operations | +| `HookSlotUpdate` | Number of hook slot modifications | +| `HookExecution` | Number of hook programs invoked during execution | +| `TokenTransferBase` | Base cost for token transfers | +| `TokenTransferBaseCustomFees` | Base cost for token transfers with custom fees | +| `TokenCreateWithCustomFee` | Token creation with a custom fee schedule defined | +| `TokenMintNft` | Number of NFT serials minted | +| `TokenMintNftBase` | Base cost for minting non-fungible tokens | +| `NftUpdate` | Number of NFT updates | +| `TokenAssociate` | Number of token associations | +| `ConsensusCreateTopicWithCustomFee` | Topic creation with a custom fee schedule defined | +| `ConsensusSubmitMessageWithCustomFee` | Message submission to a topic with custom fees | +| `ConsensusSubmitMessageWithCustomFeeBytes` | Byte count of a message submitted to a topic with custom fees | +| `ConsensusSubmitMessageWithoutCustomFeeBytes` | Byte count of a message submitted to a topic without custom fees | +| `ScheduleCreateContractCallBase` | Base cost for scheduling a contract call | +| `Records` | Number of transaction records produced | +| `StateBytes` | Bytes written to persistent state (e.g., file uploads) | +| `ProcessingBytes` | Bytes processed by the node and network (transaction size on the wire) | + + +The **included count** means you don't pay extra for typical usage. For example, the node fee includes a default allotment of processing bytes and one signature — a small, single-signature transaction pays zero byte and signature extras on the node component. + + +## Fee Calculation Example + +Consider a basic `CryptoCreate` transaction with a single key and 150 bytes: + + + + + +The node fee applies the same formula to all transactions: + +```text wrap +Node baseFee: 100,000 tinycents +ProcessingBytes extra: 150 bytes used, 1,024 included → 0 charged → 0 +Signatures extra: 1 signature, 1 included → 0 charged → 0 +─────────────────────────────────────────────── +Node fee total: 100,000 tinycents +``` + + + + + +The network fee is a multiplier of the node fee: + +```text +Network fee = 9 × 100,000 = 900,000 tinycents +``` + + + + + +The service fee is specific to `CryptoCreate`: + +```text wrap +Service baseFee: 499,000,000 tinycents +Keys extra: 1 key used, 1 included → 0 charged → 0 +─────────────────────────────────────────────── +Service fee total: 499,000,000 tinycents +``` + + + + + +```text wrap +Total = 100,000 + 900,000 + 499,000,000 = 500,000,000 tinycents ≈ $0.05 USD +``` + +This amount is converted to HBAR at the current exchange rate and charged to the payer. + + + + + +If the same transaction used **two** keys instead of one, the service fee would increase by the per-key extra fee (e.g., 10,000,000 tinycents), because the included count of 1 key is exceeded by 1. + +## Transaction Outcomes and Fees + +Not all transactions succeed. The fee charged depends on how far the transaction progresses: + +| Outcome | Description | Who Pays | Components Charged | +|---------|-------------|----------|-------------------| +| **Successful** | Transaction executed normally | Payer | Node + Network + Service | +| **Bad** | Passed due-diligence but failed during execution (e.g., out of gas, semantically wrong, inconsistent with state) | Payer | Node + Network + Service (full) | +| **Unhandled** | Well-formed but not executed (e.g., throttled, duplicate, unexecuted portion of an atomic batch) | Payer | Node + Network | +| **Invalid** | Failed due-diligence checks by the submitting node (e.g., payer can't afford the fee, incompatible fields) | Submitting node | Network only | +| **Unreadable** | Bytes cannot be parsed as a valid protobuf `Transaction` | Submitting node | Punitive flat fee | + + +Bad transactions are charged full freight (node + network + service) to protect the network from denial-of-service attacks. This applies even if the transaction fails due to a bug (`FAIL_INVALID`). + + +## Congestion Pricing + +When throughput for a specific throttle reaches a sustained critical level, **congestion pricing** may take effect. This dynamically increases fees to protect the network under high load. Congestion pricing is configurable per network — the Hedera Council sets the thresholds for the Hedera mainnet. + +## Fee Schedule Configuration + +The fee schedule is a JSON document stored in system file **`0.0.113`**. It defines: + +| Section | Purpose | +|---------|---------| +| `extras` | All available extra fee definitions (name + per-unit fee) | +| `node` | Node fee configuration (base fee + extras with included counts) | +| `network` | Network fee configuration (multiplier) | +| `services` | Per-service groupings of transaction and query fee definitions | +| `unreadable` | Punitive fee for unparsable transaction bytes | + + + +```json +{ + "version": 0, + "extras": [ + { "name": "Signatures", "fee": 100000 }, + { "name": "ProcessingBytes", "fee": 10000 }, + { "name": "Keys", "fee": 10000000 } + ], + "node": { + "baseFee": 100000, + "extras": [ + { "name": "ProcessingBytes", "includedCount": 1024 }, + { "name": "Signatures", "includedCount": 1 } + ] + }, + "network": { "multiplier": 9 }, + "services": [ + { + "name": "CryptoService", + "transactions": [ + { + "name": "CryptoCreate", + "baseFee": 499000000, + "extras": [ + { "name": "Keys", "includedCount": 1 } + ] + } + ], + "queries": [] + } + ], + "unreadable": { "fee": 100000000000 } +} +``` + + + + +The legacy fee schedule in system file `0.0.111` remains available in its existing format for backward compatibility, but it will not receive further updates. + + +## Fee Estimation + +You can estimate transaction fees before submitting them using the Mirror Node REST API: + +```bash +POST /api/v1/network/fees?mode=intrinsic +Content-Type: application/protobuf + + +``` + +The endpoint supports two modes: + +| Mode | Behavior | +|------|----------| +| `intrinsic` (default) | Estimates based on the transaction's inherent properties (size, signatures, keys) | +| `state` | Estimates using the mirror node's latest known state (e.g., checks if accounts exist) | + +See [Mirror Node REST API Network](/hedera/sdks-and-apis/rest-api/network) for the full endpoint specification and response format. + +## Queries + +Queries follow the same base-fee-plus-extras structure as transactions. Some queries are marked as `free` in the fee schedule (e.g., `CryptoGetAccountBalance`, `TransactionGetReceipt`). For non-free queries, the SDK creates a `CryptoTransfer` payment transaction to pay the node, network, and service fees. + +## Fee Schedule Schema (Protobuf) + +The fee schedule is defined as a set of protobuf messages. The wire format is JSON, stored in system file `0.0.113`. + +### FeeSchedule + +Top-level message defining the complete fee configuration. + +| Field | Type | Description | +|-------|------|-------------| +| `node` | NodeFeeSchedule | How to compute the node fee component. **Required.** | +| `network` | NetworkFeeSchedule | How to compute the network fee component. **Required.** | +| `unreadable` | UnreadableTransactionFeeSchedule | Fee for unparsable transaction bytes. Optional. | +| `extras` | repeated ExtraFeeDefinition | All available extra fee definitions. No duplicate names. | +| `services` | repeated ServiceFeeSchedule | Fee configs per network service. No duplicate names. | + +### ExtraFeeDefinition + +Defines a single extra fee — an additional charge for a specific cost factor. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Unique name. Must match `[A-Za-z].*[A-Za-z0-9]*`. **Required.** | +| `fee` | uint64 | Fee per unit in tinycents. Must be > 0. **Required.** | + +### NodeFeeSchedule + +Node fee configuration. Applied identically to **all** transaction types. + +| Field | Type | Description | +|-------|------|-------------| +| `base_fee` | uint64 | Base fee in tinycents. Defaults to 0. | +| `extras` | repeated ExtraFeeReference | Extras for computing the node fee. No duplicate references. | + +### NetworkFeeSchedule + +Network fee configuration. Calculated as a multiplier of the node fee. + +| Field | Type | Description | +|-------|------|-------------| +| `multiplier` | uint32 | Multiplied by the node fee. Must be ≥ 1. **Required.** | + +### ServiceFeeSchedule + +Groups transaction and query fee configs for a single gRPC service. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Service name (e.g., `CryptoService`). **Required.** | +| `schedule` | repeated ServiceFeeDefinition | Transaction/query fee configs. Must not be empty. | + +### ServiceFeeDefinition + +Fee definition for a single transaction or query. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Transaction/query name (e.g., `CryptoCreate`). **Required.** | +| `base_fee` | uint64 | Base fee in tinycents. Defaults to 0. | +| `extras` | repeated ExtraFeeReference | Extras for this transaction/query. No duplicate references. | +| `free` | bool | If `true`, `base_fee` and `extras` are ignored — the operation is free. | + +### ExtraFeeReference + +References an ExtraFeeDefinition with an optional included count. + +| Field | Type | Description | +|-------|------|-------------| +| `name` | string | Name of the referenced extra. Must match a defined extra. **Required.** | +| `included_count` | uint32 | Units included for free in the base fee. Defaults to 0. | + +### UnreadableTransactionFeeSchedule + +Punitive fee for nodes that submit unparsable bytes. + +| Field | Type | Description | +|-------|------|-------------| +| `fee` | uint64 | Punitive fee in tinycents. Optional (may be 0). | + +### Validation Rules + +Before a new fee schedule takes effect, the network validates it. If any rule fails, the schedule is rejected. + + + + +The JSON must parse and conform to the `FeeSchedule` protobuf message. All required fields must be present and types must match. No unrecognized fields. + + + +All `baseFee` and `fee` fields must be non-negative integers. For extras, `fee` must be strictly > 0. + + + +The `multiplier` in `network` must be a positive integer ≥ 1. + + + +All names must match `[A-Za-z].*[A-Za-z0-9]*`. Extra names, service names, and transaction/query names within each service must be unique. + + + +Every extra reference must point to a defined extra. No duplicate references within a single list. + + + +If `free` is `true`, `baseFee` and `extras` are ignored during calculation but must still comply with all validation rules if present. + + + + +## Related + + + + + The full Hiero Improvement Proposal specification. + + + + Fee tables for all transaction and query types on mainnet. + + + + Gas schedule and fee calculation for smart contracts. + + + + The fee collection account model that Simple Fees depends on. + + + \ No newline at end of file diff --git a/hedera/core-concepts/smart-contracts/gas-and-fees.mdx b/hedera/core-concepts/smart-contracts/gas-and-fees.mdx index 7a43924b..6a52634a 100644 --- a/hedera/core-concepts/smart-contracts/gas-and-fees.mdx +++ b/hedera/core-concepts/smart-contracts/gas-and-fees.mdx @@ -23,7 +23,9 @@ As noted in [HIP-410](https://hips.hedera.com/hip/hip-410), this maximizes compa ## Gas Schedule and Fee Calculation -Gas charges apply to `ContractCall`, `ContractCreate`, and `EthereumTransaction`. Other smart contract-related transactions (e.g., `ContractDelete`, `ContractGetInfo`) use standard Hedera network, node, and service fees in HBAR. +Gas charges apply to `ContractCall`, `ContractCreate`, and `EthereumTransaction`. Other smart contract-related transactions (e.g., `ContractDelete`, `ContractGetInfo`) use the standard [Fee Model](/hedera/core-concepts/fee-model), a base fee plus extras for node, network, and service components, paid in HBAR. + +For gas-consuming transactions (`ContractCall`, `ContractCreate`, `EthereumTransaction`), gas is an "extra" in the service fee component. The gas extra covers EVM execution costs. All other fee components (node fee, network fee, and the non-gas portion of the service fee) follow the base-fee-plus-extras model. Gas fees for EVM transactions consist of: diff --git a/hedera/core-concepts/tokens/hedera-token-service-hts-native-tokenization/custom-fee-schedule.mdx b/hedera/core-concepts/tokens/hedera-token-service-hts-native-tokenization/custom-fee-schedule.mdx index a8d32f0c..ebcdc3db 100644 --- a/hedera/core-concepts/tokens/hedera-token-service-hts-native-tokenization/custom-fee-schedule.mdx +++ b/hedera/core-concepts/tokens/hedera-token-service-hts-native-tokenization/custom-fee-schedule.mdx @@ -78,11 +78,11 @@ Royalty fees function as a convenience feature, but the network cannot enforce r 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. +* **Transaction fees** in HBAR serve a different purpose: they compensate the network for processing transactions. These fees follow a [base fee + extras model](/hedera/core-concepts/fee-model) defined in the network's fee schedule (system file `0.0.113`). While the fee structure varies by transaction type (each has its own base fee and applicable extras), the fee schedule is set by the network's governing authority, not by individual users. Transaction fees are paid exclusively in HBAR. ### **Key Differences** -The table below summarizes the key differences between custom fees and transaction fees. +The key differences are that custom fees offer flexibility and can be paid in various tokens to any account, while transaction fees follow a network-defined schedule and go to the network and node operators, paid only in HBAR. The table below summarizes the key differences between custom fees and transaction fees.
FeatureCustom FeesTransaction Fees
PurposeEnforce token-specific fee structures (e.g., royalties, taxes)Compensate network nodes for transaction processing
Who Collects?Designated fee collector(s)Hedera network nodes
CurrencyHBAR or HTS fungible tokensHBAR only
ConfigurabilityFully configurable by token issuerFixed by the network
diff --git a/hedera/core-concepts/transactions-and-queries.mdx b/hedera/core-concepts/transactions-and-queries.mdx index 3141dbab..95e85670 100644 --- a/hedera/core-concepts/transactions-and-queries.mdx +++ b/hedera/core-concepts/transactions-and-queries.mdx @@ -220,6 +220,10 @@ The transaction fee for the child transaction is included in the record of the p **Queries** are processed only by the single node to which they are sent. Clients send queries to retrieve some aspect of the current consensus state, like an account balance. Certain queries are free, but generally, they are subject to fees. The full list of queries can be found [here](/hedera/sdks-and-apis/sdks/queries). + +Under the [Fee Model](/hedera/core-concepts/fee-model), queries can have node, network, and service fee components. However, many common queries (e.g., `TransactionGetReceipt`, `CryptoGetAccountBalance`) are marked as **free** in the fee schedule. For non-free queries, the SDK creates a payment transaction to cover the fees. + + A query includes a header that includes a normal HBAR transfer transaction that will serve as how the client pays the node the appropriate fee. There is no way to give partial payment to a node for processing the query, meaning if a user overpaid for the query, the user will not receive a refund. The node processing the query will submit that payment transaction to the network for processing into a consensus statement to receive its fee. A client can determine the appropriate fee for a query by asking a node for the cost, not the actual data. Such a `COST_ANSWER` query is free to the client. diff --git a/hedera/faqs/network-governance.mdx b/hedera/faqs/network-governance.mdx index 885861bc..5a38e51e 100644 --- a/hedera/faqs/network-governance.mdx +++ b/hedera/faqs/network-governance.mdx @@ -174,9 +174,9 @@ title: "Network Governance" - Nodes calculate the fee for a transaction in USD but convert that value to HBAR using the current exchange rate before deducting that amount from the account paying for the transaction. Consequently, the fee in HBAR for the same transaction may vary from hour to hour, even as the fee in USD stays stable. If the client stipulates a max transaction fee for their transactions, a transaction may fail with an INSUFFICIENT_TX_FEE error if that stipulated max value is less than the value calculated by the nodes using the current exchange rate. Clients can protect themselves against this HBAR fee volatility by stipulating a sufficiently high max transaction fee (as they will only be charged the actual fee, not the max they stipulate) for transactions. + Fees are defined in USD as `tinycents` (`10⁸ tinycents` = 1 cent USD) in the fee schedule. Nodes convert the calculated USD fee to HBAR using the current exchange rate before charging the payer's account. This means the HBAR cost of the same transaction may vary from hour to hour as the exchange rate changes, even though the USD fee stays stable. - This applies to the payment transactions for queries as well. + If you set a `maxTransactionFee`, a transaction will fail with `INSUFFICIENT_TX_FEE` if the max is lower than the current calculated fee. To protect against volatility, set a sufficiently high max, you will only be charged the actual fee, not the maximum. @@ -272,11 +272,11 @@ title: "Network Governance" - Hedera council reviews pricing at every council meeting (once every three months), and approves all changes to the prices. The exchange rate that nodes use to determine the corresponding fees in hbars is updated frequently (currently every hour) . + The Hedera Council reviews pricing at every council meeting (approximately every three months) and approves all changes to the fee schedule. Fee updates are published to system file `0.0.113` on the network. The USD-to-HBAR exchange rate is updated frequently (currently every hour). - Hedera transaction and query fees are denominated in USD and paid in HBAR. The network regularly updates the USD-to-HBAR exchange rate based on current market rates, subject to a defined minimum exchange rate. + Hedera transaction and query fees are denominated in **USD** and paid in **HBAR**. Specifically, fees are defined in `tinycents` (`10⁸ tinycents` = 1 cent USD) in the fee schedule stored in system file `0.0.113`. The network regularly updates the USD-to-HBAR exchange rate based on current market rates, subject to a defined minimum exchange rate. This model is designed to keep fees predictable in USD terms, even though the amount paid in HBAR may vary over time. By using a minimum exchange rate, the network limits how much the HBAR-denominated fee can increase during periods of significant price volatility. diff --git a/hedera/networks/mainnet.mdx b/hedera/networks/mainnet.mdx index d6c5df62..4778fbda 100644 --- a/hedera/networks/mainnet.mdx +++ b/hedera/networks/mainnet.mdx @@ -7,15 +7,24 @@ sidebarTitle: Overview The Hedera mainnet (short for main network) is where applications are run in production, with transaction fees paid in [HBAR](https://www.hedera.com/hbar). Any application or retail user can submit transactions to the Hedera mainnet; they're automatically consensus-timestamped and fairly ordered. -Any Hedera account can query data associated with Hedera's services and stored on-chain. Every transaction requires payment as a **transaction fee** denominated in **tinybars** (100,000,000 tℏ = 1 ℏ). You can learn more about transaction fees and estimate your application costs [here](https://www.hedera.com/fees). +Any Hedera account can query data associated with Hedera's services and stored on-chain. Every transaction requires payment of a fee. Fees follow a [base fee + extras model](/hedera/core-concepts/fee-model) defined in the network's fee schedule (system file `0.0.113`). Fees are denominated in USD (as tinycents) and paid in HBAR at the current exchange rate (100,000,000 tℏ = 1 ℏ). You can learn more about transaction fees [here](/hedera/core-concepts/fee-model) and estimate your application costs using the [fee tables](/hedera/networks/mainnet/fees) or the `POST /api/v1/network/fees` [Mirror Node endpoint](/hedera/sdks-and-apis/rest-api/network). If you're looking to test your application (or just experiment), please visit [Testnet Access](/hedera/networks/testnet/testnet-access). The Hedera testnet enables developers to prototype and test applications in a simulated mainnet environment that uses test *HBAR* for paying transaction fees. -**Transaction Throttles**\ -Transactions on the Hedera Mainnet are currently throttled. You will receive a `"BUSY"` response if the number of transactions submitted to the network exceeds the threshold value. + #### **Transaction Throttles** + Transactions on the Hedera Mainnet are currently throttled. You will receive a `"BUSY"` response if the number of transactions submitted to the network exceeds the threshold value. ## Main Network Throttles -
Network Request TypesThrottle (tps)
Cryptocurrency Transactions

AccountCreateTransaction: 2 tps

TransferTransaction (inc. tokens): 10,000 tps
Other: 10,000 tps

Consensus Transactions

TopicCreateTransaction: 5 tps

Other: 10,000 tps

Token Transactions

TokenMintTransaction:

  • 125 TPS for fungible mint
  • 50 TPS for NFT mint

TokenAssociateTransaction: 100 tps
TransferTransaction (inc. tokens): 10,000 tps

Other: 3,000 tps

Schedule TransactionsScheduleSignTransaction: 100 tps
ScheduleCreateTransaction: 100 tps
File Transactions10 tps
Smart Contract TransactionsContractExecuteTransaction: 15 million gas per second
ContractCreateTransaction: 15 million gas per second
Queries (per node)

AccountBalanceQuery: 1000 tps

ContractGetInfo: 700 tps
ContractGetBytecode: 700 tps
ContractCallLocal: 700 tps

FileGetInfo: 700 tps
FileGetContents: 700 tps

Other: 10,000 tps

Receiptsunlimited (no throttle)
+| Network Request Types | Throttle (TPS) | +| --- | --- | +| **Cryptocurrency Transactions** | `AccountCreateTransaction`: 2 tps
`TransferTransaction` (inc. tokens): 10,000 tps
`Other`: 10,000 tps | +| **Consensus Transactions** | `TopicCreateTransaction`: 5 tps
`Other`: 10,000 tps | +| **Token Transactions** | `TokenMintTransaction`: 125 tps (fungible mint), 50 tps (NFT mint)
`TokenAssociateTransaction`: 100 tps
`TransferTransaction` (inc. tokens): 10,000 tps
`Other`: 3,000 tps | +| **Schedule Transactions** | `ScheduleSignTransaction`: 100 tps
`ScheduleCreateTransaction`: 100 tps | +| **File Transactions** | 10 tps | +| **Smart Contract Transactions** | `ContractExecuteTransaction`: 15 million gas per second
`ContractCreateTransaction`: 15 million gas per second | +| **Queries (per node)** | `AccountBalanceQuery`: 1000 tps
`ContractGetInfo`: 700 tps
`ContractGetBytecode`: 700 tps
`ContractCallLocal`: 700 tps
`FileGetInfo`: 700 tps
`FileGetContents`: 700 tps
`Other`: 10,000 tps | +| **Receipts** | unlimited (no throttle) | \ No newline at end of file diff --git a/hedera/networks/mainnet/fees.mdx b/hedera/networks/mainnet/fees.mdx index 87e45d5e..736d9de1 100644 --- a/hedera/networks/mainnet/fees.mdx +++ b/hedera/networks/mainnet/fees.mdx @@ -6,7 +6,9 @@ sidebarTitle: Overview The Hedera testnet fees tables found below offer a low-end estimate of transaction and query fees for all network services. The tables below contain USD, HBAR, and Tinybar (tℏ) values per each API call. All operation fees on the Hedera testnet are paid in test HBAR, which is freely available and only useful for development purposes. -Fee estimates are based on assumptions about the details of a specific API call. For instance, the fee for an HBAR cryptocurrency transfer (CryptoTransfer) assumes a single signature on the transaction and the fee for storing a file assumes a 1,0000-byte sized file stored for 90 days. Transactions exceeding these base assumptions will be more expensive; we recommend increasing your maximum allowable fee to accommodate additional complexity. +Fee estimates are based on assumptions about the details of a specific API call. For instance, the fee for an HBAR cryptocurrency transfer (`CryptoTransfer`) assumes a single signature on the transaction and the fee for storing a file assumes a 1,000-byte sized file stored for 90 days. Transactions exceeding these base assumptions will be more expensive; we recommend increasing your maximum allowable fee to accommodate additional complexity. + +Hedera transaction and query fees follow a **base fee + extras** model defined by [**HIP-1261 (Simple Fees)**](https://hips.hedera.com/hip/hip-1261). The base fees in the tables below are the starting cost — extras add to that cost based on what the transaction does. See [**Fee Model**](/hedera/core-concepts/fee-model) for the full explanation, the complete extras list, and worked examples. ### Mainnet Fees @@ -36,9 +38,6 @@ All fees are subject to change. The fees below reflect a base price for the tran | CryptoAccountAutoRenew | $0.00022 | | CryptoDeleteAllowance | $0.05 | | CryptoApproveAllowance | $0.05 | -| CryptoAddLiveHash | $0.10 | -| CryptoDeleteLiveHash | $0.005 | -| CryptoGetLiveHash | $0.0001 | | CryptoUpdate | $0.00022 | | CryptoTransfer | $0.0001 | | CryptoTransfer (custom fees) | $0.002 | @@ -46,7 +45,6 @@ All fees are subject to change. The fees below reflect a base price for the tran | CryptoGetAccountRecords | $0.0001 | | CryptoGetAccountBalance | $0.00 | | CryptoGetInfo | $0.0001 | -| CryptoGetStakers | $0.0001 | ### Consensus Service @@ -82,7 +80,6 @@ All fees are subject to change. The fees below reflect a base price for the tran | TokenGrantKyc | $0.001 | | TokenMint (fungible) | $0.001 | | TokenMint (non-fungible) | $0.02 | -| TokenMint (bulk mint 10k NFTs) | $200.00 | | TokenPause | $0.001 | | TokenReject | $0.001 | | TokenRevokeKyc | $0.001 | @@ -125,7 +122,6 @@ All fees are subject to change. The fees below reflect a base price for the tran | ContractCallLocal | $0.001 | | ContractGetByteCode | $0.05 | | ContractGetInfo | $0.0001 | -| ContractGetRecords | $0.0001 | | ContractAutoRenew | $0.026 | | EthereumTransaction (successful transactions) | $0.00 | | EthereumTransaction (failed transactions) | $0.0001 | @@ -150,3 +146,41 @@ All fees are subject to change. The fees below reflect a base price for the tran | SystemUndelete | $0.00 | | TransactionGetReceipt | $0.00 | | TransactionGetRecord | $0.0001 | + +### Extras + +Under the [**Simple Fees model (HIP-1261)**](https://hips.hedera.com/hip/hip-1261), every transaction is calculated as a **base fee plus extras**. The base fees in the tables above are the starting cost — extras add to that cost based on what the transaction does (number of signatures, keys, NFT serials, gas used, etc.). Each extra has an included count that covers typical usage; you only pay for units above that count. See [**Fee Model**](/hedera/core-concepts/transactions-and-queries/fee-model) for the full explanation and worked examples. + + +This table reflects the extras currently defined in the live fee schedule (system file `0.0.113`). The published [HIP-1261](https://hips.hedera.com/hip/hip-1261) lists an earlier version of this set; consult the live schedule as the source of truth. + + +| Extra | USD | Counted By | +|-------|-----|------------| +| `Signatures` | $0.00001 | Number of signature verifications on the transaction | +| `Keys` | $0.01 | Number of keys defined (nested key structures count all keys) | +| `Accounts` | $0.0001 | Number of accounts loaded during handling | +| `TokenTypes` | $0.0001 | Number of token types referenced by the transaction | +| `Gas` | $0.0000000852 | Gas cost (includes execution of hook programs) | +| `Allowances` | $0.05 | Number of allowances | +| `Airdrops` | $0.05 | Number of airdrops executed | +| `HookUpdates` | $1.00 | Number of hook create/delete operations | +| `HookSlotUpdate` | $0.005 | Number of hook slot modifications | +| `HookExecution` | $0.005 | Number of hook programs invoked during execution | +| `TokenTransferBase` | $0.0009 | Base cost for token transfers | +| `TokenTransferBaseCustomFees` | $0.0019 | Base cost for token transfers with custom fees | +| `TokenCreateWithCustomFee` | $1.00 | Token creation with a custom fee schedule defined | +| `TokenMintNft` | $0.02 | Number of NFT serials minted | +| `TokenMintNftBase` | $0.019 | Base cost for minting non-fungible tokens | +| `NftUpdate` | $0.001 | Number of NFT updates | +| `TokenAssociate` | $0.05 | Number of token associations | +| `ConsensusCreateTopicWithCustomFee` | $1.99 | Topic creation with a custom fee schedule defined | +| `ConsensusSubmitMessageWithCustomFee` | $0.04983 | Message submission to a topic with custom fees | +| `ConsensusSubmitMessageWithCustomFeeBytes` | $0.0001 | Byte count of a message submitted to a topic with custom fees | +| `ConsensusSubmitMessageWithoutCustomFeeBytes` | $0.00000068 | Byte count of a message submitted to a topic without custom fees | +| `ScheduleCreateContractCallBase` | $0.09 | Base cost for scheduling a contract call | +| `Records` | $0.0001 | Number of transaction records produced | +| `StateBytes` | $0.0001 | Bytes written to persistent state (e.g., file uploads) | +| `ProcessingBytes` | $0.000001 | Bytes processed by the node and network (transaction size on the wire) | + +Prices come from the configured fee schedule stored in system file `0.0.113` and may change. Fees are charged in HBAR, converted from USD at the live exchange rate. \ No newline at end of file diff --git a/hedera/sdks-and-apis/rest-api/network.mdx b/hedera/sdks-and-apis/rest-api/network.mdx index eaa6907d..6f733929 100644 --- a/hedera/sdks-and-apis/rest-api/network.mdx +++ b/hedera/sdks-and-apis/rest-api/network.mdx @@ -1,15 +1,45 @@ --- title: "Network" sidebarTitle: "Overview" +description: "Mirror Node REST API endpoints for querying network supply, fees, exchange rates, nodes, and staking information." --- - ## Overview -The **Network Object** in the Hedera Mirror Node REST API allows developers to query **network-related information**, such as network supply, fees, exchange rates, and node details. These object are essential for monitoring network status, estimating transaction costs, and retrieving staking information. +The Network Object in the Hedera Mirror Node REST API allows developers to query network-related information, such as network supply, fees, exchange rates, and node details. These endpoints are essential for monitoring network status, estimating transaction costs, and retrieving staking information. ## Endpoints The following endpoints are available for the Network object: -
EndpointDescription
GET /api/v1/network/supplyRetrieves the current total supply of HBAR.
GET /api/v1/network/feesFetches the latest transaction fee schedules.
GET /api/v1/network/exchangerateRetrieves exchange rates to estimate transaction costs.
GET /api/v1/network/nodesLists the network address book nodes.
GET /api/v1/network/stakeFetches staking-related information.
+| Endpoint | Description | +| --- | --- | +| `GET /api/v1/network/supply` | Retrieves the current total supply of HBAR. | +| `GET /api/v1/network/fees` | Fetches the latest transaction fee schedules. | +| `POST /api/v1/network/fees` | Estimates fees for a specific transaction before submission. [HIP-1261](https://hips.hedera.com/hip/hip-1261) | +| `GET /api/v1/network/exchangerate` | Retrieves exchange rates to estimate transaction costs. | +| `GET /api/v1/network/nodes` | Lists the network address book nodes. | +| `GET /api/v1/network/stake` | Fetches staking-related information. | + +### Estimate Transaction Fees (POST) + +`POST /api/v1/network/fees` + +Introduced in [HIP-1261 (Simple Fees)](https://hips.hedera.com/hip/hip-1261), this endpoint estimates the node, network, and service fees for a transaction before it is submitted to the network. It accepts a serialized `Transaction` protobuf in the request body (`application/protobuf` or `application/x-protobuf` Content-Type) and returns a detailed fee breakdown in tinycents. + +Two estimation modes are available via the `mode` query parameter: + +| Mode | Behavior | +| --- | --- | +| `intrinsic` (default) | Estimates based on the transaction's inherent properties (size, signatures, keys). | +| `state` | Also considers the mirror node's latest known state (e.g., account existence, token associations). | + + + For `state` mode, if the required network state is unavailable (e.g., due to data pruning), the endpoint falls back to `intrinsic` mode and includes a note in the response explaining the fallback. + + + + This endpoint currently returns stubbed (dummy) data as of mirror node `v0.145.1`. The full fee estimation implementation using the upstream fee estimation library will ship in a future release. You can integrate against the stub now to be ready when the production implementation goes live. + + +For full request/response details, parameters, and the interactive API playground, see the [API reference page](/api-reference/network/estimate-network-fees). For an overview of the Simple Fees model, see [Fee Model](/hedera/core-concepts/fee-model). \ No newline at end of file diff --git a/hedera/sdks-and-apis/sdks/fees/fee-estimation.mdx b/hedera/sdks-and-apis/sdks/fees/fee-estimation.mdx new file mode 100644 index 00000000..406e4376 --- /dev/null +++ b/hedera/sdks-and-apis/sdks/fees/fee-estimation.mdx @@ -0,0 +1,248 @@ +--- +title: "Estimating Fees with the SDK" +description: "Use FeeEstimateQuery to estimate transaction fees before submission, gate spending, and simulate high-volume pricing." +sidebarTitle: "Estimate a fee" +--- + +`FeeEstimateQuery` lets you estimate the cost of a transaction before submitting it. Use it to gate spending against a budget, surface fee previews to users, or simulate execution under high-volume congestion. + +The query returns a structured breakdown of node, network, and service fees in tinycents (USD × 10⁻¹⁰). The same calculation runs on the consensus node at execution time, so the estimate reflects what you'll be charged — modulo the live HBAR exchange rate at consensus. + +## Basic Usage + +Freeze the transaction first, then pass it to `FeeEstimateQuery`. Either call the query directly or use the `estimateFee()` convenience method on the transaction. + + + +```java Java +// Freeze the transaction first — the body must be finalized before estimating +var transaction = new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setInitialBalance(new Hbar(1)) + .freezeWith(client); + +// Option 1: FeeEstimateQuery +FeeEstimateResponse response = new FeeEstimateQuery() + .setTransaction(transaction) + .setMode(FeeEstimateMode.INTRINSIC) // optional — INTRINSIC is the default + .execute(client); + +// or option 2: Convenience method +// FeeEstimateResponse response = transaction.estimateFee().execute(client); +``` + +```javascript JavaScript +const transaction = await new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setInitialBalance(new Hbar(1)) + .freezeWith(client); + +const response = await new FeeEstimateQuery() + .setTransaction(transaction) + .setMode(FeeEstimateMode.INTRINSIC) + .execute(client); + +// or: const response = await transaction.estimateFee().execute(client); +``` + +```go Go +tx, _ := hiero.NewAccountCreateTransaction(). + SetKeyWithoutAlias(newKey.PublicKey()). + SetInitialBalance(hiero.NewHbar(1)). + FreezeWith(client) + +response, err := hiero.NewFeeEstimateQuery(). + SetTransaction(tx). + SetMode(hiero.FeeEstimateModeIntrinsic). + Execute(client) + +// or: response, err := tx.EstimateFee().Execute(client) +``` + + + +## Estimation Modes + +| Mode | Behavior | +|------|----------| +| `INTRINSIC` (default) | Estimates based on the transaction's inherent properties (size, signatures, keys). Fast and stateless. | +| `STATE` | Estimates using the mirror node's latest known state (e.g., checks if accounts exist, includes state-dependent extras). Required for high-volume pricing simulation. | + +## Response Structure + +The response contains a structured breakdown of the fee components. + +```json +{ + "high_volume_multiplier": 1, + "network": { "multiplier": 3, "subtotal": }, + "node": { + "base": , + "extras": [ + { + "name": "Signatures", + "included": 1, + "count": 2, + "charged": 1, + "fee_per_unit": , + "subtotal": + } + ] + }, + "service": { "base": , "extras": [] }, + "total": +} +``` + +The components total according to: + +```text +node.subtotal = node.base + sum(node.extras[].subtotal) +network.subtotal = node.subtotal × network.multiplier +total = node.subtotal + network.subtotal + service.subtotal +``` + +## End-to-End: Estimate, Gate, Execute + +A common pattern: estimate the fee, check against a budget, then execute only if the estimate is acceptable. + + + +```java Java +var transaction = new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setInitialBalance(new Hbar(1)) + .setMaxTransactionFee(new Hbar(10)) // set before freezing + .freezeWith(client); + +FeeEstimateResponse estimate = transaction.estimateFee().execute(client); + +// Gate on budget — $1.50 = 15,000,000,000 tinycents +if (estimate.getTotal() > 15_000_000_000L) { + throw new RuntimeException("Fee estimate exceeds budget: " + estimate.getTotal()); +} + +var record = transaction + .execute(client) + .getRecord(client); +``` + +```javascript JavaScript +const transaction = await new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setInitialBalance(new Hbar(1)) + .setMaxTransactionFee(new Hbar(10)) // set before freezing + .freezeWith(client); + +const estimate = await transaction.estimateFee().execute(client); + +if (estimate.total.toBigInt() > 15_000_000_000n) { + throw new Error(`Fee estimate exceeds budget: ${estimate.total}`); +} + +const record = await (await transaction.execute(client)).getRecord(client); +``` + +```go Go +tx, _ := hiero.NewAccountCreateTransaction(). + SetKeyWithoutAlias(newKey.PublicKey()). + SetInitialBalance(hiero.NewHbar(1)). + SetMaxTransactionFee(hiero.NewHbar(10)). // set before freezing + FreezeWith(client) + +estimate, _ := tx.EstimateFee().Execute(client) + +if estimate.Total > 15_000_000_000 { + panic(fmt.Sprintf("fee estimate exceeds budget: %d", estimate.Total)) +} + +resp, _ := tx.Execute(client) +record, _ := resp.GetRecord(client) +``` + + +## High-Volume Pricing Simulation + +For entity-creation transactions opted into the high-volume lane via `setHighVolume(true)`, the network may apply a fee multiplier under congestion. To simulate this before submitting, use `setHighVolumeThrottle()` on `FeeEstimateQuery` with `STATE` mode. + + + +```java Java +FeeEstimateResponse hvResponse = new FeeEstimateQuery() + .setTransaction( + new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setHighVolume(true) + .freezeWith(client) + ) + .setMode(FeeEstimateMode.STATE) + .setHighVolumeThrottle(5000) // simulate 50% utilization + .execute(client); + +// high_volume_multiplier uses 1-based scale: 1 = 1×, 4 = 4× +System.out.printf("Multiplier at 50%% load: %dx%n", hvResponse.getHighVolumeMultiplier()); +``` + +```javascript JavaScript +const hvResponse = await new FeeEstimateQuery() + .setTransaction( + new AccountCreateTransaction() + .setKeyWithoutAlias(newKey) + .setHighVolume(true) + .freezeWith(client) + ) + .setMode(FeeEstimateMode.STATE) + .setHighVolumeThrottle(5000) + .execute(client); + +console.log(`Multiplier at 50% load: ${hvResponse.highVolumeMultiplier}x`); +``` + +```go Go +tx, _ := hiero.NewAccountCreateTransaction(). + SetKeyWithoutAlias(newKey.PublicKey()). + SetHighVolume(true). + FreezeWith(client) + +hvResponse, _ := hiero.NewFeeEstimateQuery(). + SetTransaction(tx). + SetMode(hiero.FeeEstimateModeState). + SetHighVolumeThrottle(5000). + Execute(client) + +fmt.Printf("Multiplier at 50%% load: %dx\n", hvResponse.HighVolumeMultiplier) +``` + + +## Developer Notes + +- **Freeze before estimating.** Call `freezeWith(client)` before `FeeEstimateQuery` — the transaction body must be finalized for the estimate to reflect your actual transaction. +- **Estimates are in tinycents; execution fees are in tinybars.** The response uses tinycents (USD × 10⁻¹⁰). The fee charged on execution is in tinybars (HBAR × 10⁻⁸), converted at the live exchange rate at consensus time. +- **Set `maxTransactionFee` with headroom.** Add 10–20% above the estimate — exchange rates shift between estimation and execution. +- **`high_volume_multiplier` scale differs from `TransactionRecord`.** The estimate response uses a 1-based scale (1 = 1×, 4 = 4×). `TransactionRecord.highVolumePricingMultiplier` after execution uses a 1000-based scale (1000 = 1×, 4000 = 4×). Both represent the same multiplier. + +## SDK Versions + +`FeeEstimateQuery` is available in: + +- **Java**: v2.71.0+ +- **Go**: v2.79.0+ +- **JavaScript** (`@hiero-ledger/sdk`): v2.83.0+ + +## Related + + + + The base-fee-plus-extras model that fee estimation calculates against. + + + The underlying REST endpoint backing `FeeEstimateQuery`. + + + The HIP defining the fee model. + + + The HIP defining the high-volume lane and congestion multiplier. + + + \ No newline at end of file diff --git a/hedera/sdks-and-apis/sdks/transactions.mdx b/hedera/sdks-and-apis/sdks/transactions.mdx index c2e28e6c..9954d388 100644 --- a/hedera/sdks-and-apis/sdks/transactions.mdx +++ b/hedera/sdks-and-apis/sdks/transactions.mdx @@ -4,10 +4,10 @@ sidebarTitle: "Overview" --- -Transactions are requests submitted by a client to a node in the Hedera network. Every transaction has a fee that will be paid for processing the transaction. The following table lists the transaction type requests for each service. +Transactions are requests submitted by a client to a node in the Hedera network. Every transaction has a fee calculated using the [Fee Model](/hedera/core-concepts/fee-model): a base fee plus extras for each of the node, network, and service components. Fees are denominated in USD (as tinycents) and paid in HBAR at the current exchange rate. You can estimate fees before submission using the `POST /api/v1/network/fees` [Mirror Node endpoint](/hedera/sdks-and-apis/rest-api/network) or the [Hedera Fee Estimator](https://www.hedera.com/fees). The following table lists the transaction type requests for each service. -Transactions have a 6,144-byte size limit, which includes all attached signatures. A single signature is ~80–100 bytes, depending on the key type and encoding. Privileged Hedera accounts, such as 0.0.2 and 0.0.50, set as the transaction fee payer are permitted to submit transactions up to 130 KB in size. +Transactions have a 6,144-byte size limit, which includes all attached signatures. A single signature is ~80–100 bytes, depending on the key type and encoding. Privileged Hedera accounts, such as `0.0.2` and `0.0.50`, set as the transaction fee payer are permitted to submit transactions up to 130 KB in size. diff --git a/openapi.yaml b/openapi.yaml index fa1c5e02..d9b304c7 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -29,9 +29,8 @@ paths: get: summary: Get account by alias, id, or evm address description: | - Return the account transactions and balance information given an account alias, an account id, or an evm address. - The information will be limited to at most 1000 token balances for the account as outlined in HIP-367. - When the timestamp parameter is supplied, we will return transactions and account state for the relevant timestamp query. + Return the account transactions and balance information given an account alias, an account id, or an evm address. The information will be limited to at most 1000 token balances for the account as outlined in HIP-367. + When the timestamp parameter is supplied, we will return transactions and account state for the relevant timestamp query. Balance information will be accurate to within 15 minutes of the provided timestamp query. Historical ethereum nonce information is currently not available and may not be the exact value at a provided timestamp. operationId: getAccount parameters: @@ -54,6 +53,54 @@ paths: $ref: "#/components/responses/NotFoundError" tags: - accounts + /api/v1/accounts/{idOrAliasOrEvmAddress}/hooks: + get: + summary: List hooks for an account + description: Returns a list of hooks associated with a given account ID, alias, or EVM address. + operationId: getHooks + parameters: + - $ref: "#/components/parameters/accountIdOrAliasOrEvmAddressPathParam" + - $ref: "#/components/parameters/hookIdQueryParam" + - $ref: "#/components/parameters/limitQueryParam" + - $ref: "#/components/parameters/orderQueryParamDesc" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/HooksResponse" + "400": + $ref: "#/components/responses/InvalidParameterError" + "404": + $ref: "#/components/responses/NotFoundError" + tags: + - accounts + /api/v1/accounts/{idOrAliasOrEvmAddress}/hooks/{hookId}/storage: + get: + summary: Get hook storage slots + description: Returns a list of hook storage slots associated with a given hook. + operationId: getHookStorage + parameters: + - $ref: "#/components/parameters/accountIdOrAliasOrEvmAddressPathParam" + - $ref: "#/components/parameters/hookIdPathParam" + - $ref: "#/components/parameters/keyQueryParam" + - $ref: "#/components/parameters/limitQueryParam" + - $ref: "#/components/parameters/orderQueryParam" + - $ref: "#/components/parameters/timestampQueryParam" + responses: + "200": + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/HooksStorageResponse" + "400": + $ref: "#/components/responses/InvalidParameterError" + "404": + $ref: "#/components/responses/NotFoundError" + tags: + - accounts /api/v1/accounts/{idOrAliasOrEvmAddress}/nfts: get: summary: Get nfts for an account info @@ -345,11 +392,12 @@ paths: get: summary: List account balances description: - Returns a list of account and token balances on the network. This information is limited to - at most 50 token balances per account as outlined in HIP-367. As such, it's not recommended for general use and - we instead recommend using either `/api/v1/accounts/{id}/tokens` or `/api/v1/tokens/{id}/balances` to obtain - the current token balance information and `/api/v1/accounts/{id}` to return the current account balance. - + Returns a list of account and token balances on the network. The latest balance information is returned when + there is no timestamp query parameter, otherwise, the information is retrieved from snapshots with 15-minute + granularity. This information is limited to at most 50 token balances per account as outlined in HIP-367. + As such, it's not recommended for general use and we instead recommend using either + `/api/v1/accounts/{id}/tokens` or `/api/v1/tokens/{id}/balances` to obtain the current token balance information + and `/api/v1/accounts/{id}` to return the current account balance. operationId: getBalances parameters: - $ref: "#/components/parameters/accountIdOrAliasOrEvmAddressQueryParam" @@ -866,6 +914,37 @@ paths: $ref: "#/components/responses/ServiceUnavailableError" tags: - network + post: + summary: Estimate network fees + description: Given a HAPI transaction, estimate the network fees in tinycents. + operationId: estimateFees + parameters: + - $ref: "#/components/parameters/estimateModeQueryParam" + requestBody: + content: + application/protobuf: + schema: + format: binary + type: string + application/x-protobuf: + schema: + format: binary + type: string + description: A protobuf encoded HAPI Transaction + required: true + responses: + 200: + description: OK + content: + application/json: + schema: + $ref: "#/components/schemas/FeeEstimateResponse" + 400: + $ref: "#/components/responses/InvalidParameterError" + 500: + $ref: "#/components/responses/ServiceUnavailableError" + tags: + - network /api/v1/network/nodes: get: summary: Get the network address book nodes @@ -902,7 +981,7 @@ paths: 400: $ref: "#/components/responses/InvalidParameterError" 404: - $ref: "#/components/responses/NotFoundError" + $ref: "#/components/responses/NetworkStakeNotFound" 500: $ref: "#/components/responses/ServiceUnavailableError" tags: @@ -1399,22 +1478,22 @@ tags: - name: tokens description: The tokens object represents the information associated with a token entity and returns a list of token information.The tokens list endpoint is cached and not updated as frequently as the token lookup by a specific ID. info: - title: Hedera Mirror Node REST API - version: 0.129.1 + title: Mirror Node REST API + version: 0.149.0 license: name: Apache-2.0 url: "https://www.apache.org/licenses/LICENSE-2.0.html" - description: "The Mirror Node REST API offers the ability to query cryptocurrency transactions and account information from a Hedera managed mirror node.\n\nBase url: [/api/v1](/api/v1)\n\nOpenAPI Spec: [/api/v1/docs/openapi.yml](/api/v1/docs/openapi.yml)" + description: "The REST API offers the ability to query transactions and entity information from a mirror node.\n\nBase url: [/api/v1](/api/v1)\n\nOpenAPI Spec: [/api/v1/docs/openapi.yml](/api/v1/docs/openapi.yml)" contact: - name: Hedera Mirror Node Team + name: Mirror Node Team email: mirrornode@hedera.com url: "https://github.com/hiero-ledger/hiero-mirror-node" externalDocs: - description: Hedera REST API Docs + description: REST API Docs url: "https://docs.hedera.com/guides/docs/mirror-node-api/cryptocurrency-api" servers: - description: The current REST API server - url: "https://mainnet.mirrornode.hedera.com" + url: "" - description: The production REST API servers url: "{scheme}://{network}.mirrornode.hedera.com" variables: @@ -1550,6 +1629,108 @@ components: $ref: "#/components/schemas/CryptoAllowances" links: $ref: "#/components/schemas/Links" + HooksResponse: + type: object + required: + - hooks + - links + properties: + hooks: + type: array + items: + $ref: "#/components/schemas/Hook" + links: + $ref: "#/components/schemas/Links" + Hook: + type: object + required: + - admin_key + - contract_id + - created_timestamp + - deleted + - extension_point + - hook_id + - owner_id + - timestamp_range + - type + properties: + admin_key: + $ref: "#/components/schemas/Key" + contract_id: + allOf: + - $ref: "#/components/schemas/EntityId" + description: The contract entity that contains the hook's executing bytecode + created_timestamp: + allOf: + - $ref: "#/components/schemas/TimestampNullable" + description: The consensus timestamp when the hook was created + deleted: + description: Whether the hook has been deleted + example: false + type: boolean + extension_point: + description: The extension point this hook implements + enum: [ACCOUNT_ALLOWANCE_HOOK] + example: ACCOUNT_ALLOWANCE_HOOK + type: string + hook_id: + description: The unique identifier for the hook within the owner's scope + example: 1 + format: int64 + type: integer + owner_id: + allOf: + - $ref: "#/components/schemas/EntityId" + description: The entity that owns the hook + timestamp_range: + $ref: "#/components/schemas/TimestampRangeNullable" + type: + description: The type of the hook implementation + enum: [EVM] + example: EVM + type: string + HookStorage: + type: object + required: + - key + - timestamp + - value + properties: + key: + example: "0x00000000000000000000000000000000000000000000000000000000000f9a17" + format: binary + nullable: false + type: string + value: + example: "0x00000000000000000000000000000000000000000000000000000000000f9a17" + format: binary + nullable: true + type: string + timestamp: + $ref: "#/components/schemas/Timestamp" + HooksStorageResponse: + type: object + required: + - hook_id + - links + - owner_id + - storage + properties: + hook_id: + description: The unique identifier of the hook within the owner's scope + example: 1 + format: int64 + type: integer + links: + $ref: "#/components/schemas/Links" + owner_id: + allOf: + - $ref: "#/components/schemas/EntityId" + - description: The entity that owns the hook + storage: + type: array + items: + $ref: "#/components/schemas/HookStorage" NetworkExchangeRateSetResponse: type: object properties: @@ -2002,6 +2183,12 @@ components: memo: example: contract memo type: string + nonce: + description: The nonce of the contract + nullable: true + format: int64 + type: integer + example: 1 obtainer_id: $ref: "#/components/schemas/EntityId" permanent_removal: @@ -2562,10 +2749,10 @@ components: pattern: "^((0x)?[0-9a-fA-F]+|(earliest|pending|latest))$" type: string data: - description: Hexadecimal method signature and encoded parameters. Up to 24656 bytes as at most 49152 hexidecimal digits plus optional leading 0x. + description: Hexadecimal method signature and encoded parameters. Up to 131072 bytes as at most 262146 hexadecimal digits including optional leading 0x. example: "0x47f1aae7" format: binary - maxLength: 49154 + maxLength: 262146 nullable: true pattern: "^(0x)?[0-9a-fA-F]+$" type: string @@ -2796,6 +2983,7 @@ components: - decline_reward - description - file_id + - grpc_proxy_endpoint - max_stake - memo - min_stake @@ -2823,6 +3011,8 @@ components: type: string file_id: $ref: "#/components/schemas/EntityId" + grpc_proxy_endpoint: + $ref: "#/components/schemas/ServiceEndpoint" max_stake: description: The maximum stake (rewarded or not rewarded) this node can have as consensus weight type: integer @@ -3203,6 +3393,125 @@ components: type: array items: $ref: "#/components/schemas/FixedCustomFee" + FeeEstimate: + description: The fee estimate for the network component. Includes the base fee and any extras associated with it. + properties: + base: + description: The base fee price, in tinycents. + example: 1000 + format: int64 + minimum: 0 + type: integer + extras: + description: The extra fees that apply for this fee component. + items: + $ref: "#/components/schemas/FeeExtra" + type: array + required: + - base + - extras + type: object + FeeEstimateMode: + description: Estimate solely based on the transaction's inherent properties or use network state. + default: INTRINSIC + enum: [INTRINSIC, STATE] + type: string + FeeEstimateNetwork: + description: The network fee component which covers the cost of gossip, consensus, signature verifications, fee payment, and storage. + properties: + multiplier: + description: Multiplied by the node fee to determine the total network fee. + example: 2 + format: int32 + minimum: 0 + type: integer + subtotal: + description: The subtotal in tinycents for the network fee component which is calculated by multiplying the node subtotal by the network multiplier. + example: 1200 + format: int64 + minimum: 0 + type: integer + required: + - multiplier + - subtotal + type: object + FeeEstimateResponse: + description: The response containing the estimated transaction fees. + properties: + network: + $ref: "#/components/schemas/FeeEstimateNetwork" + node: + allOf: + - $ref: "#/components/schemas/FeeEstimate" + - description: The node fee component which is to be paid to the node that submitted the transaction to the network. This fee exists to compensate the node for the work it performed to pre-check the transaction before submitting it, and incentivizes the node to accept new transactions from users. + notes: + description: An array of strings for any caveats. + example: ["Fallback to worst-case due to missing state"] + items: + type: string + type: array + service: + allOf: + - $ref: "#/components/schemas/FeeEstimate" + - description: The service fee component which covers execution costs, state saved in the Merkle tree, and additional costs to the blockchain storage. + total: + description: The sum of the network, node, and service subtotals in tinycents. + example: 1000 + format: int64 + minimum: 0 + type: integer + required: + - network + - node + - notes + - service + - total + type: object + FeeExtra: + description: The extra fee charged for the transaction. + properties: + charged: + description: The charged count of items as calculated by `max(0, count - included)`. + example: 1 + format: int32 + minimum: 0 + type: integer + count: + description: The actual count of items received. + example: 2 + format: int32 + minimum: 0 + type: integer + fee_per_unit: + description: The fee price per unit in tinycents. + example: 100 + format: int64 + minimum: 0 + type: integer + included: + description: The count of this "extra" that is included for free. + example: 1 + format: int32 + minimum: 0 + type: integer + name: + description: The unique name of this extra fee as defined in the fee schedule. + example: Signatures + type: string + subtotal: + description: The subtotal in tinycents for this extra fee. Calculated by multiplying the charged count by the fee_per_unit. + example: 100 + format: int64 + minimum: 0 + type: integer + required: + - charged + - count + - fee_per_unit + - included + - name + - subtotal + type: object FixedCustomFee: type: object properties: @@ -3522,6 +3831,10 @@ components: example: true nullable: true expiry_timestamp: + description: >- + The token's expiration time in nanoseconds since the Unix epoch. Note that this encoding + differs from other entity expiry timestamps (e.g., accounts) which use a seconds.nanoseconds + string format. This inconsistency is a known issue retained for backwards compatibility. example: 1234567890100000 format: int64 nullable: true @@ -3664,7 +3977,8 @@ components: - FILEDELETE - FILEUPDATE - FREEZE - - NODE + - HOOKSTORE + - LEDGERIDPUBLICATION - NODECREATE - NODEDELETE - NODESTAKEUPDATE @@ -3695,7 +4009,6 @@ components: - TOKENUPDATENFTS - TOKENWIPE - UNCHECKEDSUBMIT - - UNKNOWN - UTILPRNG Tokens: type: array @@ -3817,6 +4130,9 @@ components: $ref: "#/components/schemas/Timestamp" entity_id: $ref: "#/components/schemas/EntityId" + high_volume: + description: Whether the transaction used high-volume entity creation throttles and pricing per HIP-1313 + type: boolean max_custom_fees: type: array items: @@ -3908,11 +4224,14 @@ components: valid_start_timestamp: $ref: "#/components/schemas/Timestamp" example: - batch_key: "0xae8bebf1c9fa0f309356e48057f6047af7cde63037d0509d16ddc3b20e085158bfdf14d15345c1b18b199b72fed4dead" + batch_key: + _type: "ED25519" + key: "7934a257a6144fabc8fbdeeaa5810662adb89e7b6978ace46a74fdb2d12bd4b2" bytes: null charged_tx_fee: 7 consensus_timestamp: "1234567890.000000007" entity_id: "0.0.2281979" + high_volume: false max_custom_fees: - account_id: 0.0.8 amount: 1000 @@ -3994,6 +4313,7 @@ components: charged_tx_fee: 7 consensus_timestamp: "1234567890.000000007" entity_id: "0.0.2281979" + high_volume: false max_fee: 33 memo_base64: null name: CRYPTOTRANSFER @@ -4087,6 +4407,17 @@ components: _status: messages: - message: Not found + NetworkStakeNotFound: + description: No network stake data found + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + example: + _status: + messages: + - detail: No network stake data found + message: Not Found TopicNotFound: description: Topic Not Found content: @@ -4457,6 +4788,61 @@ components: default: 25 minimum: 1 maximum: 100 + hookIdQueryParam: + description: The ID of the hook + example: 1234 + in: query + name: hook.id + schema: + format: int64 + type: integer + minimum: 1 + maximum: 9223372036854775807 + required: false + hookIdPathParam: + description: The ID of the hook + example: 1234 + in: path + name: hookId + schema: + format: int64 + type: integer + minimum: 0 + maximum: 9223372036854775807 + required: true + keyQueryParam: + description: A string representing a pair of operator:address of a hook storage entry + examples: + zeroXPrefix: + summary: Example of key equals operator with 0x prefix + value: eq:0x00000000000000000000000000000000000000000000000000000000000f9a15 + noZeroPadding: + summary: Example of key equals operator without zero padding + value: eq:f9a15 + noOperator: + summary: Example of key equals with no operator + value: 00000000000000000000000000000000000000000000000000000000000f9a15 + eqOperator: + summary: Example of key equals operator + value: eq:00000000000000000000000000000000000000000000000000000000000f9a15 + gtOperator: + summary: Example of key gt operator + value: gt:00000000000000000000000000000000000000000000000000000000000f9a15 + gteOperator: + summary: Example of key gte operator + value: gte:00000000000000000000000000000000000000000000000000000000000f9a15 + ltOperator: + summary: Example of key lt operator + value: lt:00000000000000000000000000000000000000000000000000000000000f9a15 + lteOperator: + summary: Example of key lte operator + value: lte:00000000000000000000000000000000000000000000000000000000000f9a15 + in: query + name: key + schema: + example: eq:0x00000000000000000000000000000000000000000000000000000000000f9a10 + pattern: ^((eq|gte?|lte?)\:)?(0x)?[0-9A-Fa-f]{1,64}$ + type: string blockNumberQueryParam: name: block.number in: query @@ -4486,7 +4872,6 @@ components: schema: type: string pattern: ^((eq|gt|gte|lt|lte):)?\d{1,19}$ - minimum: 0 nodeIdQueryParam: name: node.id description: The ID of the node @@ -4808,7 +5193,7 @@ components: type: array items: type: string - pattern: ^((eq|gt|gte|lt|lte|ne):)?\d{1,10}(.\d{1,9})?$ + pattern: ^((eq|gt|gte|lt|lte|ne):)?\d{1,10}(\.\d{1,9})?$ timestampPathParam: name: timestamp in: path @@ -4817,7 +5202,7 @@ components: example: 1234567890.000000700 schema: type: string - pattern: ^\d{1,10}(.\d{1,9})?$ + pattern: ^\d{1,10}(\.\d{1,9})?$ stateTimestampQueryParam: description: The consensus timestamp of the contract state as a Unix timestamp in seconds.nanoseconds format with an optional comparison operator. See [unixtimestamp.com](https://www.unixtimestamp.com/) for a simple way to convert a date to the 'seconds' part of the Unix time. name: timestamp @@ -4867,7 +5252,7 @@ components: type: array items: type: string - pattern: ^((eq|gt|gte|lt|lte):)?\d{1,10}(.\d{1,9})?$ + pattern: ^((eq|gt|gte|lt|lte):)?\d{1,10}(\.\d{1,9})?$ tokenInfoTimestampQueryParam: description: The Unix timestamp in seconds.nanoseconds format. See [unixtimestamp.com](https://www.unixtimestamp.com/) for a simple way to convert a date to the 'seconds' part of the Unix time. name: timestamp @@ -4903,7 +5288,7 @@ components: value: lte:1234567890.000000700 schema: type: string - pattern: ^((eq|lt|lte):)?\d{1,10}(.\d{1,9})?$ + pattern: ^((eq|lt|lte):)?\d{1,10}(\.\d{1,9})?$ logTopic0QueryParam: name: topic0 in: query @@ -4971,6 +5356,13 @@ components: schema: type: boolean default: false + estimateModeQueryParam: + description: Estimate solely based on the transaction's inherent properties or use network state. + in: query + name: mode + example: INTRINSIC + schema: + $ref: "#/components/schemas/FeeEstimateMode" stack: name: stack description: If provided and set to false, stack information will not be included in the response @@ -4998,7 +5390,7 @@ components: transactionTypeQueryParam: name: transactiontype in: query - example: cryptotransfer + example: schema: $ref: "#/components/schemas/TransactionTypes" transactionIdPathParam: @@ -5072,7 +5464,6 @@ components: type: string maxLength: 100 minLength: 3 - tokenTypeQueryParam: name: type in: query @@ -5138,7 +5529,6 @@ components: schema: type: string pattern: ^(eq:)?(\d{1,19}|0x[a-fA-f0-9]+)$ - minimum: 0 slotQueryParam: name: slot in: query