How to Query Owned Objects by Type Using the Sui Client

01 November 2026

To query owned objects by type with the Sui CLI, use the sui client objects command with the --type flag, specifying the full Move type signature. This returns all objects your active address owns that match that type.

Understanding object ownership and type queries

On Sui, every object has an owner, typically an address. The Sui client provides a direct way to list objects associated with your active address, filtered by their Move type. This is useful for inspecting specific assets like coins, NFTs, or custom objects defined in a package.

The type string must match the exact on-chain type, including package address and module name. For example, a Sui coin type looks like 0x2::coin::Coin<0x2::sui::SUI>, while a custom object might be 0x1234::my_module::MyObject.

Prerequisites

Before querying, ensure you have: - Installed the Sui CLI (covered in "How to Set Up a Local Sui Devnet with Sui CLI") - An active address with some objects (use sui client addresses to check) - The exact type string of the objects you want to query

Step-by-Step: query owned objects by type

1. check your active address

First, confirm which address you're querying from:

sui client active-address

This prints the currently active address. If you need to switch, use sui client switch --address <ADDRESS>.

2. List Objects Without Filtering (Optional)

To see all objects owned by your active address:

sui client objects

This returns a table with object IDs, types, and digest hashes. Review this to identify the exact type string you want to filter by.

3. Query by Type

The basic command structure is:

sui client objects --type <TYPE_STRING>

Example: query all SUI coins

For the native SUI coin:

sui client objects --type "0x2::coin::Coin<0x2::sui::SUI>"

This returns only objects matching that exact type. Note the nested angle brackets - the inner 0x2::sui::SUI is the coin type parameter.

Example: query a custom NFT

If you deployed a package with address 0xabcdef and module my_nft containing an NFT struct:

sui client objects --type "0xabcdef::my_nft::NFT"

4. handle multiple object types

You can only filter by one type per command. To query multiple types, run separate commands. Alternatively, use the --json flag to get machine-readable output, then filter programmatically:

sui client objects --json | jq '.[] | select(.type == "0x2::coin::Coin<0x2::sui::SUI>")'

This requires jq installed for JSON parsing.

Common Type Strings

Here are some frequently used type strings on Sui mainnet (package addresses may vary on testnet/devnet):

Troubleshooting

No Objects Returned

If the query returns an empty list: - Confirm the type string is correct. Copy it directly from a transaction block or package source. - Verify the objects were transferred to your active address. Use sui client objects without --type to see all owned objects. - Check if the objects are dynamic fields or wrapped in another object - those are not directly owned.

Invalid type string error

The CLI expects the exact on-chain format. Common mistakes: - Missing package address prefix (0x). - Incorrect module or struct name capitalization. - Extra spaces or missing angle brackets.

Permission or connection issues

Ensure your Sui client is configured for the correct network:

sui client envs

Switch environments with sui client switch --env <ENV_NAME>.

Querying with SDKs (Alternative Approach)

For programmatic queries, the Sui SDKs (TypeScript, Rust, Python) offer more flexible filtering. For example, in TypeScript using @mysten/sui.js:

import { SuiClient, getFullnodeUrl } from '@mysten/sui.js/client';

const client = new SuiClient({ url: getFullnodeUrl('mainnet') });
const objects = await client.getOwnedObjects({
 owner: '0xYOUR_ADDRESS',
 filter: { StructType: '0x2::coin::Coin<0x2::sui::SUI>' }
});

This returns paginated results and supports additional filters like MatchAll or MatchNone.

Performance Notes

Querying by type filters server-side, making it efficient for wallets with many objects. The CLI returns up to a default limit (typically 50 objects per call). For large collections, use the --cursor and --limit flags to paginate:

sui client objects --type "0x2::coin::Coin<0x2::sui::SUI>" --limit 100

If you need to query across all addresses, you must iterate addresses or use an indexer tool - the CLI only queries the active address.

Back to sui & aptos