gRPC for Sui

Create an account on our dashboard to get an API Key. gRPC endpoint is available for all Lite, Basic, and Pro members.

Overview

BlockVision's Sui gRPC service provides high-performance streaming capabilities specifically optimized for real-time blockchain data consumption. Built on a transparent proxy architecture, it offers seamless integration with existing Sui applications while providing advanced features like byte-level billing and intelligent rate limiting.

Service Endpoints

BlockVision provides gRPC endpoints for both Mainnet and Testnet networks:

Network	Endpoint
Mainnet	`sui-mainnet-grpc.blockvision.org:443`
Testnet	`sui-testnet-grpc.blockvision.org:443`

Note: All connections require TLS encryption. All requests require a valid API Key in the metadata header x-api-key:

grpcurl -H "x-api-key: your-api-key-here" sui-mainnet-grpc.blockvision.org:443 list

ctx := metadata.AppendToOutgoingContext(context.Background(),
    "x-api-key", "your-api-key-here",
)

metadata = [('x-api-key', 'your-api-key-here')]

Sui gRPC Documentation

For comprehensive information about Sui gRPC services, refer to the official Sui documentation:

gRPC Concepts & Services: Learn about gRPC concepts, available services, field masks, pagination, error handling, and best practices for the Sui network.
Using gRPC Guide: Step-by-step guide for building gRPC clients in TypeScript, Go, and Python, including code examples and protobuf generation instructions.

Client Integration Example

Streaming Service Example (SubscribeCheckpoints)

grpcurl \
  -H "x-api-key: your-api-key-here" \
  sui-mainnet-grpc.blockvision.org:443 \
  sui.rpc.v2.SubscriptionService/SubscribeCheckpoints

package main

import (
    "context"
    "log"
    
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
)

func main() {
    // Connect to Sui gRPC service with TLS
    conn, err := grpc.Dial("sui-mainnet-grpc.blockvision.org:443", 
        grpc.WithTransportCredentials(credentials.NewTLS(nil)))
    if err != nil {
        log.Fatalf("Connection failed: %v", err)
    }
    defer conn.Close()
    
    // Set authentication
    ctx := metadata.AppendToOutgoingContext(context.Background(),
        "x-api-key", "your-api-key-here",
    )
    
    // Subscribe to checkpoints (streaming service)
    subscriptionClient := sui.NewSubscriptionServiceClient(conn)
    stream, err := subscriptionClient.SubscribeCheckpoints(ctx, &sui.SubscribeCheckpointsRequest{})
    if err != nil {
        log.Fatalf("Subscription failed: %v", err)
    }
    
    // Process streaming responses
    for {
        resp, err := stream.Recv()
        if err != nil {
            log.Printf("Receive error: %v", err)
            break
        }
        log.Printf("Received checkpoint: %+v", resp)
    }
}

import grpc
import json
from concurrent import futures
import threading

# Import generated protobuf files (you need to generate these from .proto files)
# from sui_pb2 import SubscribeCheckpointsRequest
# from sui_pb2_grpc import SubscriptionServiceStub

def subscribe_checkpoints():
    # Create gRPC channel with TLS
    channel = grpc.secure_channel('sui-mainnet-grpc.blockvision.org:443', 
                                 grpc.ssl_channel_credentials())
    
    # Create metadata with API key
    metadata = [('x-api-key', 'your-api-key-here')]
    
    try:
        # Create subscription client
        # subscription_client = SubscriptionServiceStub(channel)
        
        # Create request
        # request = SubscribeCheckpointsRequest()
        
        # Make streaming call
        # stream = subscription_client.SubscribeCheckpoints(request, metadata=metadata)
        
        # Process streaming responses
        # for response in stream:
        #     print(f"Received checkpoint: {response}")
        
        print("Streaming service example (requires protobuf generation)")
        
    except grpc.RpcError as e:
        print(f"gRPC error: {e.code()}: {e.details()}")
    finally:
        channel.close()

if __name__ == "__main__":
    subscribe_checkpoints()

Standard Service Example (GetObject)

grpcurl \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "object_id": "0x0000000000000000000000000000000000000000000000000000000000000002",
    "options": {
      "show_type": true,
      "show_owner": true,
      "show_previous_transaction": true
    }
  }' \
  sui-mainnet-grpc.blockvision.org:443 \
  sui.rpc.v2.ReadService/GetObject

package main

import (
    "context"
    "log"
    
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/metadata"
)

func main() {
    // Connect to Sui gRPC service with TLS
    conn, err := grpc.Dial("sui-mainnet-grpc.blockvision.org:443", 
        grpc.WithTransportCredentials(credentials.NewTLS(nil)))
    if err != nil {
        log.Fatalf("Connection failed: %v", err)
    }
    defer conn.Close()
    
    // Set authentication
    ctx := metadata.AppendToOutgoingContext(context.Background(),
        "x-api-key", "your-api-key-here",
    )
    
    // Create read client for standard operations
    readClient := sui.NewReadServiceClient(conn)
    
    // Get object information
    objectResp, err := readClient.GetObject(ctx, &sui.GetObjectRequest{
        ObjectId: "0x1234567890abcdef...",
        Options: &sui.ObjectDataOptions{
            ShowType: true,
            ShowOwner: true,
            ShowPreviousTransaction: true,
        },
    })
    if err != nil {
        log.Fatalf("GetObject failed: %v", err)
    }
    
    log.Printf("Object data: %+v", objectResp)
}

import grpc
import json

# Import generated protobuf files
# from sui_pb2 import GetObjectRequest, ObjectDataOptions
# from sui_pb2_grpc import ReadServiceStub

def get_object_example():
    # Create gRPC channel with TLS
    channel = grpc.secure_channel('sui-mainnet-grpc.blockvision.org:443', 
                                 grpc.ssl_channel_credentials())
    
    # Create metadata with API key
    metadata = [('x-api-key', 'your-api-key-here')]
    
    try:
        # Create read client
        # read_client = ReadServiceStub(channel)
        
        # Create request
        # request = GetObjectRequest(
        #     object_id="0x1234567890abcdef...",
        #     options=ObjectDataOptions(
        #         show_type=True,
        #         show_owner=True,
        #         show_previous_transaction=True
        #     )
        # )
        
        # Make unary call
        # response = read_client.GetObject(request, metadata=metadata)
        # print(f"Object data: {response}")
        
        print("Standard service example (requires protobuf generation)")
        
    except grpc.RpcError as e:
        print(f"gRPC error: {e.code()}: {e.details()}")
    finally:
        channel.close()

if __name__ == "__main__":
    get_object_example()

Supported Services

BlockVision's gRPC proxy service supports the complete suite of Sui APIs as defined in the MystenLabs/sui-apis repository, providing comprehensive coverage for all Sui blockchain operations.

Streaming Services

SubscribeCheckpoints

Real-time checkpoint subscription with byte-level billing precision.

Endpoint: /sui.rpc.v2.SubscriptionService/SubscribeCheckpoints

Core Sui Services

Read API Services

GetObject: Retrieve object information by ID
GetTransaction: Fetch transaction details and status
GetTransactionBlock: Get complete transaction block data
GetTransactionBlocks: Batch transaction retrieval
GetEvents: Query blockchain events with filtering
GetOwnedObjects: Retrieve objects owned by an address
GetCoins: Fetch coin objects for an address
GetAllCoins: Get all coin types for an address
GetBalance: Query coin balance for specific type
GetAllBalances: Get all coin balances for an address

Write API Services

ExecuteTransactionBlock: Submit and execute transactions
ExecuteTransactionBlockSerializedSig: Execute with serialized signatures
ExecuteTransactionBlockV2: Enhanced transaction execution
DryRunTransactionBlock: Simulate transaction execution
GetTransactionBlockAuthSigners: Get transaction signers

Governance Services

GetCommitteeInfo: Retrieve committee information
GetLatestSuiSystemState: Get current system state
GetStakes: Query validator stakes
GetStakesByIds: Get specific stake information
GetValidatorsApy: Retrieve validator APY data

Utility Services

GetReferenceGasPrice: Get current gas price
GetProtocolConfig: Retrieve network protocol configuration
GetChainIdentifier: Get network chain identifier
GetNetworkMetrics: Fetch network performance metrics

Billing Models

Standard Interface Request Billing

Rate: 50 CU per request
Coverage: All standard Sui gRPC services (Read, Write, Governance, Utility)
Billing Event: On successful request completion
Examples: GetObject, ExecuteTransactionBlock, GetCommitteeInfo, etc.

Subscription Billing

Rate: 0.0002 CU per byte
Minimum: 1 CU per message
Coverage: Streaming services only (SubscribeCheckpoints)
Billing Event: Real-time on each message transmission

Protobuf Generation

Before using the Python examples, you need to generate the protobuf files from the Sui API definitions:

Generate Python Protobuf Files

# Clone the Sui APIs repository
git clone https://github.com/MystenLabs/sui-apis.git
cd sui-apis

# Install protobuf compiler and gRPC tools
pip install grpcio-tools

# Generate Python protobuf files
python -m grpc_tools.protoc \
  --proto_path=proto \
  --python_out=generated \
  --grpc_python_out=generated \
  proto/sui/rpc/v2/*.proto

# The generated files will be in the 'generated' directory

Generate Go Protobuf Files

# Install protoc-gen-go and protoc-gen-go-grpc
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

# Generate Go protobuf files
protoc --proto_path=proto \
  --go_out=generated \
  --go-grpc_out=generated \
  proto/sui/rpc/v2/*.proto

Using Generated Files

After generating the protobuf files, update the import statements in the examples:

# Replace the commented imports with actual generated files
from generated.sui_pb2 import SubscribeCheckpointsRequest, GetObjectRequest
from generated.sui_pb2_grpc import SubscriptionServiceStub, ReadServiceStub

Connection Requirements

TLS Encryption

All connections to the Sui gRPC service require TLS encryption for security. The service runs on port 443 with TLS enabled by default.

Important: Do not use -plaintext flag with grpcurl or grpc.WithInsecure() with Go clients, as these will cause connection failures.

Keepalive Configuration (Required for Streaming Services)

⚠️ Important: For long-lived streaming connections (such as SubscribeCheckpoints), you must configure keepalive parameters to prevent intermediate devices (NAT, firewalls, load balancers) from closing idle connections.

Why Keepalive is Required:

Intermediate devices typically close idle connections after 60-120 seconds
Without keepalive pings, streaming connections will be interrupted
Keepalive pings keep the connection alive even when no data is being transmitted

Recommended Keepalive Settings:

Ping Interval: 30 seconds (send ping every 30 seconds if no activity)
Ping Timeout: 5 seconds (wait 5 seconds for ping acknowledgment)
Permit Without Stream: true (allow pings even when there are no active streams)

Connection Lifecycle Without Keepalive:

60-120 seconds: Connection may be closed by intermediate devices → connection reset by peer error
15 minutes: Connection closed by server (MaxConnectionIdle) → UNAVAILABLE error
30 minutes: Connection closed by server (MaxConnectionAge) → UNAVAILABLE error

Connection Lifecycle With Keepalive:

Connection remains active indefinitely (as long as keepalive pings are sent)
No unexpected disconnections from intermediate devices
Stable long-lived streaming connections

Connection Examples

Go Client (TLS Required)

import (
    "time"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "google.golang.org/grpc/keepalive"
)

// Correct: Use TLS with Keepalive (required for streaming services)
conn, err := grpc.Dial("sui-mainnet-grpc.blockvision.org:443", 
    grpc.WithTransportCredentials(credentials.NewTLS(nil)),
    grpc.WithKeepaliveParams(keepalive.ClientParameters{
        Time:                30 * time.Second,
        Timeout:             5 * time.Second,
        PermitWithoutStream: true,
    }),
)

// Incorrect: This will fail (no TLS)
// conn, err := grpc.Dial("sui-mainnet-grpc.blockvision.org:443", 
//     grpc.WithInsecure())

// Incorrect: Missing keepalive for streaming (connection may be closed)
// conn, err := grpc.Dial("sui-mainnet-grpc.blockvision.org:443", 
//     grpc.WithTransportCredentials(credentials.NewTLS(nil)))

Python Client (TLS Required)

# Correct: Use TLS with Keepalive (required for streaming services)
keepalive_options = [
    ('grpc.keepalive_time_ms', 30000),
    ('grpc.keepalive_timeout_ms', 5000),
    ('grpc.keepalive_permit_without_calls', True),
    ('grpc.http2.max_pings_without_data', 0),
    ('grpc.http2.min_time_between_pings_ms', 10000),
]

channel = grpc.secure_channel(
    'sui-mainnet-grpc.blockvision.org:443',
    grpc.ssl_channel_credentials(),
    options=keepalive_options
)

# Incorrect: This will fail (no TLS)
# channel = grpc.insecure_channel('sui-mainnet-grpc.blockvision.org:443')

# Incorrect: Missing keepalive for streaming (connection may be closed)
# channel = grpc.secure_channel('sui-mainnet-grpc.blockvision.org:443', 
#                              grpc.ssl_channel_credentials())

grpcurl (TLS by Default)

# Correct: TLS enabled by default
grpcurl -H "x-api-key: your-api-key" sui-mainnet-grpc.blockvision.org:443 list

# Incorrect: This will fail
# grpcurl -plaintext -H "x-api-key: your-api-key" sui-mainnet-grpc.blockvision.org:443 list

Detailed Billing Information

Standard Interface Request Billing

Rate: 50 CU per request

Coverage: All standard Sui gRPC services

Read Services (GetObject, GetTransaction, GetEvents, etc.)
Write Services (ExecuteTransactionBlock, DryRunTransactionBlock, etc.)
Governance Services (GetCommitteeInfo, GetStakes, etc.)
Utility Services (GetReferenceGasPrice, GetProtocolConfig, etc.)

Billing Event: Charged on successful request completion

Subscription Billing

Rate: 0.0002 CU per byte (minimum 50 CU per message)

Coverage: Streaming services only

SubscribeCheckpoints

Billing Event: Real-time on each message transmission

Subscription Billing Examples

Message Size	Calculation	Actual CU
1,000 bytes	1,000 × 0.0002 = 0.2	50 CU (minimum)
5,000 bytes	5,000 × 0.0002 = 1.0	50 CU (minimum)
40,000 bytes	40,000 × 0.0002 = 8.0	50 CU (minimum)
1,000,000 bytes	1,000,000 × 0.0002 = 200.0	200 CU

Billing Summary

Service Type	Billing Model	Rate	Billing Event
Standard Requests	Fixed per request	50 CU	On completion
Subscription	Per-byte	0.0002 CU/byte	Real-time

Error Handling

Error Code	Description	Action Required
`UNAUTHENTICATED`	Invalid API Key	Verify authentication credentials
`UNAVAILABLE`	Service unavailable	Check service status
`CANCELLED`	Request cancelled	Normal client cancellation
`INTERNAL`	Internal server error	Contact support

Performance Characteristics

Latency: Sub-100ms for checkpoint delivery
Throughput: High-concurrency streaming support
Reliability: 99.999% uptime SLA
Scalability: Auto-scaling based on demand

Support

For technical support and inquiries:

📧 Email: [email protected]
💬 Discord: Community Support