Sui JSON-RPC (deprecated) (3/4)

API reference for Sui. All methods ->

Part 3 of 4: 1 · 2 · 3 · 4

Methods supported

`sui_tryGetPastObject`

Retrieves the object information for a specified version.

There is no software-level guarantee/SLA that objects with past versions can be retrieved by this API, even if the object and version exists/existed. The result may vary across nodes depending on their pruning policies.

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):
- <object_id>: the ID of the queried object.
- <version> (sequence number): the version of the queried object. If None, default to the latest known version.
- <options>: options for specifying the content to be returned.

Returns

SuiPastObjectResponse: past object data.

Request example

curl -X POST https://rpc.ankr.com/sui/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_tryGetPastObject",
  "params": [
    "0x7b073091241e64725b7a8b2bed3f37bc8f549d41b5408a783aa00bd1cb49cc1c",
    952132138,
    {
      "showType": true,
      "showOwner": true,
      "showPreviousTransaction": true,
      "showDisplay": false,
      "showContent": true,
      "showBcs": false,
      "showStorageRebate": true
    }
  ]
}'

Response example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "VersionFound",
    "details": {
      "objectId": "0x7b073091241e64725b7a8b2bed3f37bc8f549d41b5408a783aa00bd1cb49cc1c",
      "version": "952132138",
      "digest": "22FgbKATz1Vsx4CALemNuD3zv1dTVXoJoxoMMzodmXu6",
      "type": "0x2::dynamic_field::Field<u64, 0x3::staking_pool::PoolTokenExchangeRate>",
      "owner": {
        "ObjectOwner": "0xe442ab05c4060ff179b7dc9bc60bc05324befd384ab10a87a5138e6477b2d5da"
      },
      "previousTransaction": "3kxeUe1YNKRcHQd46b49ZVocqWm9bUZSjwxbx2e2tkds",
      "storageRebate": "0",
      "content": {
        "dataType": "moveObject",
        "type": "0x2::dynamic_field::Field<u64, 0x3::staking_pool::PoolTokenExchangeRate>",
        "hasPublicTransfer": false,
        "fields": {
          "id": {
            "id": "0x7b073091241e64725b7a8b2bed3f37bc8f549d41b5408a783aa00bd1cb49cc1c"
          },
          "name": "1200",
          "value": {
            "type": "0x3::staking_pool::PoolTokenExchangeRate",
            "fields": {
              "pool_token_amount": "27371146201545824",
              "sui_amount": "27415649547761097"
            }
          }
        }
      }
    }
  }
}

`sui_tryMultiGetPastObjects`

Retrieves the object information for a specified version.

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):
- <past_objects>: a vector of object and versions to be queried.
- <options>: options for specifying the content to be returned.

Returns

SuiPastObjectResponse: past object data.

`suix_getAllBalances`

Retrieves the total coin balance for all coin types owned by the address owner.

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>: the owner's Sui address.

Returns

Vec<Balance>: all balances for the address in the request.

Request example

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

Response example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
      "coinObjectCount": 1,
      "totalBalance": "12131679432",
      "lockedBalance": {},
      "fundsInAddressBalance": "0"
    }
  ]
}

`suix_getBalance`

Retrieves the total coin balance for one coin type owned by the address owner.

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>: the owner's Sui address.
- <coin_type> (string, optional): type names for the coin (example 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), defaults to 0x2::sui::SUI if not specified.

Returns

coinObjectCount
coinType
lockedBalance
totalBalance

Request example

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

Response example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
    "coinObjectCount": 1,
    "totalBalance": "12131679432",
    "lockedBalance": {},
    "fundsInAddressBalance": "0"
  }
}

`suix_getCoinMetadata`

Retrieves metadata (as symbol or decimals) for a coin.

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):
- <coin_type> (string): type names for the coin (example 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC).

Returns

decimals: the number of decimal places the coin uses.
description: token description.
iconUrl: URL for the token logo.
id: an object ID for the CoinMetadata object.
name: a token name.
symbol: a token symbol.

Request example

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

Response example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "decimals": 6,
    "name": "USDC",
    "symbol": "USDC",
    "description": "USDC is a US dollar-backed stablecoin issued by Circle. USDC is designed to provide a faster, safer, and more efficient way to send, spend, and exchange money around the world.",
    "iconUrl": "https://circle.com/usdc-icon",
    "id": "0x75cfbbf8c962d542e99a1d15731e6069f60a00db895407785b15d14f606f2b4a"
  }
}

`suix_getCoins`

Retrieves all coin type objects owned by 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>: the owner's Sui address.
- <coin_type> (string): type names for the coin (example 0x168da5bf1f48dafc111b0a488fa454aca95e0b5e::usdc::USDC), defaults to 0x2::sui::SUI if not specified.
- <cursor> (optional): a page cursor.
- <limit> (uint): max number of items per page.

Returns

CoinPage: all SUI coins owned by the address provided.

Request example

curl -X POST https://rpc.ankr.com/sui/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "suix_getCoins",
  "params": [
    "0x30430471882ea79bd2153df98b455c6b62a6acf76642a17649665266eddb9a26",
    "0x2::sui::SUI",
    null,
    3
  ]
}'

Response example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "data": [
      {
        "coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
        "coinObjectId": "0x4da1e109117bd649ca431d91f11632ea84e577ed53c23ab2f8ab1e80aeb37887",
        "version": "1062199345",
        "digest": "4fg9Zph1VcoDDup9MuNUKMVYK4iWYSpckB4NqvXh6veB",
        "balance": "12131679432",
        "previousTransaction": "jaBYC1XVXR7TVhA2YvapQ34fjNw2Jyuba8C8VVA533s"
      }
    ],
    "nextCursor": "zAEAMEMEcYgup5vSFT35i0Vca2KmrPdmQqF2SWZSZu3bmiYAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAAAAAAAEY29pbgAAAAAAAAAEQ29pbgAAAAAAAAABAAAABwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACAAAAAAAAAANzdWkAAAAAAAAAA1NVSQAAAAAAAAAAAf////0s5UM3TaHhCRF71knKQx2R8RYy6oTld+1Twjqy+KsegK6zeIc=",
    "hasNextPage": false
  }
}

`suix_getDynamicFieldObject`

Retrieves the dynamic field object information for a specified object.

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):
- <parent_object_id>: the ID of the queried parent object.
- <name>: the name of the dynamic field.

Returns

data: object data.
error: object response error.

Request example

curl -X POST https://rpc.ankr.com/sui/YOUR_ANKR_API_KEY \
-H 'Content-Type: application/json' \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "suix_getDynamicFieldObject",
  "params": [
    "0xe442ab05c4060ff179b7dc9bc60bc05324befd384ab10a87a5138e6477b2d5da",
    {
      "type": "u64",
      "value": "1200"
    }
  ]
}'

Response example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "data": {
      "objectId": "0x7b073091241e64725b7a8b2bed3f37bc8f549d41b5408a783aa00bd1cb49cc1c",
      "version": "952132138",
      "digest": "22FgbKATz1Vsx4CALemNuD3zv1dTVXoJoxoMMzodmXu6",
      "type": "0x2::dynamic_field::Field<u64, 0x3::staking_pool::PoolTokenExchangeRate>",
      "owner": {
        "ObjectOwner": "0xe442ab05c4060ff179b7dc9bc60bc05324befd384ab10a87a5138e6477b2d5da"
      },
      "previousTransaction": "3kxeUe1YNKRcHQd46b49ZVocqWm9bUZSjwxbx2e2tkds",
      "storageRebate": "0",
      "content": {
        "dataType": "moveObject",
        "type": "0x2::dynamic_field::Field<u64, 0x3::staking_pool::PoolTokenExchangeRate>",
        "hasPublicTransfer": false,
        "fields": {
          "id": {
            "id": "0x7b073091241e64725b7a8b2bed3f37bc8f549d41b5408a783aa00bd1cb49cc1c"
          },
          "name": "1200",
          "value": {
            "type": "0x3::staking_pool::PoolTokenExchangeRate",
            "fields": {
              "pool_token_amount": "27371146201545824",
              "sui_amount": "27415649547761097"
            }
          }
        }
      }
    }
  }
}

`suix_getDynamicFields`

Retrieves the list of dynamic field objects owned by an object.

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):
- <parent_object_id> (string, hex): the ID of the parent object.
- <cursor> (optional): a page cursor. If provided, the query will start from the next item after the specified cursor. Defaults to start from the first item if not specified.
- <limit> (uint): max items returned per page; defaults to [QUERY_MAX_RESULT_LIMIT] if not specified.

Returns

DynamicFieldPage: dynamic fields for the object the request provides.

Request example

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

Response example

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "data": [
      {
        "name": {
          "type": "u64",
          "value": "1252"
        },
        "bcsEncoding": "base64",
        "bcsName": "5AQAAAAAAAA=",
        "type": "DynamicField",
        "objectType": "0x0000000000000000000000000000000000000000000000000000000000000003::staking_pool::PoolTokenExchangeRate",
        "objectId": "0x01d79b559dafa1c8b89fc4ab8801ae2718df84f3ba017ef9ae6989d205b101be",
        "version": 1001398779,
        "digest": "rdVfqjRaYDQTCAtddchrxh8XuvHf3jmH5ihXhLe91fD"
      },
      {
        "name": {
          "type": "u64",
          "value": "1262"
        },
        "bcsEncoding": "base64",
        "bcsName": "7gQAAAAAAAA=",
        "type": "DynamicField",
        "objectType": "0x0000000000000000000000000000000000000000000000000000000000000003::staking_pool::PoolTokenExchangeRate",
        "objectId": "0x024b03126ffaba1798c672bfa378251558ab34f410531cc6ecf196873d898dde",
        "version": 1020577342,
        "digest": "CiKYycLoVT8bbnFhDSsHyqGhFc7Viz5zpVv8uWRtZrxM"
      }
    ],
    "nextCursor": "7QEB5EKrBcQGD/F5t9ybxgvAUyS+/ThKsQqHpROOZHey1doAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAAAAAAANZHluYW1pY19maWVsZAAAAAAAAAAFRmllbGQAAAAAAAAAAgAAAAIAAAAHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMAAAAAAAAADHN0YWtpbmdfcG9vbAAAAAAAAAAVUG9vbFRva2VuRXhjaGFuZ2VSYXRlAAAAAAAAAAAAAksDEm/6uheYxnK/o3glFVirNPQQUxzG7PGWhz2Jjd4=",
    "hasNextPage": true
  }
}

`suix_getLatestSuiSystemState`

Retrieves the latest SUI system state object on-chain.

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

activeValidators: the list of active validators in the current epoch.
atRiskValidators: the map storing the number of epochs for which each validator has been below the low stake threshold.
epoch: the current epoch ID, starting from 0.
epochDurationMs: the duration of an epoch, in milliseconds.
epochStartTimestampMs: the Unix timestamp of the current epoch start.
inactivePoolsId: the ID of the object that maps from a staking pool ID to the inactive validator that has that pool as its staking pool.
inactivePoolsSize: the of inactive staking pools.
maxValidatorCount: the max number of active validators at any moment. We do not allow the number of validators in any epoch to go above this.
minValidatorJoiningStake: the lower bound on the amount of stake required to become a validator.
pendingActiveValidatorsId: the ID of the object that contains the list of new validators that will join at the end of the epoch.
pendingActiveValidatorsSize: the number of new validators that will join at the end of the epoch.
pendingRemovals: the removal of requests from the validators. Each element is an index pointing to active_validators.
protocolVersion: the current protocol version, starting from 1.
referenceGasPrice: the reference gas price for the current epoch.
safeMode: whether the system is running in a downgraded safe mode due to a non-recoverable bug. This is set whenever we failed to execute advance_epoch, and ended up executing advance_epoch_safe_mode. It can be reset once we are able to successfully execute advance_epoch.
safeModeComputationRewards: the amount of computation rewards accumulated (and not yet distributed) during safe mode.
safeModeNonRefundableStorageFee: the amount of non-refundable storage fee accumulated during safe mode.
safeModeStorageRebates: the amount of storage rebates accumulated (and not yet burned) during safe mode.
safeModeStorageRewards: the amount of storage rewards accumulated (and not yet distributed) during safe mode.
stakeSubsidyBalance: the balance of SUI set aside for stake subsidies that will be drawn down over time.
stakeSubsidyCurrentDistributionAmount: the amount of stake subsidy to be drawn down per epoch. This amount decays and decreases over time.
stakeSubsidyDecreaseRate: the rate at which the distribution amount decays at the end of each period. Expressed in basis points.
stakeSubsidyDistributionCounter: this counter may be different from the current epoch number if in some epochs it is decided to skip the subsidy.
stakeSubsidyPeriodLength: the number of distributions to occur before the distribution amount decays.
stakeSubsidyStartEpoch: the starting epoch in which stake subsidies start being paid out.
stakingPoolMappingsId: the ID of the object that maps from staking pool's ID to the sui address of a validator.
stakingPoolMappingsSize: the number of staking pool mappings.
storageFundNonRefundableBalance: the non-refundable portion of the storage fund coming from storage reinvestment, non-refundable storage rebates and any leftover staking rewards.
storageFundTotalObjectStorageRebates: the storage rebates of all the objects on-chain stored in the storage fund.
systemStateVersion: the current version of the system state data structure type.
totalStake: the total amount of stake from all active validators at the beginning of the epoch.
validatorCandidatesId: the ID of the object that stores proactive validators, mapping their addresses to their Validator structs.
validatorCandidatesSize: the number of proactive validators.
validatorLowStakeGracePeriod: the validator can have stake below validator_low_stake_threshold for this many epochs before being kicked out.
validatorLowStakeThreshold: validators with stake amount below validator_low_stake_threshold are considered to have low stake and will be escorted out of the validator set after being below this threshold for more than validator_low_stake_grace_period number of epochs.
validatorReportRecords: a map storing the records of validator reporting each other.
validatorVeryLowStakeThreshold: validators with stake below validator_very_low_stake_threshold will be removed immediately at epoch change, no grace period.

Request example

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

Response example

{
  "jsonrpc": "2.0",
  "result": "some_system_state"
}

Methods supported​

sui_tryGetPastObject​

Parameters​

Returns​

Request example​

Response example​

sui_tryMultiGetPastObjects​

Parameters​

Returns​

suix_getAllBalances​

Parameters​

Returns​

Request example​

Response example​

suix_getBalance​

Parameters​

Returns​

Request example​

Response example​

suix_getCoinMetadata​

Parameters​

Returns​

Request example​

Response example​

suix_getCoins​

Parameters​

Returns​

Request example​

Response example​

suix_getDynamicFieldObject​

Parameters​

Returns​

Request example​

Response example​

suix_getDynamicFields​

Parameters​

Returns​

Request example​

Response example​

suix_getLatestSuiSystemState​

Parameters​

Returns​

Request example​

Response example​

Methods supported

`sui_tryGetPastObject`

Parameters

Returns

Request example

Response example

`sui_tryMultiGetPastObjects`

Parameters

Returns

`suix_getAllBalances`

Parameters

Returns

Request example

Response example

`suix_getBalance`

Parameters

Returns

Request example

Response example

`suix_getCoinMetadata`

Parameters

Returns

Request example

Response example

`suix_getCoins`

Parameters

Returns

Request example

Response example

`suix_getDynamicFieldObject`

Parameters

Returns

Request example

Response example

`suix_getDynamicFields`

Parameters

Returns

Request example

Response example

`suix_getLatestSuiSystemState`

Parameters

Returns

Request example

Response example