# gRPC

Access gRPC-based blockchain nodes through a single endpoint with metadata-based chain routing.

## Connection


```
grpc.vilna.io:443
```

TLS is required. Authentication and chain identification are passed via gRPC metadata:

| Metadata key | Value |
|  --- | --- |
| `x-api-key` | Your API key |
| `x-chain-id` | CAIP-2 chain ID or alias (e.g., `tron` or `tron:mainnet`) |


Explicit port
Always specify the `:443` port. Some clients (including `grpcurl`) don't assume a default port and will fail with `missing port in address` if it's omitted.

## Tron

Any Tron gRPC service method can be called through Vilna RPC. The request is routed to the Tron node transparently. gRPC reflection is enabled on the upstream, so `grpcurl` resolves descriptors automatically.

### Get current block


```bash
grpcurl \
  -H "x-api-key: your-api-key" \
  -H "x-chain-id: tron:mainnet" \
  -d '{}' \
  grpc.vilna.io:443 \
  protocol.Wallet/GetNowBlock2
```

### Quick sanity check


```bash
grpcurl \
  -H "x-api-key: your-api-key" \
  -H "x-chain-id: tron:mainnet" \
  grpc.vilna.io:443 \
  protocol.Wallet/TotalTransaction
```

### Get a specific block by number


```bash
grpcurl \
  -H "x-api-key: your-api-key" \
  -H "x-chain-id: tron:mainnet" \
  -d '{"num":70000000}' \
  grpc.vilna.io:443 \
  protocol.Wallet/GetBlockByNum2
```

If you don't have `grpcurl` installed, the same call works from Docker:


```bash
docker run --rm fullstorydev/grpcurl \
  -H "x-api-key: your-api-key" \
  -H "x-chain-id: tron:mainnet" \
  -d '{}' \
  grpc.vilna.io:443 \
  protocol.Wallet/GetNowBlock2
```

### Available services

Vilna proxies all standard Tron gRPC services:

| Service | Description |
|  --- | --- |
| `protocol.Wallet` | Account, transaction, and block operations |
| `protocol.WalletSolidity` | Read-only queries against confirmed blocks |
| `protocol.Database` | Low-level chain data access |


For the full list of available methods, see the [Tron protocol documentation](https://developers.tron.network/reference).

## Error handling

### System errors

Returned by Vilna RPC when the request cannot reach the blockchain node:

| Situation | gRPC status |
|  --- | --- |
| Missing API key | UNAUTHENTICATED |
| Invalid API key | UNAUTHENTICATED |
| Network not found | NOT_FOUND |
| Protocol mismatch | INVALID_ARGUMENT |
| Network unavailable | UNAVAILABLE |


For common API errors and troubleshooting, see the [Errors guide](/guides/errors).

### Blockchain node errors

If the request reaches the node but the node returns an error, you receive the node's native gRPC error. These errors come directly from the blockchain node.

## Next steps

JSON-RPC
HTTP requests for Ethereum, Solana, and Bitcoin nodes

RPC Overview
Supported networks, authentication, and health checks

Errors
Error handling and troubleshooting guide