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

APIリファレンス: getOwnedObjects

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

このメソッドを使用して、ウォレットのダッシュボード、ユーザーのインベントリ画面、トークン残高リストにデータを取り込むことができます。1つのアカウントが数千ものオブジェクトを保有している可能性があるため、Sui JSON-RPC APIはカーソルベースのページネーションを使用して、所有オブジェクトを個別のページ単位で返します。getOwnedObjects はフルノードのローカル状態から直接提供される読み取り操作であるため、トランザクションを送信したりガスを消費したりすることなく、即座に実行されます。

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

概要​

getOwnedObjects を呼び出すと、フルノードのインデックスに対して、対象アドレス（AddressOwner）に所有権が割り当てられているオブジェクトが照会されます。高いレイテンシやネットワークタイムアウトを回避するため、フルノードは結果を一度にすべて返すのではなく、ページ分割して返します。

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

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

シグネチャ​

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

パラメータ​

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

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

SuiObjectDataFilter​

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

フィルタキー値のタイプ説明
MatchAllSuiObjectDataFilter[]論理 AND。オブジェクトは、指定されたすべてのフィルタ条件を満たす必要があります。
MatchAnySuiObjectDataFilter[]論理 OR。オブジェクトは、指定されたフィルタ条件のいずれかを満たしていればよい。
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 の場合、この値は 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構造体のタイプでアセットをフィルタリングする​

他のトークンやNFTを除き、ユーザーが所有するSUIコインオブジェクトのみをクエリします：

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 は単一のバッチリクエストで、複数の特定のオブジェクトの詳細を取得します。
  • オブジェクトデータの取得方法 は Node.js で読み取り操作を実装するためのステップバイステップのチュートリアルを提供します。
  • SuiClientのアーキテクチャ は SuiClient および読み取り操作の概念的な設計について説明します。