getOwnedObjects
特定の 32 バイトの Sui ウォレットアドレスが所有するオンチェーンオブジェクトのリストを、ページ単位で取得します。
ウォレットダッシュボードへのデータ追加やユーザーインベントリの管理にこのメソッドを使用します。1つのアカウントが数千ものオブジェクトを保有する場合があります。Sui API はカーソルベースのページネーションを使用して、所有オブジェクトを個別のページで返します。JSON-RPC(JavaScript Object Notation Remote Procedure Call)から、このリクエストを Sui フルノードに送信します。getOwnedObjects はフルノードの状態を読み取り、トランザクションや gas なしですぐに実行します。呼び出し元にウォレット署名は必要ありません。
- クラス:
SuiClient - パッケージ:
@mysten/sui/client - 操作タイプ: 読み取り操作
- トランザクション: 不要
- ガス: 不要
- ウォレット署名: 不要
ページネーションの仕組み
getOwnedObjects を呼び出すと、対象アドレスに割り当てられたオブジェクトをフルノードのインデックスから検索します。所有権のタイプは AddressOwner です。
フルノードは、レイテンシとネットワークタイムアウトを回避するために結果をページ分割します。インベントリ全体を1つのレスポンスで返すことはありません。
ページネーションループの可視化
- Mermaid (画像)
- Mermaid (コード)
- ASCII
flowchart TD
Start([ページネーションを開始]) --> Init["cursor = null を初期化<br/>allObjects = []"]
Init --> Query["getOwnedObjects を呼び出す<br/>(cursor, limit: 50)"]
Query --> Resp["応答を受信:<br/>data[], hasNextPage, nextCursor"]
Resp --> Append["allObjects 配列に<br/>項目を追加"]
Append --> Check{"hasNextPage == true?"}
Check -->|はい| Update["cursor = nextCursor に更新"]
Check -->|いいえ| Done([蓄積されたすべてのオブジェクトを返す])
Update -.->|次のページ| Query
ページネーションの流れ(カーソルループ):
クライアント フルノード
│ │
│── getOwnedObjects(cursor: null) ──────────►│ (ページ 1:limit 50)
│◄── { data: [50 items], nextCursor } ───────│
│ │
│── getOwnedObjects(cursor: nextCursor) ────►│ (ページ 2:limit 50)
│◄── { data: [12 items], hasNextPage: false }
シグネチャ
client.getOwnedObjects(input: GetOwnedObjectsParams): Promise<PaginatedObjectsResponse>
パラメータ
このメソッドは、以下のプロパティを持つ設定オブジェクトを受け付けます:
| パラメータ | タイプ | 必須 | 説明 |
|---|---|---|---|
owner | string | はい | ターゲットウォレットの 32 バイトの 16 進数アドレス。 |
filter | SuiObjectDataFilter | いいえ | タイプ、パッケージ、またはモジュールによる結果のフィルタリング条件。 |
options | SuiObjectDataOptions | いいえ | showType、showContent、showDisplayなど、詳細情報を追加するフラグ。 |
cursor | string | null | いいえ | 次のページを取得するための、前回のレスポンスから得られた nextCursor トークン。 |
limit | number | いいえ | 1ページあたりの最大アイテム数。パブリックJSON-RPCノードでは通常、デフォルトが50で、上限も50です。 |
SuiObjectDataFilter
filter パラメータはフルノードでのクエリを絞り込み、帯域幅とクライアント側の処理負荷を節約します:
| フィルタキー | 値のタイプ | 説明 |
|---|---|---|
MatchAll | SuiObjectDataFilter[] | 指定されたすべてのフィルター条件を満たす必要があります。 |
MatchAny | SuiObjectDataFilter[] | 指定されたフィルター条件のいずれかを満たせばよい。 |
StructType | string | 完全修飾された Move Struct 型との完全一致。たとえば、0x2::coin::Coin<0x2::sui::SUI> です。 |
Package | string | 指定されたパッケージ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"
}
レスポンスエンベロープには、以下のフィールドが含まれます:
| フィールド | タイプ | 説明 |
|---|---|---|
data | SuiObjectResponse[] | 現在のページに対するオブジェクトレスポンスエンベロープの配列。 |
hasNextPage | boolean | オブジェクトの次のページが存在するかどうかを示します。 |
nextCursor | string | null | 次の呼び出しで cursor として渡す不透明なページネーショントークン。hasNextPage が false の場合、nextCursor は null になります。 |
使用例
インベントリの最初のページを取得する
アドレスが所有する最初の5つのオブジェクトを取得します:
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を除外します:
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 ループを使用して、アドレスに属するすべてのオブジェクトを処理します:
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_invalid | cursor 文字列の有効期限が切れているか、形式が無効か、別のクエリから取得されたものです。 | 前のクエリで nextCursor が返した文字列を正確に渡してください。 |
limit_exceeded | 指定した limit がフルノードのページサイズ上限(通常50)を超えています。 | limit を50以下に設定してください。 |
関連項目
getObjectは個々のオンチェーンオブジェクトの詳細を取得します。multiGetObjectsは、1つのバッチリクエストで多数のオブジェクトの詳細を取得します。- オブジェクトデータの取得方法 は Node.js で読み取り操作を実装するためのステップバイステップのチュートリアルを提供します。
- SuiClientのアーキテクチャ は
SuiClientおよび読み取り操作の概念的な設計について説明します。