> For the complete documentation index, see [llms.txt](https://docs.triton.one/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.triton.one/sui/grpc.md).

# Sui gRPC

The Sui gRPC API, with endpoints, authentication, available services, and grpcurl examples.

The Sui gRPC API is a fast, type-safe, and efficient interface for interacting with the Sui blockchain. It replaces the deprecated JSON-RPC protocol. gRPC uses [Protocol Buffers](https://protobuf.dev/overview/) for compact, high-performance data serialisation, and supports both standard request-response calls and real-time server-side streaming, no polling required.

{% hint style="warning" %}
Triton no longer serves Sui JSON-RPC. Sui 1.82 removes the JSON-RPC service from the Sui full node, and Triton runs Sui 1.82 or later on mainnet and testnet. Move JSON-RPC integrations to gRPC, or to [GraphQL](/sui/graphql.md) on mainnet shared endpoints.
{% endhint %}

## When to use gRPC

gRPC is the best choice when you need:

* **High-performance, low-latency** point lookups for transactions, objects, and checkpoints
* **Real-time streaming** subscriptions (replaces deprecated WebSocket support)
* **Strongly typed clients** generated from `.proto` definitions in TypeScript, Go, Rust, and other languages
* **Scalable backend systems**: indexers, exchanges, bots, and dashboards

For frontends, developer tooling, or flexible filtered historical queries, consider [GraphQL](/sui/graphql.md) as an alternative.

{% hint style="warning" %}
gRPC full nodes do not automatically fall back to the [Archival service](/sui/archival.md) for historical data. If your integration requires deep historical lookups, use the Archival service endpoint directly.
{% endhint %}

***

## Endpoints

| Endpoint                                                                | Address                                         | Authentication                      |
| ----------------------------------------------------------------------- | ----------------------------------------------- | ----------------------------------- |
| **Free test** (mainnet, rate-limited)                                   | `mainnet.sui.rpcpool.com:443`                   | No authentication token is required |
| **Shared infrastructure**                                               | `<your-endpoint>.<network>.sui.rpcpool.com:443` | Required via the `X-Token` header   |
| **Dedicated nodes** (private endpoint, provisioned exclusively for you) | `<your-endpoint>.sui.rpcpool.com:443`           | Required via the `X-Token` header   |

`<network>` is `mainnet` or `testnet`. Copy your exact hostname and token from the [customer dashboard](https://customers.triton.one/).

{% hint style="warning" %}
We provide a free shared gRPC endpoint for testing and evaluation purposes. It is strictly rate-limited and intended for development use only, **not for production traffic**.
{% endhint %}

***

## Authentication

All non-free endpoints require the `X-Token` header to be included with every request. You can find your token in the [customer dashboard](https://customers.triton.one/).

When using `grpcurl`:

```bash
grpcurl \
  -H "X-Token: <your-token>" \
  <your-endpoint>.mainnet.sui.rpcpool.com:443 \
  list
```

When using a generated gRPC client (e.g. in Go or TypeScript), add the token as a metadata field on every call:

{% code title="gRPC metadata" %}

```
key:   "x-token"
value: "<your-token>"
```

{% endcode %}

***

## Available services

The Sui gRPC API is defined via `.proto` files available in the [`sui-apis` repository on GitHub](https://github.com/MystenLabs/sui-apis/tree/main/proto). The following services are available:

| Service                        | Purpose                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------- |
| `TransactionExecutionService`  | Execute signed transactions, or simulate a transaction before you submit it           |
| `LedgerService`                | Look up checkpoints, transactions, objects, and epochs from the node's recent history |
| `StateService`                 | Query live onchain data: balances, coin info, owned objects, and dynamic fields       |
| `SubscriptionService`          | Stream checkpoints, transactions, and events in real time                             |
| `MovePackageService`           | Access deployed Move package metadata and content                                     |
| `SignatureVerificationService` | Validate signatures (including zkLogin) outside of transaction execution              |
| `NameService`                  | Resolve SuiNS names to addresses and perform reverse lookups                          |

Use these `.proto` definitions to generate type-safe client libraries in your language of choice.

***

## Quickstart: grpcurl examples

[`grpcurl`](https://github.com/fullstorydev/grpcurl) is the easiest way to explore the API from the command line.

### List available services

```bash
grpcurl \
  -H "X-Token: <your-token>" \
  <your-endpoint>.mainnet.sui.rpcpool.com:443 \
  list
```

### List methods in LedgerService

```bash
grpcurl \
  -H "X-Token: <your-token>" \
  <your-endpoint>.mainnet.sui.rpcpool.com:443 \
  list sui.rpc.v2.LedgerService
```

### Get the latest checkpoint

`GetCheckpoint` returns the latest checkpoint when the request names no sequence number or digest.

```bash
grpcurl \
  -H "X-Token: <your-token>" \
  -d '{}' \
  <your-endpoint>.mainnet.sui.rpcpool.com:443 \
  sui.rpc.v2.LedgerService/GetCheckpoint
```

### Get a transaction (events and effects)

```bash
grpcurl \
  -H "X-Token: <your-token>" \
  -d '{
    "digest": "<transaction-digest>",
    "read_mask": {
      "paths": ["effects", "events"]
    }
  }' \
  <your-endpoint>.mainnet.sui.rpcpool.com:443 \
  sui.rpc.v2.LedgerService/GetTransaction
```

### Subscribe to live checkpoints (streaming)

```bash
grpcurl \
  -H "X-Token: <your-token>" \
  -d '{}' \
  <your-endpoint>.mainnet.sui.rpcpool.com:443 \
  sui.rpc.v2.SubscriptionService/SubscribeCheckpoints
```

***

## Key concepts

### Field masks

Use `read_mask` to request only the fields you need, reducing response size and latency:

```json
{
  "read_mask": {
    "paths": ["digest", "effects", "events"]
  }
}
```

Pass `"*"` to request all fields. If you omit `read_mask`, each method returns only a small default set of fields: for example, just `digest` from `GetTransaction`, `sequence_number` and `digest` from `GetCheckpoint`, and `object_id`, `version`, and `digest` from `GetObject`. In batch requests, only the top-level `read_mask` is respected.

### Pagination

List APIs (owned objects, balances, etc.) return paginated results. Use `page_size` to control batch size and pass the returned `next_page_token` into the next request to continue. An empty `next_page_token` means you have reached the end. Keep all other request parameters constant between pages.

### Encodings

* `Address` and `ObjectId`: 64-character hex with a `0x` prefix
* `Digest`: Base58 encoded
* `TypeTag` / `StructTag`: Canonical string format

### Errors

Errors follow the [gRPC richer error model](https://grpc.io/docs/guides/error/#richer-error-model). Detailed error information is provided in the `grpc-status-details-bin` header as a Base64-encoded `google.rpc.Status` message.

***

## Resources

* [Sui gRPC Reference (official)](https://docs.sui.io/references/fullnode-protocol)
* [Proto definitions, sui-apis on GitHub](https://github.com/MystenLabs/sui-apis/tree/main/proto)
* [Official: What is gRPC?](https://docs.sui.io/develop/accessing-data/grpc/what-is-grpc)
* [Official: Querying Data with gRPC](https://docs.sui.io/develop/accessing-data/grpc/using-grpc)
* The [grpcurl tool](https://github.com/fullstorydev/grpcurl)

***

<i class="fa-life-ring">:life-ring:</i> Contact support by clicking the chat icon in your [customer dashboard](https://customers.triton.one)\ <i class="fa-briefcase">:briefcase:</i> Sales questions? [Contact us](https://triton.one/contact)\ <i class="fa-sparkles">:sparkles:</i> AI agent? Read [llms.txt](https://docs.triton.one/llms.txt)\ <i class="fa-rss">:rss:</i> Follow updates: [Blog](https://blog.triton.one) · [X](https://x.com/triton_one) · [YouTube](https://www.youtube.com/@triton_one_ltd) · [Telegram](https://t.me/tritonone) · [GitHub](https://github.com/rpcpool)