Referencia API: getObject

Recupera los detalles de un objeto específico de la cadena de bloques.

Clase: SuiClient Tipo de método: Operación de lectura, sin gas

---

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 devuelve sólo la referencia del objeto, específicamente su ID, versión y resumen. Para recuperar los datos reales, debe establecer explícitamente estas banderas a true.

Opción	Descripción
showType	Devuelve el tipo Move, por ejemplo, 0x2::coin::Coin<SUI>.
showContent	Devuelve los campos de datos Move analizados, el estado interno del objeto.
showOwner	Devuelve la dirección o el objeto que posee este elemento.
showDisplay	Devuelve los metadatos estándar de visualización, específicamente imágenes y nombres, para la representación de la interfaz de usuario.
showStorageRebate	Devuelve el descuento de almacenamiento asociado al objeto.

---

Valor de retorno

Devuelve un Promise que resuelve a una SuiObjectResponse. Esta respuesta es una envoltura estándar que maneja los estados de éxito y error.

1. Respuesta de éxito (data)

Si el objeto existe y se mantiene la accesibilidad, la propiedad data contiene SuiObjectData.

{
  "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..." 
    }
  }
}

2. Respuesta de error (error)

Si ha eliminado el objeto, está envuelto en otro objeto, o no existe, la propiedad error contiene un valor.

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

---

Ejemplos de uso

Escenario A: Comprobar si un objeto existe

Esta es la consulta más ligera. No solicita ningún dato, sólo el digest/versión.

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);
}

Escenario B: Obtención de metadatos de tokens no fungibles

Esta solicitud pide el content para leer campos, y display para ver la dirección de la imagen.

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

const name = nft.data.content.fields.name;
const imageUrl = nft.data.display.data.image_url;

Escenario C: Verificación de la propiedad

Utilice esto para comprobar si un usuario específico posee un elemento.

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

const owner = item.data.owner;

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

---

Errores comunes

Código de error	Causa	Resolución
notExists	El ID del objeto es un hex válido, pero el objeto no se encuentra en la red.	Compruebe el ID o asegúrese de que el objeto no fue eliminado en una transacción anterior.
deleted	El objeto existía antes pero fue quemado o usted lo eliminó.	No puede obtener datos de objetos eliminados.
invalid_param	El ID de objeto proporcionado no es una cadena hexadecimal válida de 32 bytes.	Asegúrese de que el ID comienza con 0x y tiene la longitud correcta.

---

Ver también

• getMultiGetObjects**: Obtiene muchos objetos en una sola petición de red, para procesamiento por lotes.
• getOwnedObjects: Encuentra todos los objetos poseídos por una dirección específica.