Skip to main content

gRPC API

High-performance binary protocol for RP1 interactions.

Connection​

# Mainnet
grpc.rp.one:9090

# Testnet
grpc.testnet.rp.one:9090

Using grpcurl​

# Install grpcurl
brew install grpcurl

# List services
grpcurl -plaintext grpc.rp.one:9090 list

# Describe service
grpcurl -plaintext grpc.rp.one:9090 describe cosmos.bank.v1beta1.Query

Available Services​

Cosmos Standard​

ServiceDescription
cosmos.bank.v1beta1.QueryBank balances
cosmos.staking.v1beta1.QueryStaking info
cosmos.gov.v1beta1.QueryGovernance
cosmos.tx.v1beta1.ServiceTransactions
cosmos.auth.v1beta1.QueryAccount info

RP1 Modules​

ServiceDescription
rp1.privacy.v1.QueryPrivacy module
rp1.lending.v1.QueryLending module
rp1.oracle.v1.QueryOracle prices
rp1.uta.v1.QueryTrading account
rp1.instawrap.v1.QueryBridge
rp1.feeburn.v1.QueryFee statistics

Query Examples​

Get Balance​

grpcurl -plaintext \
  -d '{"address": "rp1abc...", "denom": "urp1"}' \
  grpc.rp.one:9090 \
  cosmos.bank.v1beta1.Query/Balance

Get Oracle Price​

grpcurl -plaintext \
  -d '{"symbol": "BTC"}' \
  grpc.rp.one:9090 \
  rp1.oracle.v1.Query/Price

Get Privacy Pool Stats​

grpcurl -plaintext \
  grpc.rp.one:9090 \
  rp1.privacy.v1.Query/PoolStats

Go Client​

package main

import (
    "context"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials/insecure"

    banktypes "github.com/cosmos/cosmos-sdk/x/bank/types"
)

func main() {
    // Connect
    conn, err := grpc.Dial(
        "grpc.rp.one:9090",
        grpc.WithTransportCredentials(insecure.NewCredentials()),
    )
    if err != nil {
        panic(err)
    }
    defer conn.Close()

    // Create client
    bankClient := banktypes.NewQueryClient(conn)

    // Query balance
    res, err := bankClient.Balance(context.Background(), &banktypes.QueryBalanceRequest{
        Address: "rp1abc...",
        Denom:   "urp1",
    })
    if err != nil {
        panic(err)
    }

    fmt.Printf("Balance: %s\n", res.Balance.Amount)
}

TypeScript Client​

import { createProtobufRpcClient, QueryClient } from '@cosmjs/stargate';
import { Tendermint37Client } from '@cosmjs/tendermint-rpc';

async function queryViaGrpc() {
  // Connect to Tendermint RPC
  const tmClient = await Tendermint37Client.connect('https://rpc.rp.one');
  const queryClient = new QueryClient(tmClient);

  // Create protobuf RPC client
  const rpcClient = createProtobufRpcClient(queryClient);

  // Query bank balance
  const bankQuery = new bankv1beta1.QueryClientImpl(rpcClient);
  const balance = await bankQuery.Balance({
    address: 'rp1abc...',
    denom: 'urp1',
  });

  console.log(`Balance: ${balance.balance?.amount}`);
}

Streaming​

gRPC supports streaming for real-time updates:

// Subscribe to new blocks
stream, err := tmClient.Subscribe(ctx, "new-blocks", "tm.event='NewBlock'")
if err != nil {
    panic(err)
}

for event := range stream {
    block := event.Data.(tmtypes.EventDataNewBlock)
    fmt.Printf("New block: %d\n", block.Block.Height)
}

Proto Files​

Proto definitions are available at:

https://github.com/rp1-network/rp1-chain/tree/main/proto

Generate Client Code​

# Go
buf generate --template buf.gen.go.yaml

# TypeScript
buf generate --template buf.gen.ts.yaml

Performance​

MetricValue
Latency<10ms
Throughput10,000+ req/s
ConnectionPersistent
ProtocolHTTP/2

Best Practices​

  1. Use connection pooling for high-throughput applications
  2. Enable compression for large responses
  3. Set appropriate timeouts to avoid hanging connections
  4. Use streaming for real-time data instead of polling

Error Handling​

import "google.golang.org/grpc/codes"
import "google.golang.org/grpc/status"

res, err := client.Query(ctx, req)
if err != nil {
    st, ok := status.FromError(err)
    if ok {
        switch st.Code() {
        case codes.NotFound:
            // Handle not found
        case codes.InvalidArgument:
            // Handle invalid argument
        default:
            // Handle other errors
        }
    }
}

Next Steps​