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',
});

You can also provide a custom transport for advanced use cases:

import { SuiGrpcClient } from '@mysten/sui/grpc';
import { GrpcWebFetchTransport } from '@protobuf-ts/grpcweb-transport';

const transport = new GrpcWebFetchTransport({
	baseUrl: 'https://your-custom-grpc-endpoint.com',
	// Additional transport options
});

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

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({});

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: 'transfer',
});

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