Sui Clients

The Sui TypeScript SDK provides multiple client implementations for interacting with the Sui network. For application code, choose one client for your transport and use its top-level methods for common reads, writes, and queries. SuiGrpcClient is the recommended default.

The gRPC and GraphQL clients expose three useful surfaces:

• Top-level methods: the main application API, matching the Core API for common operations
• Core API: the shared client.core contract used by SDKs and libraries
• Native API: direct access to transport-specific features when the common methods are not enough

The deprecated SuiJsonRpcClient also exposes client.core, but its top-level methods retain their legacy JSON-RPC names and response shapes.

Available clients

All active Mysten SDKs are designed to accept clients that implement the Core API. SuiGrpcClient is the default choice for most apps because it uses the full node gRPC API and has the most complete top-level SDK surface. Use SuiGraphQLClient when the code needs GraphQL-specific indexed queries or a custom query shape. JSON-RPC APIs are deprecated in the Sui TypeScript SDK; migrate legacy JSON-RPC code to gRPC or GraphQL.

Quick start

import { SuiGrpcClient } from '@mysten/sui/grpc';

const client = new SuiGrpcClient({
	network: 'mainnet',
	baseUrl: 'https://fullnode.mainnet.sui.io:443',
});

const { balance } = await client.getBalance({ owner: '0x...' });
const { object } = await client.getObject({
	objectId: '0x...',
	include: { content: true },
});

Top-level, core, and native APIs

Top-level methods

Use top-level methods when writing app code against SuiGrpcClient or SuiGraphQLClient. These methods use the same option and response shapes as the Core API, and a transport can add narrowly scoped fields where it has extra native data. For SuiJsonRpcClient, use client.core for these shapes or migrate its legacy top-level calls to gRPC or GraphQL.

const { objects } = await client.listOwnedObjects({
	owner: '0x...',
	include: { display: true },
});

const result = await client.signAndExecuteTransaction({
	transaction,
	signer,
	include: { effects: true, balanceChanges: true },
});

Common top-level methods include:

Core API

Use client.core when building SDKs or libraries that accept any client implementing ClientWithCoreApi. The Core API is the shared contract that SuiGrpcClient, SuiGraphQLClient, and the deprecated SuiJsonRpcClient implement.

import type { ClientWithCoreApi } from '@mysten/sui/client';

export async function fetchResource(client: ClientWithCoreApi, objectId: string) {
	return client.core.getObject({
		objectId,
		include: { content: true },
	});
}

Native API

Each client exposes the full capabilities of its underlying transport. Use the native API when you need transport-specific features or want maximum control.

import { SuiGrpcClient } from '@mysten/sui/grpc';
import { SuiGraphQLClient } from '@mysten/sui/graphql';
import { graphql } from '@mysten/sui/graphql/schema';

const grpcClient = new SuiGrpcClient({
	network: 'mainnet',
	baseUrl: 'https://fullnode.mainnet.sui.io:443',
});

// gRPC - access various service clients to call any gRPC method
const { response } = await grpcClient.stateService.listOwnedObjects({ owner: '0x...' });

const graphqlClient = new SuiGraphQLClient({
	network: 'mainnet',
	url: 'https://graphql.mainnet.sui.io/graphql',
});

// GraphQL - write type-safe custom queries using the graphql function
const result = await graphqlClient.query({
	query: graphql(`
		query {
			chainIdentifier
		}
	`),
});

For legacy JSON-RPC-only code, see the SuiJsonRpcClient page and the JSON-RPC migration guide.

Client extensions

All clients support extensions through the $extend method, enabling SDKs like @mysten/walrus to add functionality:

import { walrus } from '@mysten/walrus';

const client = new SuiGrpcClient({ network: 'mainnet', baseUrl: '...' }).$extend(walrus());

await client.walrus.writeBlob({ ... });

See Building SDKs for more on creating client extensions.