gRPC API

High-performance RPC interface for querying Bitplanet blockchain state.

Overview

The gRPC API provides efficient, typed RPC calls for:

• All BitSDK module queries

• Custom module queries (Brahma, Precompile)

• Streaming responses for large datasets

Default Endpoint: localhost:9090

Protocol: gRPC (plaintext for local development)

Using grpcurl

grpcurl is a command-line tool for interacting with gRPC services.

List All Services

grpcurl -plaintext localhost:9090 list

List Methods for a Service

grpcurl -plaintext localhost:9090 list cosmos.bank.v1beta1.Query

Bank Module

Query Balance

Get balance for a specific denomination.

Service: cosmos.bank.v1beta1.Query Method: Balance

grpcurl -plaintext \
  -d '{"address":"cosmos1...","denom":"bplcoin"}' \
  localhost:9090 \
  cosmos.bank.v1beta1.Query/Balance

Query All Balances

Get all balances for an address.

Service: cosmos.bank.v1beta1.Query Method: AllBalances

grpcurl -plaintext \
  -d '{"address":"cosmos1..."}' \
  localhost:9090 \
  cosmos.bank.v1beta1.Query/AllBalances

Staking Module

Query Validators

Get all validators.

Service: cosmos.staking.v1beta1.Query Method: Validators

grpcurl -plaintext localhost:9090 \
  cosmos.staking.v1beta1.Query/Validators

Query Validator

Get specific validator by operator address.

Service: cosmos.staking.v1beta1.Query Method: Validator

grpcurl -plaintext \
  -d '{"validator_addr":"cosmosvaloper1..."}' \
  localhost:9090 \
  cosmos.staking.v1beta1.Query/Validator

Query Delegations

Get delegations for a delegator.

Service: cosmos.staking.v1beta1.Query Method: DelegatorDelegations

grpcurl -plaintext \
  -d '{"delegator_addr":"cosmos1..."}' \
  localhost:9090 \
  cosmos.staking.v1beta1.Query/DelegatorDelegations

Governance Module

Query Proposals

Get all governance proposals.

Service: cosmos.gov.v1.Query Method: Proposals

grpcurl -plaintext localhost:9090 \
  cosmos.gov.v1.Query/Proposals

Query Proposal

Get specific proposal by ID.

Service: cosmos.gov.v1.Query Method: Proposal

grpcurl -plaintext \
  -d '{"proposal_id":"1"}' \
  localhost:9090 \
  cosmos.gov.v1.Query/Proposal

Brahma Module

The Brahma module provides queries for AI attribution and reward distribution.

Service: brahma.Query

Query Params

Get Brahma module parameters including siphon percentage and reward splits.

Method: Params

grpcurl -plaintext localhost:9090 brahma.Query/Params

Query AI Tensor by Block Height

Get contribution tensor for an AI at specific block height.

Method: AITensorByBlockHeight

grpcurl -plaintext \
  -d '{"ai_id":"genie-ai","block_height":"1000"}' \
  localhost:9090 brahma.Query/AITensorByBlockHeight

Query Contribution by Wallet Address

Get specific contributor's contributions.

Method: ContributionByWalletAddress

grpcurl -plaintext \
  -d '{"ai_id":"genie-ai","block_height":"1000","wallet_address":"0x123..."}' \
  localhost:9090 brahma.Query/ContributionByWalletAddress

Query Core Grant Application

Get Core Grant Application status by requester.

Method: QueryCoreGrantApplication

grpcurl -plaintext \
  -d '{"requester":"cosmos1..."}' \
  localhost:9090 brahma.Query/QueryCoreGrantApplication

Query Core Token Addresses

Get Core token contract addresses.

Method: QueryCore

grpcurl -plaintext localhost:9090 brahma.Query/QueryCore

Query AI Token Addresses

Get Gem token addresses for an AI.

Method: QueryAITokens

grpcurl -plaintext \
  -d '{"ai_id":"genie-ai"}' \
  localhost:9090 brahma.Query/QueryAITokens

Query Claimable Rewards

Get claimable BPL rewards for an address.

Method: QueryClaimableRewards

grpcurl -plaintext \
  -d '{"address":"0x123..."}' \
  localhost:9090 brahma.Query/QueryClaimableRewards

Query Claim Statistics

Get aggregate statistics about pending claims and Core allocations.

Method: QueryClaimStatistics

grpcurl -plaintext localhost:9090 brahma.Query/QueryClaimStatistics

Get All Block Heights by AI ID

Get all block heights where an AI has tensor data.

Method: GetAllBlockHeightsByAIID

grpcurl -plaintext \
  -d '{"ai_id":"genie-ai"}' \
  localhost:9090 brahma.Query/GetAllBlockHeightsByAIID

Precompile Module

The Precompile module manages EVM precompiled contract addresses.

Service: precompile.Query

Query Params

Get precompile module parameters including contract addresses.

Method: Params

grpcurl -plaintext localhost:9090 precompile.Query/Params

Using gRPC Clients

Go

import (
    "context"
    "google.golang.org/grpc"
    banktypes "github.com/cosmos/cosmos-sdk/x/bank/types"
)

conn, err := grpc.Dial("localhost:9090", grpc.WithInsecure())
defer conn.Close()

client := banktypes.NewQueryClient(conn)
res, err := client.Balance(context.Background(), &banktypes.QueryBalanceRequest{
    Address: "cosmos1...",
    Denom:   "bplcoin",
})

Python

import grpc
from cosmos.bank.v1beta1 import query_pb2, query_pb2_grpc

channel = grpc.insecure_channel('localhost:9090')
stub = query_pb2_grpc.QueryStub(channel)

request = query_pb2.QueryBalanceRequest(
    address="cosmos1...",
    denom="bplcoin"
)
response = stub.Balance(request)
print(f"Balance: {response.balance.amount}")

JavaScript/TypeScript

const grpc = require('@grpc/grpc-js');
const protoLoader = require('@grpc/proto-loader');

const packageDefinition = protoLoader.loadSync(
    'cosmos/bank/v1beta1/query.proto',
    {keepCase: true, longs: String, enums: String, defaults: true, oneofs: true}
);

const bankProto = grpc.loadPackageDefinition(packageDefinition).cosmos.bank.v1beta1;

const client = new bankProto.Query('localhost:9090', grpc.credentials.createInsecure());

client.Balance({
    address: 'cosmos1...',
    denom: 'bplcoin'
}, (error, response) => {
    if (!error) {
        console.log('Balance:', response.balance.amount);
    }
});

gRPC-Web

For browser-based applications, use gRPC-Web.

Default Endpoint: localhost:9091

const {QueryClient} = require('cosmos/bank/v1beta1/query_grpc_web_pb');
const {QueryBalanceRequest} = require('cosmos/bank/v1beta1/query_pb');

const client = new QueryClient('http://localhost:9091');

const request = new QueryBalanceRequest();
request.setAddress('cosmos1...');
request.setDenom('bplcoin');

client.balance(request, {}, (err, response) => {
    if (!err) {
        console.log('Balance:', response.getBalance().getAmount());
    }
});

Benefits of gRPC

• Type Safety: Protocol buffers provide strong typing

• Performance: Binary protocol is more efficient than JSON

• Streaming: Support for server and client streaming

• Code Generation: Auto-generate clients in multiple languages

• Documentation: Self-describing via reflection

---

Related: REST API Reference | CLI Reference