Skip to main content
The Governance API provides access to validator and staking-related data such as current committee info, delegated stakes, and APY. All methods are in the iotax namespace.

​
iotax_getStakes

Return all DelegatedStake objects for an address.
​
owner
IotaAddress
required
The owner’s IOTA address
​
stakes
Vec<DelegatedStake>
List of delegated stakes
cURL
curl -X POST https://api.iota.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "iotax_getStakes",
    "params": [
      "0x0479c602460ae68771dcb9bfcef607dccc678859fb72d7d8aa8d9ce58c9430747"
    ]
  }'

​
iotax_getStakesByIds

Return one or more DelegatedStake objects by their staked IOTA IDs.
​
staked_iota_ids
Vec<ObjectID>
required
List of staked IOTA object IDs
cURL
curl -X POST https://api.iota.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "iotax_getStakesByIds",
    "params": [
      [
        "0x1234567890abcdef",
        "0xfedcba0987654321"
      ]
    ]
  }'

​
iotax_getTimelockedStakes

Return all DelegatedTimelockedStake objects for an address.
​
owner
IotaAddress
required
The owner’s IOTA address
​
timelockedStakes
Vec<DelegatedTimelockedStake>
List of timelocked delegated stakes
cURL
curl -X POST https://api.iota.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "iotax_getTimelockedStakes",
    "params": [
      "0x0479c602460ae68771dcb9bfcef607dccc678859fb72d7d8aa8d9ce58c9430747"
    ]
  }'

​
iotax_getTimelockedStakesByIds

Return one or more DelegatedTimelockedStake objects by their timelocked staked IOTA IDs.
​
timelocked_staked_iota_ids
Vec<ObjectID>
required
List of timelocked staked IOTA object IDs
cURL
curl -X POST https://api.iota.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "iotax_getTimelockedStakesByIds",
    "params": [
      [
        "0x1234567890abcdef"
      ]
    ]
  }'

​
iotax_getCommitteeInfo

Return the committee information for the asked epoch.
​
epoch
BigInt<u64>
The epoch of interest. If None, defaults to the latest epoch
​
epoch
BigInt<u64>
The epoch number
​
validators
Vec<CommitteeValidator>
List of validators in the committee
cURL
curl -X POST https://api.iota.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "iotax_getCommitteeInfo",
    "params": [null]
  }'

​
iotax_getLatestIotaSystemStateV2

Return the latest IOTA system state object.
​
epoch
BigInt<u64>
The current epoch
​
protocolVersion
BigInt<u64>
The current protocol version
​
systemStateVersion
BigInt<u64>
The system state version
​
iotaTotalSupply
BigInt<u64>
Total supply of IOTA
​
iotaTreasuryCapId
ObjectID
The treasury cap object ID
​
storageRebate
BigInt<u64>
Current storage rebate
​
activeValidators
Vec<ValidatorSummary>
List of active validators
​
pendingActiveValidatorsId
ObjectID
ID for pending active validators table
​
pendingActiveValidatorsSize
BigInt<u64>
Number of pending active validators
​
stakingPoolMappingsId
ObjectID
ID for staking pool mappings table
​
stakingPoolMappingsSize
BigInt<u64>
Number of staking pool mappings
​
inactivePoolsId
ObjectID
ID for inactive pools table
​
inactivePoolsSize
BigInt<u64>
Number of inactive pools
​
validatorCandidatesId
ObjectID
ID for validator candidates table
​
validatorCandidatesSize
BigInt<u64>
Number of validator candidates
cURL
curl -X POST https://api.iota.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "iotax_getLatestIotaSystemStateV2",
    "params": []
  }'

​
iotax_getReferenceGasPrice

Return the reference gas price for the network.
​
result
BigInt<u64>
The reference gas price in NANOS
cURL
curl -X POST https://api.iota.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "iotax_getReferenceGasPrice",
    "params": []
  }'

​
iotax_getValidatorsApy

Return the validator APY (Annual Percentage Yield) information.
​
apys
Vec<ValidatorApy>
List of validator APY information
​
epoch
BigInt<u64>
The epoch for which APY is calculated
cURL
curl -X POST https://api.iota.io \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "iotax_getValidatorsApy",
    "params": []
  }'

​
Staking Workflow

Typical staking operations involve:
  1. Query Validators - Use iotax_getLatestIotaSystemStateV2 to get validator information
  2. Check APY - Use iotax_getValidatorsApy to compare validator rewards
  3. Stake IOTA - Build and execute a staking transaction
  4. Monitor Stakes - Use iotax_getStakes to track your delegated stakes
  5. Unstake - Build and execute an unstaking transaction when desired

​
Understanding Epochs

IOTA’s staking system operates on epochs:
  • Staking requests become active in the next epoch
  • Unstaking requests are processed at epoch boundaries
  • Rewards are calculated and distributed per epoch
  • Use iotax_getCommitteeInfo to query historical epoch data

Build docs developers (and LLMs) love

Get started for freeTalk to us