Saltar al contenido principal

getOwnedObjects

Recupera una lista paginada de objetos en cadena que pertenecen a una dirección de billetera Sui específica de 32 bytes.

Utiliza este método para rellenar paneles de control de billeteras y gestionar inventarios de usuarios. Una cuenta puede contener miles de objetos. La API de Sui devuelve los objetos en propiedad en páginas independientes mediante paginación basada en cursor. JSON-RPC (JavaScript Object Notation Remote Procedure Call) envía esta solicitud a un nodo completo de Sui. getOwnedObjects lee el estado del nodo completo y se ejecuta de inmediato sin una transacción ni gas. Quien llama al método no necesita una firma de la billetera.

  • Clase: SuiClient
  • Paquete: @mysten/sui/client
  • Tipo de operación: operación de lectura
  • Transacción: no requerida
  • Gas: no consumido
  • Firma de la billetera: no requerida

Cómo funciona la paginación​

Al llamar a getOwnedObjects, se consulta el índice del nodo completo para buscar los objetos asignados a la dirección de destino. El tipo de propiedad es AddressOwner.

Los nodos completos paginan los resultados para evitar una alta latencia y tiempos de espera en la red. No devuelven todo el inventario en una sola respuesta.

Visualización del bucle de paginación​

Diagrama de flujo de paginación por cursor

Firma​

Firma
client.getOwnedObjects(input: GetOwnedObjectsParams): Promise<PaginatedObjectsResponse>

Parámetros​

El método acepta un objeto de configuración con las siguientes propiedades:

ParámetroTipoRequeridoDescripción
ownerstringSíLa dirección hexadecimal de 32 bytes de la billetera de destino.
filterSuiObjectDataFilterNoCriterios para filtrar los resultados por tipo, paquete o módulo.
optionsSuiObjectDataOptionsNoIndicadores para incluir más detalles, como showType, showContent y showDisplay.
cursorstring | nullNoEl token nextCursor de una respuesta anterior para recuperar la página siguiente.
limitnumberNoMayor cantidad de elementos por página. Los nodos JSON-RPC públicos suelen usar 50 como valor predeterminado y permiten un máximo de 50.

SuiObjectDataFilter​

El parámetro filter restringe las consultas en el nodo completo, lo que ahorra ancho de banda y procesamiento del lado del cliente:

Clave de filtroTipo de valorDescripción
MatchAllSuiObjectDataFilter[]Requiere todos los criterios de filtro.
MatchAnySuiObjectDataFilter[]Requiere cualquiera de los criterios de filtro.
StructTypestringCoincidencia exacta con un tipo Move Struct completamente calificado, como 0x2::coin::Coin<0x2::sui::SUI>.
PackagestringCoincide con cualquier objeto instanciado a partir de módulos dentro del ID de paquete especificado.
MoveModule{ package: string, module: string }Coincide con cualquier objeto definido dentro de un módulo específico de un paquete.

Valor de retorno​

Devuelve una Promise que se resuelve en un objeto PaginatedObjectsResponse:

Respuesta
{
"data": [
{ "data": { "objectId": "0xA...", "version": "1", "type": "0x2::coin::Coin<0x2::sui::SUI>" } },
{ "data": { "objectId": "0xB...", "version": "4", "type": "0x2::coin::Coin<0x2::sui::SUI>" } }
],
"hasNextPage": true,
"nextCursor": "0x12345...ResultCursor"
}

La envoltura de respuesta contiene los siguientes campos:

CampoTipoDescripción
dataSuiObjectResponse[]Array de envolturas de respuesta de objetos para la página actual.
hasNextPagebooleanIndica si existen más páginas de objetos.
nextCursorstring | nullToken de paginación opaco que se pasa como cursor en la siguiente llamada. Si hasNextPage es false, nextCursor es null.

Ejemplos de uso​

Recuperar la primera página de un inventario​

Recupera los primeros 5 objetos que posee una dirección:

basicInventory.js
const response = await client.getOwnedObjects({
owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
limit: 5,
options: { showType: true }
});

response.data.forEach((item) => {
if (item.data) {
console.log(`ID: ${item.data.objectId}, Type: ${item.data.type}`);
}
});

Filtrar activos por tipo de estructura Move​

Consulta únicamente los objetos de monedas SUI que posee un usuario. SUI es la moneda nativa de la red. Excluye otros tokens y NFT:

filterCoins.js
const response = await client.getOwnedObjects({
owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
filter: {
StructType: '0x2::coin::Coin<0x2::sui::SUI>'
},
options: { showContent: true }
});

console.log(`Objetos de monedas SUI encontrados: ${response.data.length}`);

Paginación de todos los objetos que se poseen​

Utiliza un bucle while para procesar todos los objetos que pertenecen a una dirección:

pagination.js
let hasNextPage = true;
let nextCursor = null;
const allObjects = [];

while (hasNextPage) {
const response = await client.getOwnedObjects({
owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
cursor: nextCursor,
limit: 50
});

allObjects.push(...response.data);

hasNextPage = response.hasNextPage;
nextCursor = response.nextCursor;
}

console.log(`Total de objetos obtenidos: ${allObjects.length}`);

Errores comunes​

Código de errorCausaResolución
cursor_invalidLa cadena cursor caducó, tiene un formato no válido o proviene de otra consulta.Pasa la cadena exacta que devuelve nextCursor en la consulta anterior.
limit_exceededEl limit solicitado supera el límite de tamaño de página del nodo completo, que normalmente es 50.Establece limit en 50 elementos o menos.

Ver también​