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

API リファレンス: getOwnedObjects

特定のアドレスが所有するオブジェクトのリストを取得します。

クラス: SuiClient メソッドタイプ: 読み取り操作、ガス代不要

概要​

このメソッドは、「インベントリ（持ち物）」や「ウォレット」画面を表示するために使用されます。1 つのアドレスが数千のオブジェクトを所有する可能性があるため、このメソッドは結果を**ページ分割（パジネーション）**して返します。

シグネチャ​

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

パラメーター​

パラメータータイプ必須説明
ownerstringはい確認するウォレットの 32 バイトのアドレス。
filterSuiObjectDataFilterいいえタイプまたはパッケージで結果をフィルタリングします（詳細は以下を参照）。
optionsSuiObjectDataOptionsいいえshowType などの詳細を含めるためのフラグ。
cursorstringいいえ前回のレスポンスからの nextCursor（ページ分割用）。
limitnumberいいえ返すアイテムの最大数。デフォルトは 50 です。

SuiObjectDataFilter​

filter パラメーターは強力なフィルタリング機能を提供します。ユーザーのインベントリ全体をダウンロードする代わりに、「コインのみを表示する」といった特定の条件を指定できます。

フィルターキー値のタイプ説明
MatchAllFilter[]論理積 (AND)。オブジェクトは提供されたすべてのフィルターに一致する必要があります。
MatchAnyFilter[]論理和 (OR)。オブジェクトは提供されたいずれかのフィルターに一致すれば十分です。
StructTypestringMove Struct タイプ（例: 0x2::sui::SUI）との完全一致。
Packagestring特定のパッケージ 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}, タイプ: ${item.data.type}`);
});

シナリオ B: 特定のアセットのフィルタリング​

ユーザーが所有するコインやその他のアイテムを無視して、「Sui DevNet NFT」のみを取得します。

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_invalidcursor に渡された文字列が無効であるか、別のクエリのものです。前回の呼び出しで nextCursor に返された文字列をそのまま渡しているか確認してください。
limit_exceededノードが許可する制限（例: 1000）より高い制限をリクエストした場合。制限を下げてください。標準的な最大値は通常 50 です。

関連項目​

  • getObject: ID で単一のオブジェクトを取得します。
  • multiGetObjects: 1 回のリクエストで、ID を指定して複数のオブジェクトを取得します。