跳到主要内容

getOwnedObjects

检索由特定 32 字节 Sui 钱包地址拥有的链上对象的分页列表。

使用此方法可填充钱包仪表盘并管理用户库存。一个账户可以持有数千个对象。Sui API 会通过基于游标的分页机制,分页返回拥有的对象。JSON-RPC(JavaScript Object Notation Remote Procedure Call)会将此请求发送到 Sui 全节点。getOwnedObjects 会读取全节点状态并立即运行,无需交易或 gas。调用方无需钱包签名。

  • 类: SuiClient
  • 包: @mysten/sui/client
  • 操作类型: 读取操作
  • 交易: 无需交易
  • Gas: 不消耗
  • 钱包签名: 无需签名

分页机制​

调用 getOwnedObjects 会查询全节点索引,查找分配给目标地址的对象。所有权类型为 AddressOwner。

全节点会分页返回结果,以避免高延迟和网络超时。它不会在一次响应中返回全部库存。

分页循环可视化​

游标分页流程图

签名​

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

参数​

该方法接受一个包含以下属性的配置对象:

参数类型必填描述
ownerstring是目标钱包的 32 字节十六进制地址。
filterSuiObjectDataFilter否按类型、包或模块过滤结果的条件。
optionsSuiObjectDataOptions否包含更多详细信息的标志,例如 showType、showContent 和 showDisplay。
cursorstring | null否来自先前响应的 nextCursor 令牌,用于获取后续页面。
limitnumber否每页的最大条目数。公共 JSON-RPC 节点通常默认返回 50 个,并且最多允许返回 50 个。

SuiObjectDataFilter​

filter 参数可缩小全节点上的查询范围,从而节省带宽并减少客户端处理负担:

过滤键值类型描述
MatchAllSuiObjectDataFilter[]要求满足所有筛选条件。
MatchAnySuiObjectDataFilter[]要求满足任一筛选条件。
StructTypestring完全限定的 Move Struct 类型的精确匹配,例如 0x2::coin::Coin<0x2::sui::SUI>。
Packagestring匹配从指定包 ID 内的模块实例化的任何对象。
MoveModule{ package: string, module: string }匹配包中特定模块内定义的任何对象。

返回值​

返回一个 Promise,该 Promise 解析为 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"
}

响应封装体包含以下字段:

字段类型描述
dataSuiObjectResponse[]当前页面的对象响应封装体数组。
hasNextPageboolean指示是否存在更多对象页面。
nextCursorstring | null作为下次调用中 cursor 参数的不透明分页令牌。如果 hasNextPage 为 false,则 nextCursor 为 null。

代码示例​

获取资产列表的第一页​

检索某个地址拥有的前 5 个对象:

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}`);
}
});

按 Move 结构类型过滤资产​

仅查询用户拥有的 SUI 代币对象。SUI 是网络的原生代币。排除其他代币和 NFT:

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

console.log(`找到 ${response.data.length} 个 SUI 代币对象`);

分页遍历所有拥有的对象​

使用 while 循环处理属于某个地址的所有对象:

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

常见错误​

错误代码原因解决方法
cursor_invalidcursor 字符串已过期、格式无效,或者来自其他查询。传入前一次查询中 nextCursor 返回的准确字符串。
limit_exceeded请求的 limit 超出全节点的页面大小限制,通常为 50。将 limit 设置为 50 或更少。

另请参阅​