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โ
client.getObject(input: GetObjectParams): Promise<SuiObjectResponse>
Parametersโ
The method accepts one object. It includes the properties below.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The 32-byte hexadecimal Object ID, such as 0x123.... |
options | SuiObjectDataOptions | No | Flags 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.
| Option | Description |
|---|---|
showType | Returns the Move type, such as 0x2::coin::Coin<0x2::sui::SUI>. |
showContent | Returns the parsed Move data fields, representing the object's internal state. |
showOwner | Returns the address or object with ownership of this item. |
showDisplay | Returns Display standard metadata for UI rendering. This metadata includes names, descriptions, and image URLs. |
showStorageRebate | Returns the storage rebate associated with the object. |
showBcs | Returns raw Binary Canonical Serialization bytes for client-side decoding. |
showPreviousTransaction | Returns 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 โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ 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.
{
"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.
{
"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.
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.
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.
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 code | Cause | Resolution |
|---|---|---|
notExists | The 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. |
deleted | A transaction deleted, burned, or pruned the object from the active state. | You can't retrieve historical data for deleted objects through getObject. |
invalid_param | The Object ID has a malformed 32-byte hex format. | Check that the ID starts with 0x and has the correct length. |
See alsoโ
multiGetObjectsfetches details for four objects in one batch request.getOwnedObjectslists all objects owned by a specific address.- How to fetch object data provides a tutorial that uses
getObjectin a Node.js script. - The SuiClient architecture explains the conceptual design of
SuiClientand read operations.