Saltar al contenido principal

Referencia de la API: getOwnedObjects

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

Utiliza este método para rellenar paneles de control de monederos, pantallas de inventario de usuarios y listas de saldos de tokens. Dado que una sola cuenta puede contener miles de objetos, la API JSON-RPC de Sui devuelve los objetos en propiedad en páginas separadas mediante paginación basada en cursor. Como getOwnedObjects es una operación de lectura que se realiza directamente desde el estado local del nodo completo, se ejecuta de forma inmediata sin 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 monedero)

Resumen​

Al llamar a getOwnedObjects se consulta el índice del nodo completo en busca de objetos cuya propiedad esté asignada a la dirección de destino (AddressOwner). Para evitar una alta latencia y tiempos de espera de red, los nodos completos paginan los resultados en lugar de devolver todo el inventario en una única 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 cartera de destino.
filterSuiObjectDataFilterNoCriterios para filtrar los resultados por tipo, paquete o módulo.
optionsSuiObjectDataOptionsNoIndicadores para incluir detalles adicionales (por ejemplo, showType, showContent, showDisplay).
cursorstring | nullNoEl token nextCursor de una respuesta anterior para recuperar la página siguiente.
limitnumberNoNúmero máximo de elementos que se pueden devolver por página (el valor por defecto y el máximo suele ser 50 en los nodos RPC públicos).

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[]Y lógico. Un objeto debe cumplir todos los criterios de filtro proporcionados.
MatchAnySuiObjectDataFilter[]O lógico. Un objeto puede cumplir cualquiera de los criterios de filtro proporcionados.
StructTypestringCoincidencia exacta con un tipo Move Struct completamente calificado (por ejemplo, 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[]Matriz de envolturas de respuesta de objetos para la página actual.
hasNextPagebooleanIndica si existen páginas adicionales de objetos.
nextCursorstring | nullToken de paginación opaco para pasar como cursor en la siguiente llamada. Cuando hasNextPage es false, este valor 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, excluyendo 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 recorrer todos los objetos que posee 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 pasada a cursor ha caducado, tiene un formato incorrecto o procede de una consulta diferente.Pasa la cadena exacta devuelta en nextCursor de la consulta anterior.
limit_exceededEl límite solicitado supera el tamaño máximo de página permitido por el nodo completo (normalmente 50).Reduce el parámetro de limit a 50 elementos o menos.

Véase también​