Fees

Endpoints for fee estimation.

Get approximate fees for the given transaction

post

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/fees/transaction

Get an estimated fee for the supplied transaction. This estimates the execution cost of the transaction, the current fee rate of the network, and returns estimates for fee amounts.

• transaction_payload is a hex-encoded serialization of the TransactionPayload for the transaction.

• estimated_len is an optional argument that provides the endpoint with an estimation of the final length (in bytes) of the transaction, including any post-conditions and signatures

If the node cannot provide an estimate for the transaction (e.g., if the node has never seen a contract-call for the given contract and function) or if estimation is not configured on this node, a 400 response is returned. The 400 response will be a JSON error containing a reason field which can be one of the following:

• DatabaseError - this Stacks node has had an internal database error while trying to estimate the costs of the supplied transaction.

• NoEstimateAvailable - this Stacks node has not seen this kind of contract-call before, and it cannot provide an estimate yet.

• CostEstimationDisabled - this Stacks node does not perform fee or cost estimation, and it cannot respond on this endpoint.

The 200 response contains the following data:

• estimated_cost - the estimated multi-dimensional cost of executing the Clarity VM on the provided transaction.

• estimated_cost_scalar - a unitless integer that the Stacks node uses to compare how much of the block limit is consumed by different transactions. This value incorporates the estimated length of the transaction and the estimated execution cost of the transaction. The range of this integer may vary between different Stacks nodes. In order to compute an estimate of total fee amount for the transaction, this value is multiplied by the same Stacks node"s estimated fee rate.

• cost_scalar_change_by_byte - a float value that indicates how much the estimated_cost_scalar value would increase for every additional byte in the final transaction.

• estimations - an array of estimated fee rates and total fees to pay in microSTX for the transaction. This array provides a range of estimates (default: 3) that may be used. Each element of the array contains the following fields:

  • fee_rate - the estimated value for the current fee rates in the network

  • fee - the estimated value for the total fee in microSTX that the given transaction should pay. These values are the result of computing: fee_rate x estimated_cost_scalar. If the estimated fees are less than the minimum relay fee (1 ustx x estimated_len), then that minimum relay fee will be returned here instead.

Note: If the final transaction"s byte size is larger than supplied to estimated_len, then applications should increase this fee amount by:

fee_rate x cost_scalar_change_by_byte x (final_size - estimated_size)

Body

application/json

POST request for estimated fee

transaction_payloadstringRequired

estimated_lenintegerOptional

Responses

200

Estimated fees for the transaction

application/json

POST response for estimated fee

estimated_cost_scalarintegerRequired

cost_scalar_change_by_bytenumberRequired

400

Fee estimation error

application/jsontext/plain

500

Internal Server Error

text/plain

post

/v2/fees/transaction

HTTPcURLJavaScriptPython

POST /v2/fees/transaction HTTP/1.1
Host: localhost:20443
Content-Type: application/json
Accept: */*
Content-Length: 140

{
  "estimated_len": 350,
  "transaction_payload": "021af942874ce525e87f21bbe8c121b12fac831d02f4086765742d696e666f0b7570646174652d696e666f00000000"
}

{
  "cost_scalar_change_by_byte": 0.00476837158203125,
  "estimated_cost": {
    "read_count": 19,
    "read_length": 4814,
    "runtime": 7175000,
    "write_count": 2,
    "write_length": 1020
  },
  "estimated_cost_scalar": 14,
  "estimations": [
    {
      "fee": 17,
      "fee_rate": 1.2410714285714286
    },
    {
      "fee": 125,
      "fee_rate": 8.958333333333332
    },
    {
      "fee": 140,
      "fee_rate": 10
    }
  ]
}

Get estimated fee

get

http://localhost:20443https://api.mainnet.hiro.sohttps://api.testnet.hiro.so

/v2/fees/transfer

Get an estimated fee rate for STX transfer transactions. This is a fee rate per byte, returned as a JSON integer (microSTX per byte).

Responses

200

Fee rate in microSTX per byte

application/json

integer · min: 1Optional

Fee rate in microSTX per byte

500

Internal Server Error

text/plain

get

/v2/fees/transfer

HTTPcURLJavaScriptPython

GET /v2/fees/transfer HTTP/1.1
Host: localhost:20443
Accept: */*

3