Referencia API: getObject

Recupera los detalles y metadatos en cadena de un objeto Sui individual mediante su ID de objeto hexadecimal de 32 bytes.

Utiliza este método para consultar definiciones de paquetes Move, inspeccionar campos de estructuras y verificar la propiedad de los objetos. También puedes comprobar si una transacción ha modificado o eliminado un objeto. Dado que getObject es una operación de lectura que se realiza directamente desde el estado local del nodo completo, se ejecuta de forma inmediata sin necesidad de enviar una transacción ni consumir gas.

• Clase: SuiClient
• Paquete: @mysten/sui/client
• Tipo de operación: operación de lectura (sin gas, sin firma de billetera)

---

Firma

Firma

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

Parámetros

El método acepta un único objeto de configuración que contiene las siguientes propiedades:

Parámetro	Tipo	Requerido	Descripción
id	string	Sí	El ID de objeto hexadecimal de 32 bytes, por ejemplo, 0x123....
options	SuiObjectDataOptions	No	Banderas de configuración para activar campos de datos específicos en la respuesta. Por defecto es false para todos los campos.

SuiObjectDataOptions

Por defecto, getObject solo devuelve la referencia del objeto, concretamente su ID, versión y resumen. Para recuperar los datos reales, debes establecer explícitamente estas banderas en true.

Opción	Descripción
showType	Devuelve el tipo Move; por ejemplo, 0x2::coin::Coin<0x2::sui::SUI>.
showContent	Devuelve los campos de datos Move analizados, que representan el estado interno del objeto.
showOwner	Devuelve la dirección o el objeto propietario de este elemento.
showDisplay	Devuelve los metadatos estándar de visualización (nombres, descripciones, URL de imágenes) para la representación en la interfaz de usuario.
showStorageRebate	Devuelve el descuento de almacenamiento asociado al objeto.
showBcs	Devuelve bytes sin procesar en formato BCS (Binary Canonical Serialization) para la decodificación en el lado del cliente.
showPreviousTransaction	Devuelve el resumen de la última transacción que modificó este objeto.

---

Valor de retorno

Devuelve una Promise que se resuelve en un SuiObjectResponse. Esta respuesta es una envoltura estándar que encapsula tanto los estados de éxito como los de error:

Envoltura SuiObjectResponse

┌─────────────────────────────────────────────────────────────┐
│                     SuiObjectResponse                       │
├──────────────────────────────┬──────────────────────────────┤
│   Éxito: `response.data`     │    Error: `response.error`   │
│   - objectId, version        │    - code: "notExists"       │
│   - type, digest             │    - code: "deleted"         │
│   - content, owner, display  │    - object_id               │
└──────────────────────────────┴──────────────────────────────┘

Respuesta de éxito (data)

Cuando el objeto existe y sigue siendo accesible, la propiedad data contiene un objeto SuiObjectData.

Respuesta: éxito

{
  "data": {
    "objectId": "0x...",
    "version": "10",
    "digest": "...",
    "type": "0x2::coin::Coin<0x2::sui::SUI>", // Presente si showType: true
    "content": {                              // Presente si showContent: true
       "dataType": "moveObject",
       "fields": { "balance": "1000000000" }
    },
    "owner": {                                // Presente si showOwner: true
       "AddressOwner": "0xabc..." 
    }
  }
}

Respuesta de error (error)

Si una transacción ha eliminado el objeto, lo ha envuelto en otro objeto o el ID no existe, la propiedad error devuelve los detalles del error.

Respuesta: error

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

---

Ejemplos de uso

Comprobar si un objeto existe

Esta es la consulta más ligera. No solicita ningún campo de datos, solo el resumen y el número de versión.

checkExists.js

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

if (response.error) {
    console.log("El objeto no existe.");
} else {
    console.log("El objeto existe en la versión:", response.data.version);
}

Obtener metadatos de NFT y campos de visualización

Esta solicitud pide content para leer campos en la cadena y display para recuperar los recursos de representación de la interfaz de usuario.

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(`Nombre del NFT: ${name}, Imagen: ${imageUrl}`);
} else {
    console.warn("Error al cargar el elemento:", nft.error);
}

Verificar la propiedad del objeto

Utiliza esto para comprobar si una dirección de cuenta específica es propietaria de un elemento.

verifyOwnership.js

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

const owner = item.data?.owner;

if (owner && owner.AddressOwner === '0xMyAddress...') {
    console.log("Eres el propietario de este artículo.");
}

---

Errores comunes

Código de error	Causa	Resolución
notExists	El ID del objeto es un valor hexadecimal válido, pero la red no puede localizar el objeto.	Verifica el ID o confirma que una transacción anterior no haya eliminado el objeto.
deleted	Una transacción ha eliminado, quemado o podado el objeto del estado activo.	No es posible recuperar datos históricos de objetos eliminados mediante getObject.
invalid_param	El ID de objeto proporcionado no es una cadena hexadecimal válida de 32 bytes.	Asegúrate de que el ID comience por 0x y tenga la longitud correcta.

---

Ver también

• multiGetObjects recupera los detalles de varios objetos en una única solicitud por lotes.
• getOwnedObjects enumera todos los objetos que pertenecen a una dirección específica.
• Cómo obtener datos de objetos proporciona un tutorial paso a paso que implementa getObject en un script de Node.js.
• La arquitectura de SuiClient explica el diseño conceptual de SuiClient y las operaciones de lectura.