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.

ObjectID[]

required

Array of StakedSui object IDs

DelegatedStake[]

Array of delegated stake information

Show DelegatedStake fields

ObjectID

The StakedSui object ID

ObjectID

The staking pool ID

SuiAddress

Validator address

string

Principal staked amount

string

Epoch when stake was requested

string

Epoch when stake became active

string

Estimated reward amount

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.

SuiAddress

required

The owner’s Sui address

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.

BigInt<u64>

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

SuiCommittee

Committee information

Show response fields

string

The epoch number

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.

SuiSystemStateSummary

System state summary

Show response fields

string

Current epoch

string

Protocol version

string

System state version

string

Storage fund rebates

string

Non-refundable storage balance

string

Reference gas price

boolean

Whether safe mode is enabled

string

Safe mode storage rewards

string

Safe mode computation rewards

string

Safe mode storage rebates

string

Safe mode non-refundable fee

string

Epoch start timestamp

string

Epoch duration

string

Stake subsidy start epoch

string

Maximum validator count

string

Minimum stake to join validators

string

Low stake threshold

string

Very low stake threshold

string

Low stake grace period

string

Stake subsidy balance

string

Subsidy distribution counter

string

Current distribution amount

string

Subsidy period length

number

Subsidy decrease rate

string

Total staked SUI

ValidatorSummary[]

Active validators

ObjectID

Pending validators ID

string

Pending validators count

string[]

Validators pending removal

ObjectID

Staking pool mappings ID

string

Staking pool mappings size

ObjectID

Inactive pools ID

string

Inactive pools count

ObjectID

Validator candidates ID

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.

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.

ValidatorApys

Validator APY information

Show response fields

ValidatorApy[]

Array of validator APY data

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

​Methods

​getStakesByIds

​getStakes

​getCommitteeInfo

​getLatestSuiSystemState

​getReferenceGasPrice

​getValidatorsApy

​Usage Example with Rust SDK

Methods

getStakesByIds

getStakes

getCommitteeInfo

getLatestSuiSystemState

getReferenceGasPrice

getValidatorsApy

Usage Example with Rust SDK