メインコンテンツまでスキップ

getOwnedObjects

特定の 32 バイトの Sui ウォレットアドレスが所有するオンチェーンオブジェクトのリストを、ページ単位で取得します。

ウォレットダッシュボードへのデータ追加やユーザーインベントリの管理にこのメソッドを使用します。1つのアカウントが数千ものオブジェクトを保有する場合があります。Sui API はカーソルベースのページネーションを使用して、所有オブジェクトを個別のページで返します。JSON-RPC(JavaScript Object Notation Remote Procedure Call)から、このリクエストを Sui フルノードに送信します。getOwnedObjects はフルノードの状態を読み取り、トランザクションや gas なしですぐに実行します。呼び出し元にウォレット署名は必要ありません。

  • クラス: SuiClient
  • パッケージ: @mysten/sui/client
  • 操作タイプ: 読み取り操作
  • トランザクション: 不要
  • ガス: 不要
  • ウォレット署名: 不要

ページネーションの仕組み​

getOwnedObjects を呼び出すと、対象アドレスに割り当てられたオブジェクトをフルノードのインデックスから検索します。所有権のタイプは AddressOwner です。

フルノードは、レイテンシとネットワークタイムアウトを回避するために結果をページ分割します。インベントリ全体を1つのレスポンスで返すことはありません。

ページネーションループの可視化​

カーソルページネーションのフローチャート

シグネチャ​

シグネチャ
client.getOwnedObjects(input: GetOwnedObjectsParams): Promise<PaginatedObjectsResponse>

パラメータ​

このメソッドは、以下のプロパティを持つ設定オブジェクトを受け付けます:

パラメータタイプ必須説明
ownerstringはいターゲットウォレットの 32 バイトの 16 進数アドレス。
filterSuiObjectDataFilterいいえタイプ、パッケージ、またはモジュールによる結果のフィルタリング条件。
optionsSuiObjectDataOptionsいいえshowType、showContent、showDisplayなど、詳細情報を追加するフラグ。
cursorstring | nullいいえ次のページを取得するための、前回のレスポンスから得られた nextCursor トークン。
limitnumberいいえ1ページあたりの最大アイテム数。パブリックJSON-RPCノードでは通常、デフォルトが50で、上限も50です。

SuiObjectDataFilter​

filter パラメータはフルノードでのクエリを絞り込み、帯域幅とクライアント側の処理負荷を節約します:

フィルタキー値のタイプ説明
MatchAllSuiObjectDataFilter[]指定されたすべてのフィルター条件を満たす必要があります。
MatchAnySuiObjectDataFilter[]指定されたフィルター条件のいずれかを満たせばよい。
StructTypestring完全修飾された Move Struct 型との完全一致。たとえば、0x2::coin::Coin<0x2::sui::SUI> です。
Packagestring指定されたパッケージID内のモジュールからインスタンス化された任意のオブジェクトに一致します。
MoveModule{ package: string, module: string }パッケージ内の特定のモジュールで定義された任意のオブジェクトに一致します。

戻り値​

PaginatedObjectsResponse オブジェクトに解決される Promise を返します:

レスポンス
{
"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(`取得された SUI コインオブジェクト数: ${response.data.length}`);

所有するすべてのオブジェクトをページネーションで取得する​

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以下に設定してください。

関連項目​

  • getObject は個々のオンチェーンオブジェクトの詳細を取得します。
  • multiGetObjects は、1つのバッチリクエストで多数のオブジェクトの詳細を取得します。
  • オブジェクトデータの取得方法 は Node.js で読み取り操作を実装するためのステップバイステップのチュートリアルを提供します。
  • SuiClientのアーキテクチャ は SuiClient および読み取り操作の概念的な設計について説明します。