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
- Mermaid (imagen)
- Mermaid (código)
- ASCII
flowchart TD
Start([Iniciar paginación]) --> Init["Inicializar cursor = null<br/>allObjects = []"]
Init --> Query["Llamar a getOwnedObjects<br/>(cursor, limit: 50)"]
Query --> Resp["Recibir respuesta:<br/>data[], hasNextPage, nextCursor"]
Resp --> Append["Añadir elementos al<br/>array allObjects"]
Append --> Check{"¿hasNextPage == true?"}
Check -->|Sí| Update["Actualizar cursor = nextCursor"]
Check -->|No| Done([Devolver todos los objetos acumulados])
Update -.->|Página siguiente| Query
Flujo de paginación (bucle de cursor):
Cliente Nodo completo
│ │
│── getOwnedObjects(cursor: null) ──────────►│ (Página 1: límite 50)
│◄── { data: [50 items], nextCursor } ───────│
│ │
│── getOwnedObjects(cursor: nextCursor) ────►│ (Página 2: límite 50)
│◄── { data: [12 items], hasNextPage: false }
Firma
client.getOwnedObjects(input: GetOwnedObjectsParams): Promise<PaginatedObjectsResponse>
Parámetros
El método acepta un objeto de configuración con las siguientes propiedades:
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
owner | string | Sí | La dirección hexadecimal de 32 bytes de la billetera de destino. |
filter | SuiObjectDataFilter | No | Criterios para filtrar los resultados por tipo, paquete o módulo. |
options | SuiObjectDataOptions | No | Indicadores para incluir más detalles, como showType, showContent y showDisplay. |
cursor | string | null | No | El token nextCursor de una respuesta anterior para recuperar la página siguiente. |
limit | number | No | Mayor 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 filtro | Tipo de valor | Descripción |
|---|---|---|
MatchAll | SuiObjectDataFilter[] | Requiere todos los criterios de filtro. |
MatchAny | SuiObjectDataFilter[] | Requiere cualquiera de los criterios de filtro. |
StructType | string | Coincidencia exacta con un tipo Move Struct completamente calificado, como 0x2::coin::Coin<0x2::sui::SUI>. |
Package | string | Coincide 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:
{
"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:
| Campo | Tipo | Descripción |
|---|---|---|
data | SuiObjectResponse[] | Array de envolturas de respuesta de objetos para la página actual. |
hasNextPage | boolean | Indica si existen más páginas de objetos. |
nextCursor | string | null | Token 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:
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:
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:
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 error | Causa | Resolución |
|---|---|---|
cursor_invalid | La 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_exceeded | El 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
getObjectrecupera detalles de un objeto individual en la cadena.multiGetObjectsrecupera detalles de muchos objetos en una sola solicitud por lotes.- Cómo obtener datos de objetos ofrece un tutorial paso a paso para implementar operaciones de lectura en Node.js.
- La arquitectura de SuiClient explica el diseño conceptual de
SuiClienty las operaciones de lectura.