# Role of gRPC-Gateway in Akash Node: REST API Route Registration Explained

> Discover how gRPC-gateway in Akash Node translates gRPC services to REST endpoints and how routes register via RegisterGRPCGatewayRoutes for efficient node operation.

- Repository: [Akash Network/node](https://github.com/akash-network/node)
- Tags: deep-dive
- Published: 2026-02-24

---

**The gRPC-gateway in Akash Node acts as a protocol translator that exposes internal gRPC query services as REST/JSON endpoints, with each Cosmos SDK module registering its HTTP routes through the `RegisterGRPCGatewayRoutes` method during node initialization.**

The akash-network/node repository utilizes a **gRPC-gateway** to provide HTTP access to the blockchain's query layer without requiring native gRPC clients. This component automatically translates incoming REST requests into gRPC calls and marshals protobuf responses into JSON format. Understanding how the gateway registers routes reveals how the modular architecture wires HTTP paths to specific query services during the node's startup sequence.

## What Is the gRPC-Gateway?

The gRPC-gateway is a reverse proxy that allows HTTP/JSON clients to interact with Akash Node's internal gRPC services. It enables browsers, command-line tools, and CI pipelines to query blockchain state using standard HTTP methods while the node internally processes these as efficient gRPC calls.

### Protocol Translation Layer

Powered by the `grpc-gateway` library (v2) from the grpc-ecosystem, the gateway inspects incoming HTTP requests, routes them to the appropriate gRPC method, and translates the protobuf response into JSON. This eliminates the need for clients to handle protobuf encoding or maintain gRPC connections directly.

## How Routes Are Registered in Akash Node

Each Cosmos SDK module in the Akash codebase implements the **`RegisterGRPCGatewayRoutes`** method on its `AppModuleBasic` type to expose its query endpoints. This method receives a `client.Context` containing the gRPC endpoint configuration and a `runtime.ServeMux` where HTTP handlers are mounted.

### The Registration Interface

During node startup, the application invokes `RegisterGRPCGatewayRoutes` for every module added to the `module.Configurator`. Inside this method, the module calls its **generated** `RegisterQueryHandlerClient` function from the protobuf package, passing three critical arguments:

- `context.Background()` for request scoping
- The `mux` (*runtime.ServeMux*) to which HTTP paths are added
- A `NewQueryClient` instance that knows the node's gRPC address

### Fail-Fast Error Handling

If registration encounters an error, the method immediately panics with a descriptive message, causing the node startup to abort. This guarantees that the gateway never runs with partially registered or missing routes, preventing runtime HTTP 404 errors for expected endpoints.

## Module Route Registration Examples

Every core module in Akash Node follows an identical pattern for wiring its query services to the REST API.

### Provider Module Implementation

In [`x/provider/module.go`](https://github.com/akash-network/node/blob/main/x/provider/module.go), the `AppModuleBasic` type implements the registration method by binding the provider query client to the serve mux:

```go
func (AppModuleBasic) RegisterGRPCGatewayRoutes(clientCtx client.Context, mux *runtime.ServeMux) {
    err := types.RegisterQueryHandlerClient(
        context.Background(),
        mux,
        types.NewQueryClient(clientCtx),
    )
    if err != nil {
        panic(fmt.Sprintf("couldn't register provider grpc routes: %s", err.Error()))
    }
}

```

This code mounts all provider-specific query paths (such as listing providers) onto the gateway's router.

### Additional Module Registrations

The following modules implement identical `RegisterGRPCGatewayRoutes` methods in their respective [`module.go`](https://github.com/akash-network/node/blob/main/module.go) files:

- **Market module** ([`x/market/module.go`](https://github.com/akash-network/node/blob/main/x/market/module.go)): Registers market query handlers via `types.RegisterQueryHandlerClient`
- **Deployment module** ([`x/deployment/module.go`](https://github.com/akash-network/node/blob/main/x/deployment/module.go)): Wires deployment query routes using the generated handler
- **Escrow module** ([`x/escrow/module.go`](https://github.com/akash-network/node/blob/main/x/escrow/module.go)): Uses `v1.RegisterQueryHandlerClient` for versioned protobuf queries
- **Cert module** ([`x/cert/module.go`](https://github.com/akash-network/node/blob/main/x/cert/module.go)): Mounts certificate query endpoints
- **Audit module** ([`x/audit/module.go`](https://github.com/akash-network/node/blob/main/x/audit/module.go)): Registers audit-related REST paths
- **Take module** ([`x/take/module.go`](https://github.com/akash-network/node/blob/main/x/take/module.go)): Completes the registration chain for "take" queries

## HTTP Request Flow Through the Gateway

When a client queries the provider list via HTTP, the request traverses the following path:

1. The HTTP request hits the gRPC-gateway's `runtime.ServeMux` on port 1317
2. The mux matches the path `/akash/provider/v1beta2/providers` to the handler registered by [`provider/module.go`](https://github.com/akash-network/node/blob/main/provider/module.go)
3. The handler creates a `ProviderQueryClient` via `types.NewQueryClient` that forwards the request to the node's internal gRPC server
4. The gRPC response is marshaled to JSON and returned to the HTTP client

Example client request:

```bash
curl http://localhost:1317/akash/provider/v1beta2/providers

```

## Key Source Files for Gateway Implementation

Understanding the complete gateway architecture requires examining these specific files in the akash-network/node repository:

- [`x/provider/module.go`](https://github.com/akash-network/node/blob/main/x/provider/module.go): Provider route registration logic
- [`x/market/module.go`](https://github.com/akash-network/node/blob/main/x/market/module.go): Market module gateway setup
- [`x/deployment/module.go`](https://github.com/akash-network/node/blob/main/x/deployment/module.go): Deployment query REST exposure
- [`x/escrow/module.go`](https://github.com/akash-network/node/blob/main/x/escrow/module.go): Escrow module registration (uses versioned `v1` package)
- [`x/cert/module.go`](https://github.com/akash-network/node/blob/main/x/cert/module.go): Certificate query route binding
- [`x/audit/module.go`](https://github.com/akash-network/node/blob/main/x/audit/module.go): Audit module REST handlers
- [`x/take/module.go`](https://github.com/akash-network/node/blob/main/x/take/module.go): "Take" module gateway configuration
- [`testutil/network/util.go`](https://github.com/akash-network/node/blob/main/testutil/network/util.go): Demonstrates gRPC server initialization and gateway attachment via `api.New`
- [`tests/upgrade/upgrade_test.go`](https://github.com/akash-network/node/blob/main/tests/upgrade/upgrade_test.go): Contains environment variable configurations for gRPC and gRPC-Web endpoints

## Summary

- The **gRPC-gateway** translates HTTP/JSON requests into internal gRPC calls, enabling browser-based and REST-native clients to query the Akash blockchain.
- Each module implements **`RegisterGRPCGatewayRoutes`** on `AppModuleBasic` to bind generated query handlers to the `runtime.ServeMux` during node startup.
- Registration calls the generated **`RegisterQueryHandlerClient`** function with a `NewQueryClient` instance scoped to the node's gRPC endpoint.
- Failures during route registration trigger an immediate **panic**, ensuring the node never starts with incomplete REST API coverage.
- All core modules—**provider, market, deployment, escrow, cert, audit, and take**—follow this identical registration pattern in their respective `x/{module}/module.go` files.

## Frequently Asked Questions

### What is the primary purpose of gRPC-gateway in Akash Node?

The gRPC-gateway serves as a protocol bridge that exposes the node's internal gRPC query services as standard REST/JSON HTTP endpoints. This allows external clients like browsers, mobile applications, and shell scripts to interact with the Akash blockchain without implementing native gRPC clients or handling protobuf encoding directly.

### How does a Cosmos SDK module register its REST endpoints?

Each module implements the `RegisterGRPCGatewayRoutes` method on its `AppModuleBasic` type, which receives a `client.Context` and a `runtime.ServeMux`. Inside this method, the module calls its generated `RegisterQueryHandlerClient` function, passing a new query client instance to bind HTTP paths to the appropriate gRPC handlers.

### What happens if route registration fails during node startup?

The registration method implements fail-fast behavior by calling `panic` if `RegisterQueryHandlerClient` returns an error. This immediate termination prevents the node from starting with incomplete REST API routes, ensuring that all expected HTTP endpoints are properly wired before the gateway begins serving traffic.

### Which library powers the gRPC-gateway implementation?

The implementation relies on the **grpc-gateway v2** library from the grpc-ecosystem, specifically importing `github.com/grpc-ecosystem/grpc-gateway/runtime`. This library provides the `ServeMux` router and the code generation tools that create the `RegisterQueryHandlerClient` functions used by each module.