Skip to main content

getObject

Retrieves on-chain details and metadata for one Sui object by its 32-byte hexadecimal Object ID.

Use this method to inspect Move packages and object ownership. You can also check struct fields. A read operation can't change the object. getObject reads from fullnode state. It runs without a transaction, gas, or wallet signature.

  • Class: SuiClient
  • Package: @mysten/sui/client

Signatureโ€‹

Signature
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>

Parametersโ€‹

The method accepts one object. It includes the properties below.

ParameterTypeRequiredDescription
idstringYesThe 32-byte hexadecimal Object ID, such as 0x123....
optionsSuiObjectDataOptionsNoFlags for response data fields. Each flag defaults to false.

SuiObjectDataOptionsโ€‹

By default, getObject returns an ID, version, and digest. Set each flag to true to retrieve more data.

OptionDescription
showTypeReturns the Move type, such as 0x2::coin::Coin<0x2::sui::SUI>.
showContentReturns the parsed Move data fields, representing the object's internal state.
showOwnerReturns the address or object with ownership of this item.
showDisplayReturns Display standard metadata for UI rendering. This metadata includes names, descriptions, and image URLs.
showStorageRebateReturns the storage rebate associated with the object.
showBcsReturns raw Binary Canonical Serialization bytes for client-side decoding.
showPreviousTransactionReturns the digest of the last transaction that modified this object.

Return valueโ€‹

Returns a Promise that resolves to a SuiObjectResponse. The response contains success or error data:

SuiObjectResponse envelope
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ SuiObjectResponse โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚ Success: `response.data` โ”‚ Error: `response.error` โ”‚
โ”‚ - objectId, version โ”‚ - code: "notExists" โ”‚
โ”‚ - type, digest โ”‚ - code: "deleted" โ”‚
โ”‚ - content, owner, display โ”‚ - object_id โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Success response: dataโ€‹

When the object exists, its data property holds SuiObjectData.

Response: success
{
"data": {
"objectId": "0x...",
"version": "10",
"digest": "...",
"type": "0x2::coin::Coin<0x2::sui::SUI>",
"content": {
"dataType": "moveObject",
"fields": { "balance": "1000000000" }
},
"owner": {
"AddressOwner": "0xabc..."
}
}
}

Error response: errorโ€‹

The error property returns details when a transaction deletes the object or wraps it in another object. It also returns details when the ID doesn't exist.

Response: error
{
"error": {
"code": "notExists",
"object_id": "0x..."
}
}

Usage examplesโ€‹

Check whether an object existsโ€‹

This lightweight query doesn't request data fields. It returns only the digest and version number.

checkExists.js
const response = await client.getObject({
id: '0x123...'
});

if (response.error) {
console.log("Object doesn't exist.");
} else if (response.data) {
console.log("Object exists at version:", response.data.version);
} else {
console.log("The response didn't include object data.");
}

Fetch non-fungible token metadata and display fieldsโ€‹

This request sets showContent to read on-chain fields and showDisplay to retrieve UI assets.

fetchNFT.js
const nft = await client.getObject({
id: '0x123...',
options: {
showContent: true,
showDisplay: true
}
});

if (nft.data) {
const name = nft.data.content?.fields?.name;
const imageUrl = nft.data.display?.data?.image_url;
console.log(`NFT Name: ${name}, Image: ${imageUrl}`);
} else {
console.warn("Item failed to load:", nft.error);
}

Verify object ownershipโ€‹

Use this code to check whether a specific account address controls an item.

verifyOwnership.js
const item = await client.getObject({
id: '0x123...',
options: { showOwner: true }
});

const owner = item.data?.owner;

if (owner && owner.AddressOwner === '0xMyAddress...') {
console.log("You own this item.");
}

Common errorsโ€‹

Error codeCauseResolution
notExistsThe Object ID contains valid hex, but the network can't locate the object.Verify the ID or confirm a previous transaction didn't delete the object.
deletedA transaction deleted, burned, or pruned the object from the active state.You can't retrieve historical data for deleted objects through getObject.
invalid_paramThe Object ID has a malformed 32-byte hex format.Check that the ID starts with 0x and has the correct length.

See alsoโ€‹