# Cosmos - gRPC

Cosmos gRPC is a high-performance, strongly-typed interface for interacting with Cosmos SDK chains using Protocol Buffers and HTTP/2. This guide shows how to connect to Tatum’s Cosmos gRPC endpoint, authenticate with an API key, set up a Node.js environment with required .proto files, and execute common queries like retrieving balances or staking data.

Cosmos gRPC provides a high-performance, strongly-typed interface for interacting with the Cosmos Hub and other SDK-based chains. Unlike REST, gRPC uses Protocol Buffers and HTTP/2, making it the industry standard for building scalable wallets, indexers, and backend services.

**With Tatum’s Cosmos gRPC endpoint, you can:**

* [Retrieve account balances](/reference/cosmos-grpc#retrieve-account-balances)
* [Retrieve all balances](/reference/cosmos-grpc#retrieve-all-balances)
* [Retrieve staking delegations](/reference/cosmos-grpc#retrieve-staking-delegations)
* And more

<h2>Cosmos Mainnet gRPC endpoint</h2>

<div class="tatum-grid">
  <div class="tatum-grid-header" id="cosmos-grpc">
    <div class="tatum-blockchain-info">
      <img src="https://blockchains.tatum.io/assets/img/cosmos.svg" alt="Cosmos Logo" class="tatum-blockchain-logo" />

      <h3>Cosmos gRPC (Mainnet)</h3>
    </div>

    <div class="tatum-buttons">
      <a class="tatum-btn tatum-postman" href="https://www.postman.com/blockchainnow/tatum-io/collection/69ce3ad9483a20e3fc590719/cosmos-mainnet-grpc" target="_blank" title="Run in Postman - Cosmos gRPC">▶️ Run in Postman</a>
      <a class="tatum-btn tatum-get-started" href="https://dashboard.tatum.io/chains/cosmos?origin=docs&chain=cosmos" target="_blank" title="Get started with Cosmos">🚀 Get Started</a>
    </div>
  </div>

  <div class="tatum-grid-row tatum-interface-row">
    <div class="tatum-grid-cell tatum-interface-name">↳ gRPC (Mainnet)</div>
    <div class="tatum-grid-cell">[https://cosmos-mainnet-grpc.gateway.tatum.io](https://cosmos-mainnet-grpc.gateway.tatum.io)</div>

    <div class="tatum-grid-cell actions">
      <a class="tatum-btn small" href="https://status.tatum.io/#cosmos-mainnet" target="_blank" title="Status page for gRPC">🔍 Status</a>
      <a class="tatum-btn small" href="https://mintscan.io/cosmos" target="_blank" title="Cosmos Mainnet explorer">🕵️ Explorer</a>
    </div>
  </div>
</div>

<p>For Tendermint RPC and the full network list, see <a href="/reference/rpc-cosmos" target="_blank" title="Cosmos RPC reference">Cosmos RPC</a>.</p>

<HTMLBlock>
  {`
  <div class="tatum-callout tatum-callout-pr" onclick="window.open('https://dashboard.tatum.io/?utm_source=docs&utm_medium=docs&utm_campaign=api_banner');">
    <div class="tatum-call-to-action tatum-center">
      <a class="tatum-button tatum-button-secondary" href="https://dashboard.tatum.io/?utm_source=docs&utm_medium=docs&utm_campaign=api_banner" target="_blank">Get API key</a>
      <small class="tatum-benefit">For free. No commitment.</small>
    </div> 
    
    <h2 class="tatum-headline">Don't have an API key?</h2>
    <p class="tatum-description">Sign up to Dashboard and create your API keys today.<br>Get higher limits and use debugging tools.</p>
  </div>
  `}
</HTMLBlock>

<h2>Test Cosmos in Postman</h2>
<p>Use the collections below to try gRPC calls against Tatum’s Cosmos gateway.</p>

<div class="tatum-postman-section">
  <h3>Cosmos Mainnet gRPC Postman collection</h3>

  <ol>
    <li><strong>Get your API key:</strong> Use your standard Tatum API key. For gRPC, this is passed via the <code>x-api-key</code> header (see <a href="#authentication-in-cosmos-grpc">Authentication</a> below).</li>
    <li><strong>Import the collection:</strong> Open Postman using the button below to access the Cosmos gRPC-over-HTTPS collection.</li>
    <li><strong>Configure variables:</strong> Set host and API key per the collection’s instructions</li>
    <li><strong>Start testing:</strong> Call standard Cosmos SDK methods (for example, <code>GetNodeInfo</code> or <code>AllBalances</code>) as provided in the collection.</li>
  </ol>

  <div class="tatum-postman-cta">
    <a class="tatum-btn tatum-postman" href="https://www.postman.com/blockchainnow/tatum-io/collection/69ce3ad9483a20e3fc590719/cosmos-mainnet-grpc" target="_blank" title="Run Cosmos Mainnet gRPC collection in Postman">▶️ Run gRPC in Postman</a>
  </div>
</div>

## Getting Started

### Set Up Your Environment

This guide uses **Node.js** with **macOS** to interact with the Cosmos gRPC gateway. Because gRPC is strictly typed, you must manage **.proto** files to define the communication contract.

1. **Install** `Node.js` (version 18+)
   ```shell
   brew install node
   node -v
   ```
2. **Install** `grpcurl`:\
   Highly recommended for smoke testing your endpoint and API key.
   ```shell
   brew install grpcurl
   ```
3. **Create your project and install dependencies**:
   ```shell
   mkdir tatum-cosmos-grpc && cd tatum-cosmos-grpc
   npm init -y
   npm install @grpc/grpc-js @grpc/proto-loader
   ```
4. **Set up Protobuf definitions**:\
   Cosmos gRPC requires service definitions. Create the directory structure in your home folder (`~`) or project root:
   ```shell
   # Create directory structure
   mkdir -p proto/cosmos/bank/v1beta1 \
            proto/cosmos/base/v1beta1 \
            proto/cosmos/base/query/v1beta1 \
            proto/cosmos/msg/v1 \
            proto/cosmos/query/v1 \
            proto/cosmos_proto \
            proto/google/api \
            proto/gogoproto \
            proto/amino

   # Download Core Bank definitions
   curl -s https://raw.githubusercontent.com/cosmos/cosmos-sdk/main/proto/cosmos/bank/v1beta1/query.proto > proto/cosmos/bank/v1beta1/query.proto
   curl -s https://raw.githubusercontent.com/cosmos/cosmos-sdk/main/proto/cosmos/bank/v1beta1/bank.proto > proto/cosmos/bank/v1beta1/bank.proto

   # Download Base, Msg, & Query dependencies
   curl -s https://raw.githubusercontent.com/cosmos/cosmos-sdk/main/proto/cosmos/base/v1beta1/coin.proto > proto/cosmos/base/v1beta1/coin.proto
   curl -s https://raw.githubusercontent.com/cosmos/cosmos-sdk/main/proto/cosmos/base/query/v1beta1/pagination.proto > proto/cosmos/base/query/v1beta1/pagination.proto
   curl -s https://raw.githubusercontent.com/cosmos/cosmos-sdk/main/proto/cosmos/msg/v1/msg.proto > proto/cosmos/msg/v1/msg.proto
   curl -s https://raw.githubusercontent.com/cosmos/cosmos-sdk/main/proto/cosmos/query/v1/query.proto > proto/cosmos/query/v1/query.proto

   # Download Third-party Metadata (Critical for resolution)
   curl -s https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/annotations.proto > proto/google/api/annotations.proto
   curl -s https://raw.githubusercontent.com/googleapis/googleapis/master/google/api/http.proto > proto/google/api/http.proto
   curl -s https://raw.githubusercontent.com/cosmos/gogoproto/main/gogoproto/gogo.proto > proto/gogoproto/gogo.proto
   curl -s https://raw.githubusercontent.com/cosmos/cosmos-proto/main/proto/cosmos_proto/cosmos.proto > proto/cosmos_proto/cosmos.proto
   curl -s https://raw.githubusercontent.com/cosmos/cosmos-sdk/main/proto/amino/amino.proto > proto/amino/amino.proto
   ```
5. **Verify your connection with** `grpcurl`:
   * **Tatum-specific**: The gRPC endpoint is `cosmos-mainnet-grpc.gateway.tatum.io:443` (Mainnet).
   * **Authentication**: uses the `x-api-key` header passed as metadata. Port **443** is required for SSL.
   ```shell
   grpcurl \
     -H "x-api-key: YOUR_API_KEY" \
     cosmos-mainnet-grpc.gateway.tatum.io:443 \
     cosmos.base.tendermint.v1beta1.Service/GetNodeInfo
   ```
   Expected response format:
   ```shell
   {
     "defaultNodeInfo": {
       "protocolVersion": {
         "p2p": "8",
         "block": "11"
       },
       "defaultNodeId": "0b8bf4c894418453cfeb45d57eec6036bb863cff",
       "listenAddr": "tcp://0.0.0.0:26656",
       "network": "cosmoshub-4",
       "version": "0.38.19",
       "channels": "QCAhIiMwOGBhAA==",
       "moniker": "ndl-archival-b@eu",
       "other": {
         "txIndex": "on",
         "rpcAddress": "tcp://0.0.0.0:26657"
       }
     },
   //[...]
   ```
   > 🚧 Attention
   >
   > * If you receive a JSON response containing node information, your endpoint and API key are working correctly.
   > * If this step fails, no amount of Node.js code will fix it. Confirm your environment setup and credentials.

### Quick start checklist

Before making your first production call, confirm:

* **Successful Smoke Test**: You can call `GetNodeInfo` successfully using `grpcurl` with the `x-api-key` header.
* **Full Dependency Chain**: Your `proto` folder contains `cosmos_proto`, `amino`, and `gogoproto` folders. Without these, the loader will fail on `ENOENT` errors.
* **SSL Configuration**: You are using `grpc.credentials.createSsl()` to connect via port **443** (non-TLS connections will be rejected).
* **Error Handling**: Your application handles gRPC-specific error codes (e.g., `Code 14: Unavailable` for network issues or `Code 16: Unauthenticated` for key issues).
* **Pro-Tip: Why all the files?** Cosmos Protobufs are modular. The Bank module imports the Base module, which in turn imports `cosmos_proto` for metadata and `amino` for legacy compatibility. The `@grpc/proto-loader` must have all these files locally to build the request "contract."

<h3 id="authentication-in-cosmos-grpc">Authentication in Node.js</h3>

1. Get the Cosmos gRPC URL
2. Get an <Anchor label="API Key" target="_blank" href="https://dashboard.tatum.io/api-keys">API Key</Anchor> from the Tatum Dashboard.
3. Configure your client with the endpoint and `x-api-key`:

```typescript
const grpc = require('@grpc/grpc-js');

const ENDPOINT = "cosmos-mainnet-grpc.gateway.tatum.io:443";
const API_KEY = "YOUR_API_KEY";

const meta = new grpc.Metadata();
meta.add('x-api-key', API_KEY);
```

***

## Example Requests

### Retrieve account balances

The following script opens a connection to the Bank module to query a wallet's current balances.

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

const PROTO_FILE = path.join(__dirname, 'proto/cosmos/bank/v1beta1/query.proto');

async function main() {
  const packageDefinition = protoLoader.loadSync(PROTO_FILE, {
    keepCase: true,
    longs: String,
    enums: String,
    defaults: true,
    oneofs: true,
    includeDirs: [path.join(__dirname, 'proto')]
  });

  const cosmosProto = grpc.loadPackageDefinition(packageDefinition).cosmos.bank.v1beta1;
  const client = new cosmosProto.Query('cosmos-mainnet-grpc.gateway.tatum.io:443', grpc.credentials.createSsl());

  const meta = new grpc.Metadata();
  meta.add('x-api-key', 'YOUR_API_KEY');

  const request = { address: "cosmos15480746979255644783" };

  client.AllBalances(request, meta, (err, response) => {
    if (err) {
      console.error("RPC Error:", err.message);
      return;
    }
    console.log("Balances:", JSON.stringify(response.balances, null, 2));
  });
}

main().catch(console.error);
```

### Retrieve all balances

Use this to fetch the total coin balance for an account across all denominations.

```javascript
const request = {
  "address": "cosmos1..."
};
```

### Retrieve staking delegations

Requires `cosmos/staking/v1beta1/query.proto`. Use this to monitor where an account has bonded its ATOM.

```javascript
const request = {
  "delegator_addr": "cosmos1..."
};
```

***

## Troubleshooting & Dependencies

Working with Cosmos gRPC in `Node.js` often involves managing a complex web of modular dependencies. If your script fails, it is likely due to one of the following:

1. **The** `ENOENT` **(Missing File) Loop**

   Because `.proto` files use `import` statements, loading a single file like `query.proto` triggers a chain reaction.

   * The Symptom: Error: `ENOENT: no such file or directory` pointing to `cosmos/msg/v1/msg.proto` or `pagination.proto`.
   * **The Cause**: One of the "hidden" dependencies required by the Bank module is missing from your local directory.
   * **The Fix**: Ensure your `proto` directory exactly matches the nested structure in the setup guide. If the loader asks for a new file, you must create the folder and `curl` the raw file from the official <Anchor label="Cosmos SDK GitHub" target="_blank" href="https://github.com/cosmos/cosmos-sdk">Cosmos SDK GitHub</Anchor>.
2. **Common Connection Issues**
   * **Auth failures**: Ensure the header name is exactly `x-api-key` and you are using the correct Mainnet/Testnet key.
   * **Port 443 & SSL**: Tatum requires SSL on port **443**. Insecure connections (standard on local nodes via port 9090) will be rejected. Always use `grpc.credentials.createSsl()`.
   * **Timeouts**: gRPC calls may require a `deadline`. Use `client.waitForReady()` to ensure the connection is established before querying.