æternity Blockchain
AE & Gas

AE & Gas

AE is æternity's native coin. It pays for gas, it is the base currency of every bonding curve, and it is what a tip is denominated in. Most integration bugs in this ecosystem are unit bugs, so start here.

1 AE = 10^18 aettos

An aetto (plural aettos) is the smallest unit of AE:

1 AE      = 1 000 000 000 000 000 000 aettos = 10^18 aettos
1 aetto   = 0.000000000000000001 AE          = 10^-18 AE

Every amount crossing a chain boundary is in aettos. Node balances, contract call amount options, bonding-curve prices, event arguments: all aettos, all integers. AE is a presentation format.

Convert safely

Never use JavaScript floating point for this. 10^18 is past Number.MAX_SAFE_INTEGER (about 9.007 × 10^15), so a balance held as a Number silently loses precision. Use BigNumber or BigInt for every value you send or receive, and divide by 1e18 with a plain Number only for display.

import BigNumber from 'bignumber.js';
 
// aettos -> AE, for display
const balanceAE = new BigNumber(balanceAettos).dividedBy(1e18).toString();
 
// AE -> aettos, for sending. toFixed(0) first, then BigInt — never Number().
const amountAettos = BigInt(new BigNumber('0.25').shiftedBy(18).toFixed(0));

The SDK also ships a formatter:

import { formatAmount, AE_AMOUNT_FORMATS } from '@aeternity/aepp-sdk';
 
const priceAE = formatAmount(priceAettos.toString(), {
  denomination: AE_AMOUNT_FORMATS.AETTOS,
  targetDenomination: AE_AMOUNT_FORMATS.AE,
});

The SDK's toAe helper does the same job in one call.

Community tokens have their own decimals

Do not assume a token balance shares AE's exponent. AEX-9 tokens declare decimals in their meta_info; read it from the contract rather than hardcoding it. Superhero community tokens use 18, matching the bonding curve's supported_decimals. Scale token amounts by the token's own decimals, and only AE amounts by 18.

What a transaction costs

An æternity transaction has two separate charges:

ChargeApplies toHow it is set
feeEvery transactionSize- and type-dependent base fee; the SDK computes it
gasContract create and contract call transactionsgasLimit × gasPrice, charged on top of fee

Gas is charged on top of fee, up to the limit in the transaction. At a routine 5M gas limit that ceiling is around thirty times the fee, so the Superhero wallet shows a separate "Gas, at most" row, computed as gasLimit × gasPrice. When you approve a contract call, that row, not "Network fee", is your worst case.

Gas price

gasPrice is quoted in aettos per unit of gas. The SDK's default follows network demand, using the consensus minimum the node reports as the floor and 1e9 aettos (1 Gaetto) per gas unit as the fallback when the node does not report one. Under load, the same call costs more for the same gasUsed.

Worked example at the floor price, for a contract deploy:

gasLimit  76 000
gasPrice   1 000 000 000 aettos
max gas = 76 000 × 1e9 = 7.6e13 aettos = 0.000076 AE

A contract call typically carries a gasLimit of 5 000 000.

Superhero does not override the SDK's gas defaults: no contract call in the web app sets gasPrice or gasLimit, so a call that runs out of gas does so at the SDK's default limit.

Running out of gas

Gas is debited up front: the protocol subtracts gas × gas_price from the caller before execution, then refunds the unused portion and pays the used portion to the miner. A call that exhausts its gasLimit refunds nothing: the transaction is still mined, the state change is rolled back, and you pay the full limit. A generous gasLimit costs nothing when the call succeeds and everything when it does not.

Transactions per Superhero action

Each transaction pays gas at the network's current gas price:

ActionTransactions
Publish a post1
Publish a comment1
Cast a vote1
Revoke a vote1
Delegate / revoke delegation1
Create a governance poll2
Create a token1, plus any initial buy
Redeem an invitation1

The agent skill confirms a balance of at least 0.01 AE before doing anything on chain.

Invite links carry an explicit extra: 0.001 AE per invite is attached to cover the invitee's redemption gas, so an invite batch costs (amount_ae + 0.001) × count, plus gas. The AffiliationTreasury contract enforces that floor:

let minimum_redemption_fee_cover = 10 ^ 15 // minimal amount to cover redemption tx fees is ~2.01e14 (overpaid by few times to be sure)
require(redemption_fee_cover >= minimum_redemption_fee_cover, "MINIMUM_REDEMPTION_AND_FEE_NOT_MEET")

10^15 aettos is 0.001 AE, about five times the measured cost of the redemption call.

Getting AE

See Buying AE for mainnet and Testnet for free test AE.

Related

Accounts & KeysAENS