GovernanceApi

The GovernanceApi provides methods for querying staking information, validator details, and network governance state. All methods are in the suix namespace.

Methods

getStakesByIds

Returns one or more DelegatedStake objects by their IDs. If a stake was withdrawn, its status will be Unstaked.

staked_sui_ids

ObjectID[]

required

Array of StakedSui object IDs

result

DelegatedStake[]

Array of delegated stake information

Show DelegatedStake fields

stakedSuiId

ObjectID

The StakedSui object ID

stakingPool

ObjectID

The staking pool ID

validatorAddress

SuiAddress

Validator address

principal

string

Principal staked amount

stakeRequestEpoch

string

Epoch when stake was requested

stakeActiveEpoch

string

Epoch when stake became active

estimatedReward

string

Estimated reward amount

status

string

Stake status: Active, Pending, or Unstaked

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getStakesByIds",
    "params": [
      ["0x..."]
    ]
  }'

getStakes

Returns all DelegatedStake objects for a given address.

owner

SuiAddress

required

The owner’s Sui address

result

DelegatedStake[]

Array of all delegated stakes for the address

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getStakes",
    "params": [
      "0x..."
    ]
  }'

getCommitteeInfo

Returns the committee information for the specified epoch.

epoch

BigInt<u64>

The epoch of interest. If None, defaults to the latest epoch

result

SuiCommittee

Committee information

Show response fields

epoch

string

The epoch number

validators

ValidatorCommitteeInfo[]

Array of validator committee information

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getCommitteeInfo",
    "params": [
      null
    ]
  }'

getLatestSuiSystemState

Returns the latest SUI system state object on-chain.

result

SuiSystemStateSummary

System state summary

Show response fields

epoch

string

Current epoch

protocolVersion

string

Protocol version

systemStateVersion

string

System state version

storageFundTotalObjectStorageRebates

string

Storage fund rebates

storageFundNonRefundableBalance

string

Non-refundable storage balance

referenceGasPrice

string

Reference gas price

safeMode

boolean

Whether safe mode is enabled

safeModeStorageRewards

string

Safe mode storage rewards

safeModeComputationRewards

string

Safe mode computation rewards

safeModeStorageRebates

string

Safe mode storage rebates

safeModeNonRefundableStorageFee

string

Safe mode non-refundable fee

epochStartTimestampMs

string

Epoch start timestamp

epochDurationMs

string

Epoch duration

stakeSubsidyStartEpoch

string

Stake subsidy start epoch

maxValidatorCount

string

Maximum validator count

minValidatorJoiningStake

string

Minimum stake to join validators

validatorLowStakeThreshold

string

Low stake threshold

validatorVeryLowStakeThreshold

string

Very low stake threshold

validatorLowStakeGracePeriod

string

Low stake grace period

stakeSubsidyBalance

string

Stake subsidy balance

stakeSubsidyDistributionCounter

string

Subsidy distribution counter

stakeSubsidyCurrentDistributionAmount

string

Current distribution amount

stakeSubsidyPeriodLength

string

Subsidy period length

stakeSubsidyDecreaseRate

number

Subsidy decrease rate

totalStake

string

Total staked SUI

activeValidators

ValidatorSummary[]

Active validators

pendingActiveValidatorsId

ObjectID

Pending validators ID

pendingActiveValidatorsSize

string

Pending validators count

pendingRemovals

string[]

Validators pending removal

stakingPoolMappingsId

ObjectID

Staking pool mappings ID

stakingPoolMappingsSize

string

Staking pool mappings size

inactivePoolsId

ObjectID

Inactive pools ID

inactivePoolsSize

string

Inactive pools count

validatorCandidatesId

ObjectID

Validator candidates ID

validatorCandidatesSize

string

Validator candidates count

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getLatestSuiSystemState",
    "params": []
  }'

getReferenceGasPrice

Returns the reference gas price for the network.

result

BigInt<u64>

Reference gas price in MIST

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getReferenceGasPrice",
    "params": []
  }'

getValidatorsApy

Returns the validator APY (Annual Percentage Yield) information.

result

ValidatorApys

Validator APY information

Show response fields

apys

ValidatorApy[]

Array of validator APY data

epoch

string

The epoch for this APY data

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getValidatorsApy",
    "params": []
  }'

Usage Example with Rust SDK

use sui_sdk::SuiClientBuilder;
use sui_types::base_types::SuiAddress;
use std::str::FromStr;

#[tokio::main]
async fn main() -> Result<(), anyhow::Error> {
    let sui = SuiClientBuilder::default()
        .build("https://fullnode.mainnet.sui.io:443")
        .await?;
    
    // Get system state
    let system_state = sui.governance_api()
        .get_latest_sui_system_state()
        .await?;
    
    println!("Current Epoch: {}", system_state.epoch);
    println!("Reference Gas Price: {}", system_state.reference_gas_price);
    println!("Total Stake: {}", system_state.total_stake);
    println!("Active Validators: {}", system_state.active_validators.len());
    
    // Get reference gas price
    let gas_price = sui.governance_api()
        .get_reference_gas_price()
        .await?;
    
    println!("Gas Price: {} MIST", gas_price);
    
    // Get stakes for an address
    let address = SuiAddress::from_str("0x...")?;
    let stakes = sui.governance_api()
        .get_stakes(address)
        .await?;
    
    for stake in stakes {
        println!("Stake: {} SUI with validator {}", 
            stake.principal, 
            stake.validator_address);
    }
    
    // Get validator APY
    let apys = sui.governance_api()
        .get_validators_apy()
        .await?;
    
    println!("Validator APYs for epoch {}", apys.epoch);
    
    Ok(())
}

JSON-RPC API

Rust SDK

GraphQL API

Framework

GovernanceApi

Methods

getStakesByIds

getStakes

getCommitteeInfo

getLatestSuiSystemState

getReferenceGasPrice

getValidatorsApy

Usage Example with Rust SDK

Build docs developers (and LLMs) love

JSON-RPC API

Rust SDK

GraphQL API

Framework

Documentation Index

​Methods

​getStakesByIds

​getStakes

​getCommitteeInfo

​getLatestSuiSystemState

​getReferenceGasPrice

​getValidatorsApy

​Usage Example with Rust SDK

Build docs developers (and LLMs) love

Methods

getStakesByIds

getStakes

getCommitteeInfo

getLatestSuiSystemState

getReferenceGasPrice

getValidatorsApy

Usage Example with Rust SDK