# SuiGrpcClient

> Connect to Sui via gRPC with SuiGrpcClient

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](https://docs.sui.io/concepts/data-access/grpc-overview).

## Creating a gRPC client

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

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

For local development:

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

## Transport options

By default, `SuiGrpcClient` uses `GrpcWebFetchTransport` from
[protobuf-ts](https://github.com/timostamm/protobuf-ts), which works in browsers and Node.js via 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:

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

### Native gRPC transport

For server-side applications (Node.js, Bun, etc.), 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:

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

Then create the client with a `GrpcTransport`:

```typescript
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:

```typescript
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](https://github.com/timostamm/protobuf-ts), which
provides type-safe gRPC clients for TypeScript. For more details on how to use gRPC with Sui, see
the [gRPC overview](https://docs.sui.io/concepts/data-access/grpc-overview).

### With the core API

The gRPC client implements all the [`core`](./core) API methods:

```typescript
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

```typescript
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

```typescript
// 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

```typescript
// 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

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

### Name Service

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

### Signature Verification Service

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