RPC Client Interface

CosmJS communicates with Cosmos SDK chains through Tendermint/CometBFT RPC. The transport layer sits between the high-level clients (StargateClient, CosmWasmClient) and the blockchain node, handling request encoding, response parsing, connection management, and event subscriptions. All transports implement the same RpcClient interface from @cosmjs/tendermint-rpc, so the upper layers are transport-agnostic.

RpcClient & RpcStreamingClient

Every transport implements at least RpcClient:

interface RpcClient {
  readonly execute: (request: JsonRpcRequest) => Promise<JsonRpcSuccessResponse>;
  readonly disconnect: () => void;
}

Transports that support event subscriptions additionally implement RpcStreamingClient:

interface RpcStreamingClient extends RpcClient {
  readonly listen: (request: JsonRpcRequest) => Stream<SubscriptionEvent>;
}

You can check at runtime with instanceOfRpcStreamingClient(client).

Automatic Transport Selection

When you call StargateClient.connect(endpoint) or connectComet(endpoint), the transport is selected based on the URL protocol:

Endpoint	Transport
`http://...` or `https://...`	`HttpClient`
`ws://...` or `wss://...`	`WebsocketClient`
`HttpEndpoint` object	`HttpClient` (always)

// HTTP transport (default for most use cases)
const client = await StargateClient.connect("https://rpc.my-chain.network");

// WebSocket transport (needed for subscriptions)
const client = await StargateClient.connect("wss://rpc.my-chain.network");

Manual Transport Configuration

The automatic connect() methods don’t expose transport-level options like timeouts or batching. For full control, construct the RPC client manually and pass it through the create() factory:

import { StargateClient } from "@cosmjs/stargate";
import { Comet38Client, HttpClient } from "@cosmjs/tendermint-rpc";

// HTTP with 15-second timeout
const rpcClient = new HttpClient("https://rpc.my-chain.network", 15_000);
const cometClient = Comet38Client.create(rpcClient);
const client = StargateClient.create(cometClient);

import { StargateClient } from "@cosmjs/stargate";
import { Comet38Client, HttpBatchClient } from "@cosmjs/tendermint-rpc";

// Batched HTTP with custom options
const rpcClient = new HttpBatchClient("https://rpc.my-chain.network", {
  batchSizeLimit: 10,
  dispatchInterval: 50,
  httpTimeout: 15_000,
});
const cometClient = Comet38Client.create(rpcClient);
const client = StargateClient.create(cometClient);

When using manual transport configuration, you need to know the CometBFT version of your target chain. Use Comet38Client for CometBFT 0.38, Comet1Client for CometBFT 1.x, or Tendermint37Client for Tendermint 0.37. If you’re not sure, use connectComet() for auto-detection — though this only accepts an endpoint string or HttpEndpoint, not a pre-built RPC client.

Package Summary

Package	Role
`@cosmjs/tendermint-rpc`	RPC client implementations (`HttpClient`, `HttpBatchClient`, `WebsocketClient`) and CometBFT client wrappers
`@cosmjs/json-rpc`	JSON-RPC 2.0 types, parsing, and ID generation
`@cosmjs/socket`	WebSocket wrapper with reconnection, queueing, and connection status
`@cosmjs/stream`	Reactive stream utilities (xstream-based)

CosmJS

Concepts

Guides

API Reference

RpcClient & RpcStreamingClient

Automatic Transport Selection

Manual Transport Configuration

Package Summary

​RpcClient & RpcStreamingClient

​Automatic Transport Selection

​Manual Transport Configuration

​Package Summary

RpcClient & RpcStreamingClient

Automatic Transport Selection

Manual Transport Configuration

Package Summary