---
title: gRPC API Overview
description: High-performance gRPC API for real-time blockchain interactions
  using Protocol Buffers
source_url:
  html: https://thru.org/docs/api-ref/grpc/overview/
  md: https://thru.org/docs/api-ref/grpc/overview.md
---

# gRPC API Overview

The Thru gRPC API provides high-performance, strongly-typed remote procedure calls for interacting with the blockchain. Built on Protocol Buffers and HTTP/2, gRPC offers efficient binary serialization and bidirectional streaming.

For browser-based applications, gRPC-Web provides a JavaScript-compatible version of the gRPC protocol that works in web browsers without requiring plugins or proxies.

## API Endpoints

| Network | Endpoint | Protocol | Description |
| - | - | - | - |
| Alphanet | `grpc.alphanet.thruput.org:443` | gRPC over HTTP/2 with TLS | Native gRPC endpoint for all platforms |
| Alphanet | `https://grpc-web.alphanet.thruput.org` | gRPC-Web | Browser-compatible gRPC endpoint |

## Available Services

- [QueryService](https://thru.org/docs/api-ref/grpc/services/query-service.md): Read-only operations for querying blockchain state, accounts, blocks, and transactions
- [CommandService](https://thru.org/docs/api-ref/grpc/services/command-service.md): Write operations for submitting transactions and executing state-changing operations
- [StreamingService](https://thru.org/docs/api-ref/grpc/services/streaming-service.md): Real-time streaming for account updates, block notifications, and transaction monitoring

## Common Features

### Protocol Buffers

All gRPC services use Protocol Buffers (proto3) for serialization. Proto definitions are available in the [GitHub repository](https://github.com/Unto-Labs/thru-net/tree/main/proto).

### Binary Serialization

gRPC uses Protocol Buffers for efficient binary serialization, resulting in payloads 2-10x smaller than JSON.

### Streaming Support

The StreamingService supports bidirectional streaming for real-time updates:

```python
# Subscribe to account updates
request = SubscribeAccountRequest(address=account_address)
for update in client.SubscribeAccount(request):
    print(f"Account updated: {update}")
```

### Error Handling

gRPC uses status codes for error handling:

- `OK` (0) - Success
- `NOT_FOUND` (5) - Resource not found
- `INVALID_ARGUMENT` (3) - Invalid request parameters
- `INTERNAL` (13) - Internal server error
- `UNAVAILABLE` (14) - Service unavailable

## Performance

Typical performance characteristics:

- Request latency: <50ms
- Throughput: 1000+ requests/second per connection
- Payload size: 2-10x smaller than REST/JSON

## Best Practices

Connection Pooling

Reuse gRPC channels and connections instead of creating new ones for each request

Timeouts

Set appropriate deadlines for requests to prevent hanging operations

Retry Logic

Implement exponential backoff for retries on transient failures

Health Checks

Monitor service health using gRPC health check protocol