Sui gRPC (2/3)

API reference for Sui. All methods ->

Part 2 of 3: 1 · 2 · 3

Methods list

GetDatatype

Retrieves metadata about a Move struct/type.

Parameters

• package_id (string; required): The storage ID (storage_id) of the package that defines the datatype.
• module_name (string; required): The name of the module where the datatype is defined.
• name (string; required): The name of the datatype to retrieve.

Returns

• datatype (object; optional): Information about the requested Move datatype.
  • typeName (string): Fully qualified name (<package>::<module>::<name>).
  • definingId (string): Package ID of the version where this datatype was first introduced.
  • module (string): Name of the defining module.
  • name (string): Name of the datatype.
  • abilities (array): List of abilities (e.g., COPY, DROP, STORE, KEY).
  • typeParameters (array): Type parameter descriptors.
    • constraints (array): Ability constraints.
    • isPhantom (boolean): Whether the type parameter is phantom.
  • kind (string): Either STRUCT or ENUM.
  • fields (array; optional): Field descriptors (only for struct types).
    • name (string): Field name.
    • position (number): Field position in the struct definition.
    • type (object): Field type signature.
      • type (string): Primitive or composite type (e.g., U64, ADDRESS, VECTOR, DATATYPE, etc.).
      • typeName (string; optional): Fully qualified datatype name (when type is DATATYPE).
      • typeParameterInstantiation (array; optional): Applied generic parameters.
      • typeParameter (number; optional): Index of the type parameter (when applicable).
  • variants (array; optional): Enum variant descriptors (only for enum types).
    • name (string): Variant name.
    • position (number): Variant order.
    • fields (array): Field descriptors for this variant.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "package_id": "0x2",
        "module_name": "coin",
        "name": "Coin"
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.MovePackageService.GetDatatype

Response example

{
  "datatype": {
    "typeName": "0x0000000000000000000000000000000000000000000000000000000000000002::coin::Coin",
    "definingId": "0x0000000000000000000000000000000000000000000000000000000000000002",
    "module": "coin",
    "name": "Coin",
    "abilities": [
      "STORE",
      "KEY"
    ],
    "typeParameters": [
      {
        "isPhantom": true
      }
    ],
    "kind": "STRUCT",
    "fields": [
      {
        "name": "id",
        "position": 0,
        "type": {
          "type": "DATATYPE",
          "typeName": "0x0000000000000000000000000000000000000000000000000000000000000002::object::UID"
        }
      },
      {
        "name": "balance",
        "position": 1,
        "type": {
          "type": "DATATYPE",
          "typeName": "0x0000000000000000000000000000000000000000000000000000000000000002::balance::Balance",
          "typeParameterInstantiation": [
            {
              "type": "TYPE_PARAMETER",
              "typeParameter": 0
            }
          ]
        }
      }
    ]
  }
}

---

GetFunction

Retrieves metadata about a Move function.

Parameters

• package_id (string; required): The storage ID (storage_id) of the package that defines the function.
• module_name (string; required): The name of the module where the function is defined.
• name (string; required): The name of the function to retrieve.

Returns

• function (object; optional): Metadata describing the requested Move function.
  • name (string): The function name.
  • visibility (string): One of PRIVATE, PUBLIC, or FRIEND.
  • isEntry (boolean): Whether the function is marked as entry.
  • typeParameters (array): Type parameter descriptors.
    • constraints (array): Ability constraints required by this type parameter.
    • isPhantom (boolean): Indicates whether this type parameter is phantom.
  • parameters (array): Function parameter type descriptors.
    • reference (string): Reference kind (IMMUTABLE, MUTABLE, or UNKNOWN).
    • body (object): Type signature.
      • type (string): Primitive or composite type (U64, ADDRESS, VECTOR, DATATYPE, etc.).
      • typeName (string; optional): Fully qualified datatype name (when applicable).
      • typeParameterInstantiation (array; optional): Applied type parameters (for generics).
      • typeParameter (number; optional): Index of the type parameter.
  • returns (array): Function return type descriptors.
    • Same structure as parameters.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "package_id": "0x2",
        "module_name": "coin",
        "name": "mint"
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.MovePackageService.GetFunction

Response example

{
  "function": {
    "name": "mint",
    "visibility": "PUBLIC",
    "isEntry": false,
    "typeParameters": [
      {}
    ],
    "parameters": [
      {
        "reference": "MUTABLE",
        "body": {
          "type": "DATATYPE",
          "typeName": "0x0000000000000000000000000000000000000000000000000000000000000002::coin::TreasuryCap",
          "typeParameterInstantiation": [
            {
              "type": "TYPE_PARAMETER",
              "typeParameter": 0
            }
          ]
        }
      },
      {
        "body": {
          "type": "U64"
        }
      },
      {
        "reference": "MUTABLE",
        "body": {
          "type": "DATATYPE",
          "typeName": "0x0000000000000000000000000000000000000000000000000000000000000002::tx_context::TxContext"
        }
      }
    ],
    "returns": [
      {
        "body": {
          "type": "DATATYPE",
          "typeName": "0x0000000000000000000000000000000000000000000000000000000000000002::coin::Coin",
          "typeParameterInstantiation": [
            {
              "type": "TYPE_PARAMETER",
              "typeParameter": 0
            }
          ]
        }
      }
    ]
  }
}

---

GetPackage

Retrieves information about a Move package.

Parameters

• package_id (string; required): The storage ID (storage_id) of the package to retrieve.

Returns

• package (object; optional): Metadata describing the requested Move package.
  • storageId (string): The on-chain ObjectId for this specific package version.
  • originalId (string): The package’s original ID (the first published version). Stable across upgrades.
  • version (number): The version number of this package.
  • modules (array): List of Move modules defined in the package.
    • name (string): Module name.
    • contents (string): Base64-encoded compiled bytecode.
    • datatypes (array): Datatype descriptors defined in the module.
    • functions (array): Function descriptors defined in the module.
  • typeOrigins (array): Mapping of datatypes to the package version that first defined them.
    • moduleName (string)
    • datatypeName (string)
    • packageId (string)
  • linkage (array): Mapping of dependency package IDs.
    • originalId (string): Runtime ID used by dependent packages.
    • upgradedId (string): Storage ID used for loading.
    • upgradedVersion (number): Version corresponding to upgraded_id.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "package_id": "0x2"
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.MovePackageService.GetPackage

Response example

Below is a truncated example:

{
  "package": {
    "storageId": "0x2",
    "originalId": "0x2",
    "version": "1",
    "modules": [
      {
        "name": "coin",
        "contents": "BASE64_BYTECODE...",
        "datatypes": [
          {
            "typeName": "0x2::coin::Coin",
            "definingId": "0x2",
            "module": "coin",
            "name": "Coin",
            "abilities": ["COPY", "DROP", "STORE"],
            "typeParameters": [],
            "kind": "STRUCT",
            "fields": [
              {
                "name": "value",
                "position": 0,
                "type": {
                  "type": "U64"
                }
              }
            ]
          }
        ],
        "functions": [
          {
            "name": "mint",
            "visibility": "FRIEND",
            "isEntry": false,
            "typeParameters": [],
            "parameters": [],
            "returns": []
          }
        ]
      }
    ],
    "typeOrigins": [
      {
        "moduleName": "coin",
        "datatypeName": "Coin",
        "packageId": "0x2"
      }
    ],
    "linkage": [
      {
        "originalId": "0x1",
        "upgradedId": "0x1",
        "upgradedVersion": "1"
      }
    ]
  }
}

---

ListPackageVersions

Lists the published versions of a package.

Parameters

• package_id (string; required): The storage ID (storage_id) of any version of the package.
• page_size (number; optional): Maximum number of versions to return. Defaults to 1000, maximum is 10000.
• page_token (string; optional): Token from a previous response used to fetch the next page. Must match the original request parameters.

Returns

• versions (array): List of available package versions, ordered by version.
  • packageId (string): Storage ID of this package version.
  • version (number): Version number.
• nextPageToken (string; optional): Token to retrieve the next page. Omitted if no more versions are available.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "package_id": "0x2",
        "page_size": 5
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.MovePackageService.ListPackageVersions

Response example

{
  "versions": [
    {
      "packageId": "0x0000000000000000000000000000000000000000000000000000000000000002",
      "version": "38"
    },
    {
      "packageId": "0x0000000000000000000000000000000000000000000000000000000000000002",
      "version": "39"
    },
    {
      "packageId": "0x0000000000000000000000000000000000000000000000000000000000000002",
      "version": "40"
    },
    {
      "packageId": "0x0000000000000000000000000000000000000000000000000000000000000002",
      "version": "41"
    },
    {
      "packageId": "0x0000000000000000000000000000000000000000000000000000000000000002",
      "version": "42"
    }
  ],
  "nextPageToken": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAIrAAAAAAAAAA=="
}

---

Signature Verification Service:

Performs cryptographic verification for signatures, proofs, and signed messages.

VerifySignature

Validates a signature against a message and public key.

Parameters

• message (object; required): BCS-encoded message to verify.

  • name (string; required): Message type identifier (for example: "PersonalMessage", "TransactionData").
  • value (string; required): Base64-encoded BCS bytes of the message.

• signature (object; required): Signature to verify, represented as a UserSignature.

  • May contain one of the following depending on the scheme:
    • simple → ED25519 / SECP256K1 / SECP256R1 signatures
    • multisig → multisig aggregated signature
    • zklogin → zkLogin authenticator
    • passkey → passkey authenticator
  • scheme (string; optional): Signature scheme identifier (e.g., "ED25519").

• address (string; optional): Expected address derived from the signature. Verification fails unless the derived address matches this value.

• jwks (array; optional): List of JSON Web Keys used to verify zkLogin signatures. If omitted, the node uses the active on-chain JWK set.

  • Each entry:
    • kty (string): Key type (e.g., "RSA").
    • e (string): RSA public exponent.
    • n (string): RSA modulus.
    • alg (string): Algorithm (e.g., "RS256").

Returns

• isValid (boolean): Indicates whether the provided signature is valid for the given message.
• reason (string; optional): Error explanation when isValid is false.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "message": {
          "name": "PersonalMessage",
          "value": "BASE64_BCS_MESSAGE"
        },
        "signature": {
          "scheme": "ED25519",
          "simple": {
            "scheme": "ED25519",
            "signature": "BASE64_SIGNATURE",
            "publicKey": "BASE64_PUBLIC_KEY"
          }
        },
        "address": "0xREPLACE_WITH_EXPECTED_ADDRESS",
        "jwks": [
          {
            "kty": "RSA",
            "e": "AQAB",
            "n": "BASE64URL_RSA_MODULUS",
            "alg": "RS256"
          }
        ]
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.SignatureVerificationService.VerifySignature

Response example

{
  "isValid": true
}

---

State Service:

Provides access to detailed on-chain state including objects, balances, ownership, object layouts, dynamic fields, and protocol configuration. This is the main service for querying Sui state data.

GetBalance

Retrieves balance for a specific coin type.

Parameters

• owner (string; required): Sui address whose balance you want to query.
• coin_type (string; required): Fully qualified coin type (for example: 0x2::sui::SUI).

Returns

• balance (object; optional): Balance information for the requested coin type.
  • coinType (string): Coin type identifier.
  • balance (string): Total balance in the smallest unit of the coin.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "owner": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "coin_type": "0x2::sui::SUI"
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.StateService.GetBalance

Response example

{
  "balance": {
    "coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
    "balance": "2044869853603"
  }
}

---

GetCoinInfo

Retrieves metadata for a coin type.

Parameters

• coin_type (string; required): Fully qualified coin type to query (example: 0x2::sui::SUI).

Returns

• coinType (string): The coin type returned by the node.

• metadata (object; optional): Standard metadata for this coin type.

  • id (string): ObjectId of the metadata object.
  • decimals (number): Number of decimal places.
  • name (string): Human-readable token name.
  • symbol (string): Token symbol.
  • description (string): Token description.
  • iconUrl (string; optional): URL to the coin icon.
  • metadataCapId (string; optional): If claimed, ID of MetadataCap.
  • metadataCapState (string): State of the MetadataCap.

• treasury (object; optional): Information about the coin’s TreasuryCap object.

  • id (string): TreasuryCap object ID.
  • totalSupply (string): Total supply (smallest unit).
  • supplyState (string): Whether supply is FIXED, BURN_ONLY, etc.

• regulatedMetadata (object; optional): Applies only to regulated coins.

  • id (string): RegulatedCoinMetadata object ID.
  • coinMetadataObject (string): Linked metadata object ID.
  • denyCapObject (string): Deny list controller object.
  • allowGlobalPause (boolean): Whether coin can be globally paused.
  • variant (number): Variant of regulated metadata.
  • coinRegulatedState (string): REGULATED / UNREGULATED / UNKNOWN.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "coin_type": "0x2::sui::SUI"
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.StateService.GetCoinInfo

Response example

{
  "coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
  "metadata": {
    "id": "0xf256d3fb6a50eaa748d94335b34f2982fbc3b63ceec78cafaa29ebc9ebaf2bbc",
    "decimals": 9,
    "name": "Sui",
    "symbol": "SUI",
    "description": "",
    "iconUrl": "",
    "metadataCapState": "UNCLAIMED"
  },
  "treasury": {
    "totalSupply": "10000000000000000000",
    "supplyState": "FIXED"
  },
  "regulatedMetadata": {
    "coinRegulatedState": "UNREGULATED"
  }
}

---

ListBalances

Lists all coin balances for an address.

Parameters

• owner (string; required): Address whose balances to list.
• page_size (uint32; optional): Maximum number of entries to return (default: 50; max: 1000).
• page_token (bytes; optional): Token for fetching the next page.

Returns

• balances (array): List of balances for each coin type.

  • coinType (string): Fully qualified coin type.
  • balance (string): Total balance in the smallest unit.

• nextPageToken (bytes; optional): Token for retrieving the next page.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "owner": "0x123456789abcdef123456789abcdef123456789abcdef123456789abcdef1234",
        "page_size": 20
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.StateService.ListBalances

Response example

{
  "balances": [
    {
      "coinType": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
      "balance": "1048533540"
    },
    {
      "coinType": "0x022cac18d673c28bb29a69bf1cc4b86344d81e1ae29d9bd2220745f75e4c980c::mat::MAT",
      "balance": "1000000000000"
    },
    {
      "coinType": "0x03cbd6eac52f4e6a98cd8ee44e1d7c8960ccc94cb48fcd94b45846df2c58ce07::mat::MAT",
      "balance": "1000000000000"
    },
    {
      "coinType": "0x25bb6dda13a9e44f0a5eef5edf6967e551f3c8e57e3495f2f1da1285a2d45955::mat::MAT",
      "balance": "1000000000000"
    },
    {
      "coinType": "0x49b3e7b2b7f3fec982c1c40d4acfcc55361e0925d1b689b643251b01ee6e635c::mat::MAT",
      "balance": "1000000000000"
    },
    {
      "coinType": "0x7e21166ee1ae31652cdbbac427d4830e172a0b8a65eb1c2f37e6b7c9fc24bd53::mat::MAT",
      "balance": "1000000000000"
    }
  ]
}

---

ListDynamicFields

Lists dynamic fields under an object.

Parameters

• parent (string; required): The UID/ObjectId of the parent that owns the dynamic fields.
• page_size (uint32; optional): Maximum number of entries to return (default: 50; max: 1000).
• page_token (bytes; optional): Token for fetching the next page.
• read_mask (object; optional): Field mask specifying which fields to include.
  • paths (array of strings): Protobuf field names to return (for example: "parent", "field_id", "field_object", "name", "value", "value_type", "child_id", "child_object"). Some implementations accept "*" to request all available fields.

Returns

• dynamicFields (array): Page of dynamic fields under the parent. Each entry may contain:

  • kind (string): "FIELD" or "OBJECT".
  • parent (string): Parent ObjectId.
  • fieldId (string): ObjectId representing this dynamic field.
  • fieldObject (object; optional): The Object when the field is stored as an object.
  • name (object; optional): BCS-encoded dynamic field name.
  • value (object; optional): BCS-encoded dynamic field value.
  • valueType (string; optional): Type of the value or child object.
  • childId (string; optional): ObjectId of a child object (when kind = OBJECT).
  • childObject (object; optional): The dynamic child object itself.

• nextPageToken (bytes; optional): Token for retrieving the next results page.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "parent": "0xREAL_PARENT_WITH_DYNAMIC_FIELDS",
        "page_size": 10
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.StateService.ListDynamicFields

Response example

{
  "dynamicFields": [
    {
      "kind": "FIELD",
      "parent": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
      "fieldId": "0xa1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1",
      "name": {
        "name": "u64",
        "value": "AAAAAAE="
      },
      "value": {
        "name": "u64",
        "value": "AAAH6A=="
      },
      "valueType": "u64"
    },
    {
      "kind": "OBJECT",
      "parent": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcd",
      "fieldId": "0x99ffeeddccbbaa99887766554433221100ffeeddccbbaa9988776655443322",
      "childId": "0x22ee11ddccbb0099887766554433221100ffeeccbb22aa9988776655443300",
      "childObject": {
        "objectId": "0x22ee11ddccbb0099887766554433221100ffeeccbb22aa9988776655443300",
        "version": "5",
        "digest": "B9k7QJ4twQ6nB8c6jZpTZxB6TcvG6YtM2h5b2j2G5mTf",
        "objectType": "0x2::my_module::MyStruct",
        "owner": {
          "kind": "AddressOwner",
          "addressOwner": "0x87654321abcdef00112233445566778899aabbccddeeff0011223344556677"
        }
      },
      "valueType": "0x2::my_module::MyStruct"
    }
  ],
  "nextPageToken": "CgYIARAA"
}

---

ListOwnedObjects

Lists the objects owned by an address.

Parameters

• owner (string; required): The Sui address whose owned objects should be listed.

• page_size (uint32; optional): Maximum number of objects to return (default: 50; max: 1000).

• page_token (bytes; optional): Token from a previous response to fetch the next page.

• read_mask (object; optional): Field mask selecting which object fields to include. If omitted, defaults to: object_id, version, object_type.

  • paths (array of strings): Field names to include (e.g., "object_id", "version", "owner", "object_type", "digest", "bcs", "json").

• object_type (string; optional): Optional type filter:

  • "0x2::coin::Coin" → returns all Coin<T> objects.
  • "0x2::coin::Coin<0x2::sui::SUI>" → returns only Coin<SUI>.
  • Any Move struct tag is accepted.

Returns

• objects (array): List of owned objects with fields requested via read_mask. Each object may include fields such as:

  • objectId (string): Object identifier.
  • version (string): Object version.
  • digest (string): Object digest.
  • owner (object): Ownership details.
  • objectType (string): Move type or "package".
  • bcs (object): BCS-encoded value (if requested).
  • json (object): JSON representation (if requested).
  • Additional fields depending on the mask.

• nextPageToken (bytes; optional): Returned if more pages are available.

Request example

grpcurl \
  -H "x-token: token-value" \
  -d '{
        "owner": "0xd8908c165dee785924e7421a0fd0418a19d5daeec395fd505a92a0fd3117e428",
        "read_mask": {
            "paths": ["object_id", "version", "owner", "digest", "object_type"]
        }
      }' \
  sui.grpc.ankr.com:443 \
  sui.rpc.v2.StateService.ListOwnedObjects

Response example

{
  "objects": [
    {
      "objectId": "0x5b52d6863faad645692a0928fe7bc35df999ecfcf2ad029e471b42a4abbecec6",
      "version": "527071929",
      "digest": "DigX1wVS5xGHCELdhG1BSzHULNkF5sM3aPpS9Q1ZfHri",
      "owner": {
        "kind": "ADDRESS",
        "address": "0xd8908c165dee785924e7421a0fd0418a19d5daeec395fd505a92a0fd3117e428"
      },
      "objectType": "0x0000000000000000000000000000000000000000000000000000000000000002::coin::Coin\u003c0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI\u003e"
    },
    {
      "objectId": "0x4fb01474fd465cf97e36f6e758b9f3f47c56d4907ea74552fc0027c9318b354a",
      "version": "527071928",
      "digest": "4WohPFhmhq1ezPh7XqP8AexG9bg5nEXcY82VoKBVaL15",
      "owner": {
        "kind": "ADDRESS",
        "address": "0xd8908c165dee785924e7421a0fd0418a19d5daeec395fd505a92a0fd3117e428"
      },
      "objectType": "0x0000000000000000000000000000000000000000000000000000000000000002::coin::Coin\u003c0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI\u003e"
    }
  ]
}

---

Subscription Service:

Supports server-side streaming for real-time updates. Use it to subscribe to events, transactions, checkpoints, or other continuous data feeds.