Skip to main content

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โ€‹

Cursor pagination flowchart

Signatureโ€‹

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

Parametersโ€‹

The method accepts a configuration object with the following properties:

ParameterTypeRequiredDescription
ownerstringYesThe 32-byte hexadecimal address of the target wallet.
filterSuiObjectDataFilterNoCriteria to filter results by type, package, or module.
optionsSuiObjectDataOptionsNoFlags to include more details, such as showType, showContent, and showDisplay.
cursorstring | nullNoThe nextCursor token from a previous response to fetch the next page.
limitnumberNoLargest 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 KeyValue TypeDescription
MatchAllSuiObjectDataFilter[]Require every filter criterion.
MatchAnySuiObjectDataFilter[]Require any filter criterion.
StructTypestringExact match for a fully qualified Move Struct type, such as 0x2::coin::Coin<0x2::sui::SUI>.
PackagestringMatches 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:

Response
{
"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:

FieldTypeDescription
dataSuiObjectResponse[]Array of object response envelopes for the current page.
hasNextPagebooleanIndicates whether more pages of objects exist.
nextCursorstring | nullOpaque 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:

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}`);
}
});

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:

filterCoins.js
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:

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(`Total objects fetched: ${allObjects.length}`);

Common errorsโ€‹

Error codeCauseResolution
cursor_invalidThe cursor string expired, has an invalid format, or comes from another query.Pass the exact string that nextCursor returns from the preceding query.
limit_exceededThe requested limit exceeds the fullnode page size limit, which is typically 50.Set limit to 50 or fewer items.

See alsoโ€‹