跳到主要内容

API 参考：getOwnedObjects

获取由特定地址拥有的对象列表。

类： SuiClient 方法类型： 读取操作，不消耗 gas

概述​

此方法用于填充“资产”或“钱包”界面。由于一个地址可能拥有数千个对象，因此该方法会分页显示结果。

签名​

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

参数​

参数类型必填描述
ownerstring是要查询的钱包的 32 字节地址。
filterSuiObjectDataFilter否按类型或包过滤结果，详见下文。
optionsSuiObjectDataOptions否用于包含详细信息的标志，例如 showType。
cursorstring否来自先前响应的 nextCursor，用于分页。
limitnumber否返回的最大项目数，默认：50。

SuiObjectDataFilter​

filter 参数提供了强大的过滤功能。它允许您提出具体查询，例如 “仅显示金币”，而无需下载用户的整个库存。

过滤键值类型描述
MatchAllFilter[]逻辑“且”。对象必须满足所有给定的筛选条件。
MatchAnyFilter[]逻辑或。对象可以匹配任何提供的过滤条件。
StructTypestring与 Move Struct 类型的精确匹配，例如 0x2::sui::SUI。
Packagestring匹配特定 Package ID 中定义的任何对象。

返回值​

返回一个 PaginatedObjectsResponse。

{
  "data": [
    { "data": { "objectId": "0xA...", "type": "..." } },
    { "data": { "objectId": "0xB...", "type": "..." } }
  ],
  "hasNextPage": true,
  "nextCursor": "0x12345...ResultCursor"
}
  • data：此数组包含本页的对象。
  • hasNextPage：如果还有更多对象待获取，则返回 true。
  • nextCursor：您必须在 下一次 调用中将其作为 cursor 参数传递，以获取下一页。

使用示例​

场景 A：基础资产查询，第一页​

获取某个地址拥有的前 5 个对象.

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

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

场景 B：筛选特定资产​

仅获取用户拥有的“Sui DevNet 非同质化代币”，忽略其代币和其他项目。

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

场景 C：完整分页，获取全部数据​

使用 while 循环逐页获取账户拥有的所有对象。

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(`共获取对象数：${allObjects.length}`);

常见错误​

错误代码原因解决方法
cursor_invalid传递给 cursor 的字符串无效，或来自其他查询。请确保传递与 上一次 调用中 nextCursor 返回的字符串完全一致。
limit_exceeded如果您请求的限制超过节点允许的范围，例如 1000。降低限制。标准最大值通常为 50。

参见​