BlockRazor Base API Go Client

base-api-client-go provides Go examples for connecting to the BlockRazor Base API through gRPC and WebSocket.

The repository demonstrates how to subscribe to Base block streams, raw Flashblock streams, and Flashblock transaction streams, as well as how to submit a raw transaction. It also includes the Protocol Buffers definitions and generated Go client code for the BlockRazor Base API.

Supported APIs

Capability	Protocol	Method or function
Base block stream	gRPC	GetBlockStream
Raw Flashblock stream	gRPC	GetRawFlashBlockStream
Flashblock transaction stream	gRPC	GetNewFlashblockTransactionsStream
Transaction submission	gRPC	SendTransaction
Flashblock subscription	WebSocket	subscribe_FlashBlock
Flashblock transaction subscription	WebSocket	subscribe_FlashTransaction

Requirements

• Go 1.24
• A BlockRazor authentication token
• Access to the corresponding BlockRazor Base API service

Repository structure

.
├── main.go                  # gRPC and WebSocket client examples
├── proto/
│   └── BaseApi.proto        # Base API service and message definitions
├── basepb/
│   ├── BaseApi.pb.go        # Generated Protocol Buffers types
│   └── BaseApi_grpc.pb.go   # Generated gRPC client and server interfaces
├── compile_proto.sh         # Protocol Buffers generation script
├── go.mod
└── go.sum

Quick start

Clone the repository:

git clone https://github.com/BlockRazorinc/base-api-client-go.git
cd base-api-client-go

Download the Go dependencies:

go mod download

Open main.go and replace the placeholder token:

authToken = "your token goes here"

Run the example:

go run .

By default, main() calls:

GetBlockStream(authToken)

This example connects to the configured gRPC endpoint and waits for Base blocks.

Select an example

The available examples are listed in main():

func main() {
	// GetFlashBlockStream(authToken)
	// GetFlashTransactionStream(authToken)
	GetBlockStream(authToken)
	// GetWebSocketFlashBlockStream(authToken)
	// GetWebSocketFlashTransactionStream(authToken)
}

Comment out the current function and enable the example you want to run.

Configure the endpoints

The example endpoints are defined at the top of main.go:

const (
	grpcAddr      = "tokyo.grpc.base.blockrazor.xyz:80"
	websocketAddr = "ws://tokyo.base.blockrazor.xyz:81/ws"
	authToken     = "your token goes here"
)

The source also includes commented WebSocket addresses for Frankfurt and Virginia:

// websocketAddr = "ws://frankfurt.base.blockrazor.xyz:81/ws"
// websocketAddr = "ws://virginia.base.blockrazor.xyz:81/ws"

Update the configured address when another available endpoint is required.

Authentication

The examples send the authentication token through the authorization metadata or HTTP header.

gRPC authentication

streamCtx := metadata.NewOutgoingContext(
	context.Background(),
	metadata.Pairs("authorization", authToken),
)

WebSocket authentication

header := http.Header{}
header.Set("Authorization", authToken)

Subscribe to the Base block stream

GetBlockStream calls the gRPC GetBlockStream method and waits for new blocks:

stream, err := client.GetBlockStream(
	streamCtx,
	&basepb.GetBlockStreamRequest{},
)

For every received block, the example prints:

• Block number
• Block hash
• Transaction count

log.Printf(
	"=> [BlockStream] Received new block: Number=%d, Hash=%s, TransactionCount=%d",
	block.GetBlockNumber(),
	block.GetBlockHash(),
	len(block.GetTransactions()),
)

Transactions are returned as binary values in the block response. The repository includes DecodeTransactions for decoding them into go-ethereum transaction objects:

transactions, err := DecodeTransactions(block.GetTransactions())

Subscribe to the raw Flashblock stream with gRPC

GetFlashBlockStream calls GetRawFlashBlockStream:

stream, err := client.GetRawFlashBlockStream(
	streamCtx,
	&basepb.GetRawFlashBlocksStreamRequest{},
)

The response contains Flashblock data in the message field. The example passes this data to ParseFlashBlockByte, which uses Brotli decompression:

jsonString, err := ParseFlashBlockByte(block.Message)

The decompressed JSON is then formatted and printed.

Subscribe to Flashblock transactions with gRPC

GetFlashTransactionStream calls:

stream, err := client.GetNewFlashblockTransactionsStream(
	streamCtx,
	&basepb.GetNewFlashblockTransactionsStreamRequest{},
)

For every received transaction, the example prints:

• Block number
• Transaction hash
• Transaction index

The complete transaction message defined in BaseApi.proto also contains fields such as the sender, recipient, value, gas information, input, logs, status, and block timestamp.

Subscribe to Flashblocks with WebSocket

GetWebSocketFlashBlockStream connects to the configured WebSocket endpoint and sends this JSON-RPC request:

{
  "jsonrpc": "2.0",
  "method": "subscribe_FlashBlock",
  "params": [],
  "id": 1
}

The response is parsed from the JSON-RPC result field. The result data is then Brotli-decompressed and printed as JSON.

Subscribe to Flashblock transactions with WebSocket

GetWebSocketFlashTransactionStream sends:

{
  "jsonrpc": "2.0",
  "method": "subscribe_FlashTransaction",
  "params": [],
  "id": 1
}

Each valid result is decoded into basepb.NewFlashblockTransaction and printed as formatted JSON.

Submit a transaction

The Proto service defines the following unary gRPC method:

rpc SendTransaction(SendTransactionRequest)
    returns (SendTransactionResponse);

The request contains a raw transaction string:

message SendTransactionRequest {
  string rawTransaction = 1;
}

The response contains the transaction hash:

message SendTransactionResponse {
  string txHash = 1;
}

The repository provides a sendTransactions helper that accepts an existing basepb.BaseApiClient:

func sendTransactions(
	client basepb.BaseApiClient,
	authToken string,
	rawTxString string,
)

The helper sends the token in gRPC metadata and prints the returned transaction hash. The source recommends keeping the gRPC client connection alive when sending transactions.

Base API service definition

The BaseApi service is defined in proto/BaseApi.proto:

service BaseApi {
  rpc SendTransaction(SendTransactionRequest)
      returns (SendTransactionResponse);

  rpc GetBlockStream(GetBlockStreamRequest)
      returns (stream BaseBlock);

  rpc GetRawFlashBlockStream(GetRawFlashBlocksStreamRequest)
      returns (stream RawFlashBlockStrResponse);

  rpc GetNewFlashblockTransactionsStream(
      GetNewFlashblockTransactionsStreamRequest
  ) returns (stream NewFlashblockTransaction);
}

Regenerate the Go protobuf files

The repository includes compile_proto.sh:

./compile_proto.sh

The script runs:

protoc \
  -I=./proto \
  --go_out=. \
  --go-grpc_out=. \
  proto/*.proto

Running the script requires protoc together with the Go Protocol Buffers and gRPC code-generation plugins.

Connection behavior

The stream examples make one connection attempt and exit after a connection, subscription, or receive error.

The source code does not implement automatic reconnection. Applications using these examples in production need to provide their own reconnection behavior.

The examples currently use insecure gRPC transport credentials:

grpc.WithTransportCredentials(insecure.NewCredentials())

Frequently asked questions

What is base-api-client-go?

base-api-client-go is a collection of Go examples and generated Protocol Buffers code for accessing the BlockRazor Base API through gRPC and WebSocket.

Which Base data streams are included?

The repository includes examples for Base blocks, raw Flashblocks, and Flashblock transactions.

Does the repository support transaction submission?

Yes. The Proto service defines SendTransaction, and main.go contains a helper for submitting a raw transaction through an existing gRPC client.

How is Flashblock data decoded?

Raw Flashblock messages are decompressed with Brotli by ParseFlashBlockByte. The resulting content is printed as formatted JSON.

Does the example reconnect automatically?

No. The stream examples attempt to connect once and stop when a connection or receive error occurs.