What is a gas budget, and how do I set it?

The gas budget is the most a transaction is allowed to spend on gas, in MIST (1 SUI = 10^9 MIST). You only pay what the transaction actually uses, and the rest goes back to you. But if execution needs more than the budget, the transaction aborts and you still pay for the computation. Both the Sui CLI and the TypeScript SDK set the budget for you by dry-running the transaction first. To set it yourself, use --gas-budget <MIST> on the CLI or tx.setGasBudget(n) in TypeScript.

What the budget has to cover

A Sui gas fee has a computation part and a storage part, minus rebates for storage you free up:

Text

net_gas_fee = computation_units × gas_price + storage_units × storage_price − storage_rebate

A transaction only succeeds if the budget is at least the larger of the computation fees and the total fees before the rebate is subtracted. So when a transaction deletes objects and earns a big rebate, the budget it needs can be much higher than what you end up paying. See what is Sui gas and the storage fund for how the fee parts work.

Minimum and maximum

These come from the protocol config and the gas model source:

Minimum: base_tx_cost_fixed × gas price. base_tx_cost_fixed is 1,000 on mainnet, and the reference gas price was 100 MIST as of epoch 1291 (25 October 2026), so the minimum budget at the reference price is 100,000 MIST (0.0001 SUI).
Maximum: max_tx_gas, which is 50,000,000,000,000 MIST (50,000 SUI) on mainnet at protocol version 139. Some older pages still say 50 SUI. That was the limit before protocol version 72.
Computation cap: at most 5,000,000 computation units per transaction, however large the budget.

The reference gas price can change every epoch. To check it, query GraphQL:

Terminal

curl -s https://graphql.mainnet.sui.io/graphql -H 'content-type: application/json' \
  -d '{"query":"{ epoch { epochId referenceGasPrice } }"}'

Setting it on the CLI

Since v1.24.1 you can leave out --gas-budget. The CLI then dry-runs the transaction and uses the estimate. To set it explicitly:

Terminal

sui client call --package $PKG --module counter --function increment \
  --args $COUNTER --gas-budget 10000000

sui client ptb --move-call $PKG::counter::increment @$COUNTER --gas-budget 10000000

--gas-price sets the price per computation unit and defaults to the reference gas price. Going above the reference price acts as a tip and gives you priority on congested shared objects. Going below it doesn't work, because validators won't sign the transaction.

Setting it in TypeScript

With @mysten/sui v2, tx.build() and signAndExecuteTransaction simulate the transaction and set the budget for you. The SDK uses computation cost plus 1,000 × gas price as overhead, plus storage cost, minus the storage rebate, and never goes below computation plus overhead. To control it yourself:

TypeScript

import { SuiGrpcClient } from '@mysten/sui/grpc'
import { Transaction } from '@mysten/sui/transactions'

const client = new SuiGrpcClient({
  network: 'testnet',
  baseUrl: 'https://fullnode.testnet.sui.io:443',
})

const tx = new Transaction()
tx.moveCall({ target: `${PACKAGE_ID}::counter::increment`, arguments: [tx.object(COUNTER_ID)] })
tx.setGasBudget(10_000_000) // 0.01 SUI cap

// Or estimate first and add headroom:
const sim = await client.simulateTransaction({ transaction: tx, include: { effects: true } })
const used = (sim.Transaction ?? sim.FailedTransaction).effects.gasUsed
console.log(used.computationCost, used.storageCost, used.storageRebate)

tx.setGasBudgetIfNotSet(n) only applies when nothing else has set a budget yet. tx.setGasPrice(n) overrides the price.

Gotchas

Budget versus balance. Your gas payment (coins or address balance) has to hold at least the full budget, not just the amount you'll end up paying. This is the usual cause of an "insufficient gas" error on a wallet that does have some SUI.
Out of gas still costs you. A transaction that runs out of gas aborts and you're charged for the computation used. See why did my transaction fail.
Sponsors should cap budgets. If you pay gas for users, limit the budget you'll sign. See sponsored transactions.
Estimates depend on state. A dry run against today's shared-object state can come in under what execution later needs. Add some headroom for contended objects.

Sources

Gas Fees, Sui documentation
sui-protocol-config/src/lib.rs (max_tx_gas, base_tx_cost_fixed), Sui source
gas_v2.rs (minimum transaction cost), Sui source
client_commands.rs (--gas-budget, --gas-price), Sui CLI source