Referencia API: getOwnedObjects

Obtiene una lista de objetos pertenecientes a una dirección específica.

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

---

Resumen

Este método rellena las pantallas de "Inventario" o "Cartera". Dado que una dirección puede poseer miles de objetos, este método pagina los resultados.

Firma

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

Parámetros

Parámetro	Tipo	Requerido	Descripción
owner	string	Sí	La dirección de 32 bytes del monedero a comprobar.
filter	SuiObjectDataFilter	No	Filtrar resultados por tipo o paquete, ver más abajo.
options	SuiObjectDataOptions	No	Banderas para incluir detalles, por ejemplo, showType.
cursor	string	No	El nextCursor de una respuesta anterior, para paginación.
limit	number	No	Máximo de elementos a devolver, por defecto: 50.

SuiObjectDataFilter

El parámetro filter ofrece un potente filtrado. Te permite hacer preguntas específicas como "Muéstrame sólo las Monedas" en lugar de descargar todo el inventario del usuario.

Clave del Filtro	Tipo de Valor	Descripción
MatchAll	Filter[]	AND lógico. El objeto debe coincidir con todos los filtros proporcionados.
MatchAny	Filter[]	OR lógico. El objeto puede coincidir con cualquier filtro proporcionado.
StructType	string	Coincidencia exacta para un tipo de Move Struct, por ejemplo, 0x2::sui::SUI.
Package	string	Coincide con cualquier objeto definido en un Package ID específico.

---

Valor de retorno

Devuelve un PaginatedObjectsResponse.

{
  "data": [
    { "data": { "objectId": "0xA...", "type": "..." } },
    { "data": { "objectId": "0xB...", "type": "..." } }
  ],
  "hasNextPage": true,
  "nextCursor": "0x12345...ResultCursor"
}

• data: Este array contiene los objetos de esta página.
• hasNextPage: true si hay más objetos que recuperar.
• nextCursor: La cadena que debes pasar al parámetro cursor en tu llamada next para obtener la siguiente página.

---

Ejemplos de uso

Escenario A: Obtención de inventario básico, primera página

Obtener los 5 primeros objetos propiedad de una dirección.

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

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

Escenario B: Filtrado de activos específicos

Obtener sólo los "Sui DevNet Non-Fungible Tokens" propiedad de un usuario, ignorando sus monedas y otros objetos.

const response = await client.getOwnedObjects({
    owner: '0xMyAddress...',
    filter: {
        StructType: '0x2::devnet_nft::DevNetNFT'
    },
    options: { showContent: true }
});

Escenario C: Paginación completa, obteniendo todo

Utiliza un bucle while para obtener todos los objetos de una cuenta, página por página.

let hasNextPage = true;
let nextCursor = null;
const allObjects = [];

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

    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 pasada a cursor no es válida o proviene de una consulta diferente.	Asegúrate de pasar la cadena exacta devuelta en nextCursor de la llamada anterior.

| limit_exceeded | Si solicitas un límite superior al permitido por el nodo, por ejemplo, 1000, reduce tu límite. El máximo estándar suele ser 50. |

---

Ver también

• getObject: Obtener un único objeto por su ID.
• multiGetObjects**: Obtiene muchos objetos por sus IDs en una sola solicitud.