getOwnedObjects
Retrieves a paginated list of on-chain objects owned by a specific 32-byte Sui wallet address.
Use this method to populate wallet dashboards and manage user inventories. An account can hold thousands of objects. The Sui API returns owned objects in discrete pages with cursor-based pagination. JSON-RPC (JavaScript Object Notation Remote Procedure Call) sends this request to a Sui fullnode. getOwnedObjects reads from fullnode state and runs immediately without a transaction or gas. Callers don't need a wallet signature.
- Class:
SuiClient - Package:
@mysten/sui/client - Operation type: read operation
- Transaction: not required
- Gas: not consumed
- Wallet signature: not required
How pagination worksโ
Calling getOwnedObjects queries the fullnode index for objects assigned to the target address. The ownership type is AddressOwner.
Fullnodes paginate results to avoid high latency and network timeouts. They don't return the entire inventory in one response.
Visualizing the pagination loopโ
- Mermaid (image)
- Mermaid (code)
- ASCII
flowchart TD
Start([Start Pagination]) --> Init["Initialize cursor = null<br/>allObjects = []"]
Init --> Query["Call getOwnedObjects<br/>(cursor, limit: 50)"]
Query --> Resp["Receive response:<br/>data[], hasNextPage, nextCursor"]
Resp --> Append["Append items to<br/>allObjects array"]
Append --> Check{"hasNextPage == true?"}
Check -->|Yes| Update["Update cursor = nextCursor"]
Check -->|No| Done([Return all accumulated objects])
Update -.->|Next page| Query
Pagination Flow (Cursor Loop):
Client Fullnode
โ โ
โโโ getOwnedObjects(cursor: null) โโโโโโโโบโ (Page 1: limit 50)
โโโโ { data: [50 items], nextCursor } โโโโโ
โ โ
โโโ getOwnedObjects(cursor: nextCursor) โโบโ (Page 2: limit 50)
โโโโ { data: [12 items], hasNextPage: false }
Signatureโ
client.getOwnedObjects(input: GetOwnedObjectsParams): Promise<PaginatedObjectsResponse>
Parametersโ
The method accepts a configuration object with the following properties:
| Parameter | Type | Required | Description |
|---|---|---|---|
owner | string | Yes | The 32-byte hexadecimal address of the target wallet. |
filter | SuiObjectDataFilter | No | Criteria to filter results by type, package, or module. |
options | SuiObjectDataOptions | No | Flags to include more details, such as showType, showContent, and showDisplay. |
cursor | string | null | No | The nextCursor token from a previous response to fetch the next page. |
limit | number | No | Largest item count per page. Public JSON-RPC nodes typically default to 50 and allow no more than 50. |
SuiObjectDataFilterโ
The filter parameter narrows queries on the fullnode, saving bandwidth and client-side processing:
| Filter Key | Value Type | Description |
|---|---|---|
MatchAll | SuiObjectDataFilter[] | Require every filter criterion. |
MatchAny | SuiObjectDataFilter[] | Require any filter criterion. |
StructType | string | Exact match for a fully qualified Move Struct type, such as 0x2::coin::Coin<0x2::sui::SUI>. |
Package | string | Matches any object instantiated from modules within the specified package ID. |
MoveModule | { package: string, module: string } | Matches any object defined within a specific module of a package. |
Return valueโ
Returns a Promise that resolves to a PaginatedObjectsResponse object:
{
"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"
}
The response envelope contains the following fields:
| Field | Type | Description |
|---|---|---|
data | SuiObjectResponse[] | Array of object response envelopes for the current page. |
hasNextPage | boolean | Indicates whether more pages of objects exist. |
nextCursor | string | null | Opaque pagination token to pass as cursor in the next call. If hasNextPage is false, nextCursor is null. |
Usage examplesโ
Fetch the first page of an inventoryโ
Retrieve the first 5 objects owned by an address:
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}`);
}
});
Filter assets by Move struct typeโ
Query only SUI coin objects owned by a user. SUI is the network's native coin. Exclude other tokens and NFTs:
const response = await client.getOwnedObjects({
owner: '0x0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef',
filter: {
StructType: '0x2::coin::Coin<0x2::sui::SUI>'
},
options: { showContent: true }
});
console.log(`Found ${response.data.length} SUI coin objects`);
Paginate through all owned objectsโ
Use a while loop to process all objects that belong to an address:
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(`Total objects fetched: ${allObjects.length}`);
Common errorsโ
| Error code | Cause | Resolution |
|---|---|---|
cursor_invalid | The cursor string expired, has an invalid format, or comes from another query. | Pass the exact string that nextCursor returns from the preceding query. |
limit_exceeded | The requested limit exceeds the fullnode page size limit, which is typically 50. | Set limit to 50 or fewer items. |
See alsoโ
getObjectretrieves details for an individual on-chain object.multiGetObjectsfetches details for many objects in one batch request.- How to fetch object data provides a step-by-step tutorial for using read operations in Node.js.
- The SuiClient architecture explains the conceptual design of
SuiClientand read operations.