IOTA — iotax, iota (2/3)

API reference for IOTA. All methods ->

Part 2 of 3: 1 · 2 · 3

`iotax_getLatestIotaSystemStateV2`

Retrieves the latest IOTA system state (v2 format).

Retrieves the latest IOTA system state object on networks supporting protocol version >= 5. These are networks with node software release version >= 0.11.

Parameters

id (integer; required): a request ID (example: 1).
jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
method (string; required): a method used for the request.
params (array; required): none.

Returns

IotaSystemStateSummary< IotaSystemStateSummary >

activeValidators<[ IotaValidatorSummary ]> (required): the list of active validators in the current epoch.
atRiskValidators<[ IotaAddress, BigInt_for_uint64 ]> (required): map storing the number of epochs for which each validator has been below the low stake threshold.
epoch< BigInt_for_uint64 > (required): the current epoch ID, starting from 0.
epochDurationMs< BigInt_for_uint64 > (required): the duration of an epoch, in milliseconds.
epochStartTimestampMs< BigInt_for_uint64 > (required): Unix timestamp of the current epoch start.
inactivePoolsId< ObjectID > (required): ID of the object that maps from a staking pool ID to the inactive validator that has that pool as its staking pool.
inactivePoolsSize< BigInt_for_uint64 > (required): number of inactive staking pools.
iotaTotalSupply< BigInt_for_uint64 > (required): the current IOTA supply.
iotaTreasuryCapId< ObjectID > (required): the TreasuryCap<IOTA> object ID.
maxValidatorCount< BigInt_for_uint64 > (required): maximum number of active validators allowed in any epoch.
minValidatorCount< BigInt_for_uint64 > (required): minimum number of active validators allowed in any epoch.
minValidatorJoiningStake< BigInt_for_uint64 > (required): lower bound on the amount of stake required to become a validator.
pendingActiveValidatorsId< ObjectID > (required): ID of the object containing the list of new validators scheduled to join at the end of the epoch.
pendingActiveValidatorsSize< BigInt_for_uint64 > (required): number of new validators that will join at the end of the epoch.
pendingRemovals<[ BigInt_for_uint64 ]> (required): removal requests from validators, each element is an index pointing to activeValidators.
protocolVersion< BigInt_for_uint64 > (required): the current protocol version, starting from 1.
referenceGasPrice< BigInt_for_uint64 > (required): the reference gas price for the current epoch.
safeMode< Boolean > (required): indicates whether the system is running in downgraded safe mode due to a non-recoverable bug.
safeModeComputationRewards< BigInt_for_uint64 > (required): amount of computation rewards accumulated and not yet distributed during safe mode.
safeModeNonRefundableStorageFee< BigInt_for_uint64 > (required): amount of non-refundable storage fee accumulated during safe mode.
safeModeStorageCharges< BigInt_for_uint64 > (required): amount of storage charges accumulated and not yet distributed during safe mode.
safeModeStorageRebates< BigInt_for_uint64 > (required): amount of storage rebates accumulated and not yet burned during safe mode.
stakingPoolMappingsId< ObjectID > (required): ID of the object that maps from staking pool IDs to validator IOTA addresses.
stakingPoolMappingsSize< BigInt_for_uint64 > (required): number of staking pool mappings.
storageFundNonRefundableBalance< BigInt_for_uint64 > (required): non-refundable portion of the storage fund from rebates and leftover rewards.
storageFundTotalObjectStorageRebates< BigInt_for_uint64 > (required): total storage rebates for all on-chain objects stored in the storage fund.
systemStateVersion< BigInt_for_uint64 > (required): current version of the system state data structure type.
totalStake< BigInt_for_uint64 > (required): total stake from all active validators at the beginning of the epoch.
validatorCandidatesId< ObjectID > (required): ID of the object that stores preactive validators, mapping addresses to validator structs.
validatorCandidatesSize< BigInt_for_uint64 > (required): number of preactive validators.
validatorLowStakeGracePeriod< BigInt_for_uint64 > (required): number of epochs a validator can remain under the low stake threshold before being removed.
validatorLowStakeThreshold< BigInt_for_uint64 > (required): stake threshold below which validators are considered at risk and subject to removal after the grace period.
validatorReportRecords<[ IotaAddress, array ]> (required): map storing records of validators reporting each other.
validatorVeryLowStakeThreshold< BigInt_for_uint64 > (required): stake threshold below which validators are removed immediately at epoch change, with no grace period.

Request example

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "iotax_getLatestIotaSystemStateV2",
      "params": [],
      "id": 1
    }'

Response example

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "V2": {
            "epoch": "8",
            "protocolVersion": "7",
            "systemStateVersion": "2",
            "iotaTotalSupply": "4606135837711000000",
            "iotaTreasuryCapId": "0x03f980dbd802f9cae9a91a95c7d8918d53e960a529224a4fe949f16ed0a0bfe6",
            "storageFundTotalObjectStorageRebates": "142099092400",
            "storageFundNonRefundableBalance": "0",
            "referenceGasPrice": "1000",
            "safeMode": false,
            "safeModeStorageCharges": "0",
            "safeModeComputationCharges": "0",
            "safeModeComputationChargesBurned": "0",
            "safeModeStorageRebates": "0",
            "safeModeNonRefundableStorageFee": "0",
            "epochStartTimestampMs": "1747121947622",
            "epochDurationMs": "86400000",
            "minValidatorCount": "4",
            "maxValidatorCount": "150",
            "minValidatorJoiningStake": "2000000000000000",
            "validatorLowStakeThreshold": "1500000000000000",
            "validatorVeryLowStakeThreshold": "1000000000000000",
            "validatorLowStakeGracePeriod": "7",
            "totalStake": "1593618205314001166",
            "committeeMembers": ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", ...],
            "activeValidators": [
                {
                    "iotaAddress": "0xa69363ce32b9b1e5b9c7480232ca6799068daa7c22c3d8cc53632246c354b9ff",
                    "authorityPubkeyBytes": "hhTzcuJ0oEm+i3IQsoLp3tIODqhN69i6CcF2BiM6D/zzrNz7WTpYs1UFCLG1hp01AP314/jW/NoZ/esH6LvVwFDWu3LlL78rpUMnrob+jxzUpFszfGGRG1HVBthRsthH",
                    "networkPubkeyBytes": "cgaeXKN4Rg/Z6ffKCoRudauC5PHwrq13kpPG620EeR8=",
                    "protocolPubkeyBytes": "mlAC5S1B2MngnAUL/xdSCFFy4Pkg/nl1Tz59wSo1gDY=",
                    "proofOfPossessionBytes": "iWqAfqA1pnrZybpC9onttc1hyTy7kFUgdgu3Dod2TqxiCpaLfxXXIpATuwohTKdt",
                    "name": "Nansen",
                    "description": "Nansen is a leading on-chain analytics platform founded in 2020, and is now one of the most trusted names in crypto, serving traders and institutions. Disclaimer: delegating comes with slashing risks",
                    "imageUrl": "https://raw.githubusercontent.com/nansen-ai/staking-brand-assets/refs/heads/main/nansen_logo.png",
                    "projectUrl": "https://nansen.ai",
                    "netAddress": "/dns/iota-mainnet-validator.nansen.ai/tcp/8080/http",
                    "p2pAddress": "/dns/iota-mainnet-validator.nansen.ai/udp/8084",
                    "primaryAddress": "/dns/iota-mainnet-validator.nansen.ai/udp/8081",
                    "nextEpochAuthorityPubkeyBytes": null,
                    "nextEpochProofOfPossession": null,
                    "nextEpochNetworkPubkeyBytes": null,
                    "nextEpochProtocolPubkeyBytes": null,
                    "nextEpochNetAddress": null,
                    "nextEpochP2pAddress": null,
                    "nextEpochPrimaryAddress": null,
                    "votingPower": "709",
                    "operationCapId": "0x8c257442fdc3108e909a6e640d698183b5b659b4b91e49299b7bdec8eae77498",
                    "gasPrice": "1000",
                    "commissionRate": "1000",
                    "nextEpochStake": "107971890702362012",
                    "nextEpochGasPrice": "1000",
                    "nextEpochCommissionRate": "1000",
                    "stakingPoolId": "0x650976e1fcdc34715fcd3c3fc855fe53f8fb1975d71ef0a14c70def314f29cd0",
                    "stakingPoolActivationEpoch": "0",
                    "stakingPoolDeactivationEpoch": null,
                    "stakingPoolIotaBalance": "112369730917907092",
                    "rewardsPool": "446972976946139",
                    "poolTokenBalance": "111674731070595754",
                    "pendingStake": "714511436394942",
                    "pendingTotalIotaWithdraw": "5112351651940022",
                    "pendingPoolTokenWithdraw": "5080732072641612",
                    "exchangeRatesId": "0x6cac6ce099478b8502a3610cd5731fd506cdc68904f22140c2dc969baa5edccd",
                    "exchangeRatesSize": "9"
                }
            ],
            "pendingActiveValidatorsId": "0x0c5baa1518f8bde68dbff9187e1c6ee4902991ec458dadac56bdad36d1dd1a6f",
            "pendingActiveValidatorsSize": "0",
            "pendingRemovals": [],
            "stakingPoolMappingsId": "0x833c0d40c9ff97d5a58a5ddebee25beaee26a87d9d75935f918aea8ddcd77afe",
            "stakingPoolMappingsSize": "50",
            "inactivePoolsId": "0x1fdfc877c137ad53da70bf3173a59c2cae85268226918a071b00879d01ffee5e",
            "inactivePoolsSize": "3",
            "validatorCandidatesId": "0xbd088ad9621996a89da1f3ec01b360fad990b7e37499967b585248191210d7ad",
            "validatorCandidatesSize": "9",
            "atRiskValidators": [],
            "validatorReportRecords": []
        }
    }
}

`iotax_getReferenceGasPrice`

Retrieves the current reference gas price.

Parameters

id (integer; required): a request ID (example: 1).
jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
method (string; required): a method used for the request.
params (array; required): none.

Returns

BigInt<u64>< BigInt_for_uint64 >

Request example

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "iotax_getReferenceGasPrice",
      "params": [],
      "id": 1
    }'

Response example

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": "1000"
}

`iotax_getStakes`

Retrieves all stakes for a given address.

Parameters

id (integer; required): a request ID (example: 1).
jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
method (string; required): a method used for the request.
params (array; required):
- owner< IotaAddress > (required): the owner's IOTA address.

Returns

Vec<DelegatedStake><[ DelegatedStake ]>

Request example

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "iotax_getStakes",
      "params": ["0x303db99c56283dba10c014f90fce2691cba6e7ea661fd3331d95b6e76ada9a19"],
      "id": 1
    }'

Response example

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": [
        {
            "validatorAddress": "0x303db99c56283dba10c014f90fce2691cba6e7ea661fd3331d95b6e76ada9a19",
            "stakingPool": "0xf544f15d1c3fadcc60fa74717a0039607c64af9919ecad396716909768b3ba96",
            "stakes": [
                {
                    "stakedIotaId": "0x4bab00a6e80e6271351ea8d2ebf9658bed92a7fb9f9e9778c7279dee0d47cfbb",
                    "stakeRequestEpoch": "7",
                    "stakeActiveEpoch": "8",
                    "principal": "4279860002232",
                    "status": "Active",
                    "estimatedReward": "0"
                },
                {
                    "stakedIotaId": "0x58cd59f365ff591d10fe67f6b449098940562c7fa7cdaf6783b7bc99ed0c292b",
                    "stakeRequestEpoch": "1",
                    "stakeActiveEpoch": "2",
                    "principal": "7232810014145",
                    "status": "Active",
                    "estimatedReward": "25499919585"
                }
            ]
        }
    ]
}

`iotax_getStakesByIds`

Retrieves stakes by stake object IDs.

Parameters

id (integer; required): a request ID (example: 1).
jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
method (string; required): a method used for the request.
params (array; required):
- staked_iota_ids<[ ObjectID ]> (required): list of object IDs representing IOTA coin objects that have been staked by the validator.

Returns

Vec<DelegatedStake><[ DelegatedStake ]>

Request example

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "iotax_getStakesByIds",
      "params": [
        [
          "0x37e9ed4fe1b3781210575cdbb42a9599dc3b42ae12a6cd29f4f6b071522062d1",
          "0x474a511684bc5323b3688ff3a7df5c2e99140e91a4cc010976f8ba5ee8e489b3"
        ]
      ],
      "id": 1
    }'

Response example

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "validatorAddress": "0x8e2e13c2ecfda356f07d008885b7bb82befb4d602245c3bff98ad59863162dd8",
            "stakingPool": "0x49976354d0dc89ea6f0102c653f737d223ea4c0623e9d3e3ce73cb49f38bb0eb",
            "stakes": [
                {
                    "stakedIotaId": "0x37e9ed4fe1b3781210575cdbb42a9599dc3b42ae12a6cd29f4f6b071522062d1",
                    "stakeRequestEpoch": "5",
                    "stakeActiveEpoch": "6",
                    "principal": "7455240000000",
                    "status": "Active",
                    "estimatedReward": "7132473715"
                },
                {
                    "stakedIotaId": "0x474a511684bc5323b3688ff3a7df5c2e99140e91a4cc010976f8ba5ee8e489b3",
                    "stakeRequestEpoch": "7",
                    "stakeActiveEpoch": "8",
                    "principal": "6833970003564",
                    "status": "Active",
                    "estimatedReward": "0"
                }
            ]
        }
    ]
}

`iotax_getTimelockedStakes`

Retrieves all timelocked stakes for an address.

Parameters

id (integer; required): a request ID (example: 1).
jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
method (string; required): a method used for the request.
params (array; required):
- owner< IotaAddress > (required): the owner's IOTA address.

Returns

Vec<DelegatedTimelockedStake><[ DelegatedTimelockedStake ]>

Request example

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "iotax_getTimelockedStakes",
      "params": ["0x8e2e13c2ecfda356f07d008885b7bb82befb4d602245c3bff98ad59863162dd8"],
      "id": 1
    }'

Response example

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": []
}

`iotax_getTimelockedStakesByIds`

Retrieves timelocked stakes by object IDs.

Parameters

id (integer; required): a request ID (example: 1).
jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
method (string; required): a method used for the request.
params (array; required):
- timelocked_staked_iota_ids<[ ObjectID ]> (required): list of object IDs representing IOTA coin objects that have been staked with a time lock.

Returns

Vec<DelegatedTimelockedStake><[ DelegatedTimelockedStake ]>

Request example

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "iotax_getTimelockedStakesByIds",
      "params": [["0x<timelocked_stake_object_id_1>", "0x<timelocked_stake_object_id_2>"]],
      "id": 1
    }'

Response example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "id": "0xabc123...",
      "stake_amount": "1000000000",
      "start_epoch": 5200,
      "unlock_epoch": 5300,
      "owner": "0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961",
      "status": "Staked",
      "validator_address": "0x8a8b61fe5e6ff7d70c6cbff8b6c3cf2cb74ff67236beed1e92b9e651e0e19f3b"
    },
    {
      "id": "0xdef456...",
      "stake_amount": "2000000000",
      "start_epoch": 5180,
      "unlock_epoch": 5280,
      "owner": "0x94f1a597b4e8f709a396f7f6b1482bdcd65a673d111e49286c527fab7c2d0961",
      "status": "Unstaked",
      "validator_address": "0x7b72a2cd3efbbde451a9f3f179edf65ff07f3a0616b72c1a95e12a1bd176c918"
    }
  ]
}

`iotax_getValidatorsApy`

Retrieves the annual percentage yield (APY) for validators.

Parameters

id (integer; required): a request ID (example: 1).
jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
method (string; required): a method used for the request.
params (array; required): none.

Returns

ValidatorApys< ValidatorApys >

apys<[ ValidatorApy ]> (required)
epoch< BigInt_for_uint64 > (required)

Request example

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "iotax_getValidatorsApy",
      "params": [],
      "id": 1
    }'

Response example

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "apys": [
            {
                "address": "0xa69363ce32b9b1e5b9c7480232ca6799068daa7c22c3d8cc53632246c354b9ff",
                "apy": 0.23075268854918127
            },
            {
                "address": "0x864c651958094732a1227134cf7cab7587f05a399398804552553fbc01dba4e7",
                "apy": 0.232642723786573
            }
        ],
        "epoch": "8"
    }
}

`iota_getMoveFunctionArgTypes`

Retrieves argument types for a Move function.

Parameters

id (integer; required): a request ID (example: 1).
jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
method (string; required): a method used for the request.
params (array; required):
- package< ObjectID > (required): the object ID of the Move package that contains the target module.
- module< string > (required): the name of the Move module where the function is defined.
- function< string > (required): the name of the Move function for which to retrieve the argument types.

Returns

Vec<MoveFunctionArgType><[ MoveFunctionArgType ]>

Request example

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "iota_getMoveFunctionArgTypes",
      "params": [
        "0x1b33a3cf7eb5dde04ed7ae571db1763006811ff6b7bb35b3d1c780de153af9dd",
        "request",
        "create_and_send_request"
      ],
      "id": 1
    }'

Response example

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        "Pure",
        {
            "Object": "ByValue"
        },
        "Pure",
        "Pure",
        "Pure",
        "Pure",
        "Pure",
        {
            "Object": "ByMutableReference"
        }
    ]
}

`iota_getNormalizedMoveFunction`

Retrieves normalized representation of a Move function.

Parameters

id (integer; required): a request ID (example: 1).
jsonrpc (string; required): a JSON RPC spec used (example: 2.0).
method (string; required): a method used for the request.
params (array; required):
- package< ObjectID > (required): the object ID of the Move package that contains the module definition.
- module_name< string > (required): the name of the Move module in the specified package.
- function_name< string > (required): the name of the function within the module whose normalized representation should be retrieved.

Returns

IotaMoveNormalizedFunction< IotaMoveNormalizedFunction >

isEntry< Boolean > (required): indicates whether the function is an entry function, meaning it can be invoked directly in a transaction.
parameters<[ IotaMoveNormalizedType ]> (required): list of types representing the function's input parameters, in normalized Move type format.
return<[ IotaMoveNormalizedType ]> (required): list of types representing the function's return values, in normalized Move type format.
typeParameters<[ IotaMoveAbilitySet ]> (required): list of type parameters declared by the function, each associated with a set of required abilities (e.g., copy, drop, store).
visibility< IotaMoveVisibility > (required): the visibility of the function — e.g., public, private, or friend — which defines where and how the function can be accessed.

Request example

curl -X POST https://rpc.ankr.com/iota_mainnet/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
      "jsonrpc": "2.0",
      "method": "iota_getNormalizedMoveFunction",
      "params": [
        "0x1b33a3cf7eb5dde04ed7ae571db1763006811ff6b7bb35b3d1c780de153af9dd",
        "request",
        "create_and_send_request"
      ],
      "id": 1
    }'

Response example

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "visibility": "Public",
        "isEntry": false,
        "typeParameters": [],
        "parameters": [
            "Address",
            {
                "Struct": {
                    "address": "0x1b33a3cf7eb5dde04ed7ae571db1763006811ff6b7bb35b3d1c780de153af9dd",
                    "module": "assets_bag",
                    "name": "AssetsBag",
                    "typeArguments": []
                }
            },
            "U32",
            "U32",
            {
                "Vector": {
                    "Vector": "U8"
                }
            },
            {
                "Vector": "U8"
            },
            "U64",
            {
                "MutableReference": {
                    "Struct": {
                        "address": "0x2",
                        "module": "tx_context",
                        "name": "TxContext",
                        "typeArguments": []
                    }
                }
            }
        ],
        "return": []
    }
}

iotax_getLatestIotaSystemStateV2​

Parameters​

Returns​

Request example​

Response example​

iotax_getReferenceGasPrice​

Parameters​

Returns​

Request example​

Response example​

iotax_getStakes​

Parameters​

Returns​

Request example​

Response example​

iotax_getStakesByIds​

Parameters​

Returns​

Request example​

Response example​

iotax_getTimelockedStakes​

Parameters​

Returns​

Request example​

Response example​

iotax_getTimelockedStakesByIds​

Parameters​

Returns​

Request example​

Response example​

iotax_getValidatorsApy​

Parameters​

Returns​

Request example​

Response example​

iota_getMoveFunctionArgTypes​

Parameters​

Returns​

Request example​

Response example​

iota_getNormalizedMoveFunction​

Parameters​

Returns​

Request example​

Response example​

`iotax_getLatestIotaSystemStateV2`

Parameters

Returns

Request example

Response example

`iotax_getReferenceGasPrice`

Parameters

Returns

Request example

Response example

`iotax_getStakes`

Parameters

Returns

Request example

Response example

`iotax_getStakesByIds`

Parameters

Returns

Request example

Response example

`iotax_getTimelockedStakes`

Parameters

Returns

Request example

Response example

`iotax_getTimelockedStakesByIds`

Parameters

Returns

Request example

Response example

`iotax_getValidatorsApy`

Parameters

Returns

Request example

Response example

`iota_getMoveFunctionArgTypes`

Parameters

Returns

Request example

Response example

`iota_getNormalizedMoveFunction`

Parameters

Returns

Request example

Response example