Mysten Labs TypeScript SDK Docs

The SuiGrpcClient provides access to the Full Node gRPC API.

For more complete details on what is available through this API see the gRPC API docs.

Creating a gRPC client

To get started, create a SuiGrpcClient instance by specifying a network and base URL:

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

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

For local development:

const grpcClient = new SuiGrpcClient({
	network: 'localnet',
	baseUrl: 'http://127.0.0.1:9000',
});

Transport options

By default, SuiGrpcClient uses GrpcWebFetchTransport from protobuf-ts, which works in browsers and Node.js through the Fetch API. You can also provide a custom transport for advanced use cases.

The GrpcWebFetchTransport class, GrpcWebOptions type, and RpcTransport type are all re-exported from @mysten/sui/grpc for convenience.

gRPC-web transport (default)

The default transport uses the gRPC-web protocol over HTTP/1.1 or HTTP/2. You can customize it by passing GrpcWebFetchTransport options directly:

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

const transport = new GrpcWebFetchTransport({
	baseUrl: 'https://your-custom-grpc-endpoint.com',
	format: 'binary', // default is 'text' (base64-encoded)
	// Additional transport options like fetchInit
});

const grpcClient = new SuiGrpcClient({
	network: 'testnet',
	transport,
});

For server-side applications (Node.js, Bun, and others), you can use the native gRPC transport with @protobuf-ts/grpc-transport and @grpc/grpc-js. This uses HTTP/2 with the native gRPC protocol rather than the gRPC-web translation layer.

Install the required packages:

npm install @protobuf-ts/grpc-transport @grpc/grpc-js

Then create the client with a GrpcTransport:

import { SuiGrpcClient } from '@mysten/sui/grpc';
import { GrpcTransport } from '@protobuf-ts/grpc-transport';
import { ChannelCredentials } from '@grpc/grpc-js';

const transport = new GrpcTransport({
	host: 'fullnode.testnet.sui.io:443',
	channelCredentials: ChannelCredentials.createSsl(),
});

const grpcClient = new SuiGrpcClient({
	network: 'testnet',
	transport,
});

For local development without TLS:

import { GrpcTransport } from '@protobuf-ts/grpc-transport';
import { ChannelCredentials } from '@grpc/grpc-js';

const transport = new GrpcTransport({
	host: '127.0.0.1:9000',
	channelCredentials: ChannelCredentials.createInsecure(),
});

const grpcClient = new SuiGrpcClient({
	network: 'localnet',
	transport,
});

Using service clients

The SuiGrpcClient exposes several service clients for lower-level access to the gRPC API. These service clients are generated using protobuf-ts, which provides type-safe gRPC clients for TypeScript. For more details on how to use gRPC with Sui, see the gRPC overview.

With the core API

The gRPC client implements all the core API methods:

import { SuiGrpcClient } from '@mysten/sui/grpc';
const grpcClient = new SuiGrpcClient({
	network: 'testnet',
	baseUrl: 'https://fullnode.testnet.sui.io:443',
});
// Get coins owned by an address
await grpcClient.getCoins({
	owner: '<OWNER_ADDRESS>',
});

To query additional data not available in the core API, you can use the service clients directly:

Transaction execution service

const { response } = await grpcClient.transactionExecutionService.executeTransaction({
	transaction: {
		bcs: {
			value: transactionBytes,
		},
	},
	signatures: signatures.map((sig) => ({
		bcs: { value: fromBase64(sig) },
		signature: { oneofKind: undefined },
	})),
});

// IMPORTANT: Always check the transaction status
if (!response.finality?.effects?.status?.success) {
	const error = response.finality?.effects?.status?.error;
	throw new Error(`Transaction failed: ${error || 'Unknown error'}`);
}

Ledger service

// Get transaction by digest
const { response } = await grpcClient.ledgerService.getTransaction({
	digest: '0x123...',
});

// Get current epoch information
const { response: epochInfo } = await grpcClient.ledgerService.getEpoch({});

The ledger service also provides streaming listCheckpoints, listTransactions, and listEvents RPCs. For most use cases, prefer the corresponding core API query methods, which handle pagination and filter construction for you. The raw RPCs additionally support DNF filters (combined, negated, and additional predicates like affected_address and package_write) and checkpoint range bounds that the core API does not expose:

// Transactions that affected an address but were not sent by it:
const stream = grpcClient.ledgerService.listTransactions({
	filter: {
		terms: [
			{
				literals: [
					{
						negated: false,
						predicate: {
							oneofKind: 'affectedAddress',
							affectedAddress: { address: '0xabc...' },
						},
					},
					{
						negated: true,
						predicate: { oneofKind: 'sender', sender: { address: '0xabc...' } },
					},
				],
			},
		],
	},
	readMask: { paths: ['digest'] },
});

for await (const frame of stream.responses) {
	if (frame.transaction) {
		console.log(frame.transaction.digest);
	}
}

Subscription service

Subscribe to filtered, real-time streams of checkpoints, transactions, or events. Streams begin at the current tip of the chain:

const stream = grpcClient.subscriptionService.subscribeTransactions({
	filter: {
		terms: [
			{
				literals: [
					{
						negated: false,
						predicate: { oneofKind: 'sender', sender: { address: '0xabc...' } },
					},
				],
			},
		],
	},
	readMask: { paths: ['digest', 'effects.status'] },
});

for await (const frame of stream.responses) {
	if (frame.transaction) {
		console.log(frame.transaction.digest);
	}
}

State service

// List owned objects
const { response } = await grpcClient.stateService.listOwnedObjects({
	owner: '0xabc...',
	objectType: '0x2::coin::Coin<0x2::sui::SUI>',
});

// Get dynamic fields
const { response: fields } = await grpcClient.stateService.listDynamicFields({
	parent: '0x123...',
});

Move package service

// Get function information
const { response } = await grpcClient.movePackageService.getFunction({
	packageId: '0x2',
	moduleName: 'coin',
	name: 'value',
});

Name service

// Reverse lookup address to get name
const { response } = await grpcClient.nameService.reverseLookupName({
	address: '0xabc...',
});

Signature verification service

// Verify a signature
const { response } = await grpcClient.signatureVerificationService.verifySignature({
	message: {
		name: 'TransactionData',
		value: messageBytes,
	},
	signature: {
		bcs: { value: signatureBytes },
		signature: { oneofKind: undefined },
	},
	jwks: [],
});

SuiGrpcClient