CosmJS provides two HTTP-based transports for communicating with CometBFT RPC nodes: HttpClient for single requests and HttpBatchClient for batching multiple queries into one round-trip.
HttpClient
HttpClient is the default transport for http:// and https:// endpoints. It
sends one JSON-RPC POST request per execute() call using the platform’s
fetch API.
Basic Usage
Pass an HttpEndpoint object to attach headers (e.g. API keys) to every
request:
Timeout
An optional second argument sets the request timeout in milliseconds. When set,
the underlying fetch call uses AbortSignal.timeout() to abort if the server
doesn’t respond in time:
If omitted, requests have no timeout (they rely on the runtime’s default
behavior).
How It Works Internally
execute() serializes the JsonRpcRequest to JSON.- A
POST request is sent via fetch with Content-Type: application/json
and any custom headers.
- HTTP status >= 400 throws an error with the status code and response body.
- The JSON body is parsed with
parseJsonRpcResponse() from @cosmjs/json-rpc.
- JSON-RPC error responses throw with the error object.
disconnect() is a no-op — there is no persistent connection to close.
Limitations
- No subscriptions.
HttpClient implements RpcClient only, not
RpcStreamingClient. You cannot subscribe to events (new blocks,
transactions) over HTTP.
- No retry logic. Failed requests throw immediately. Implement retries in
your application if needed.
HttpBatchClient
HttpBatchClient groups multiple execute() calls into a single
JSON-RPC batch request. This
reduces HTTP overhead when you need to make many queries in a short time.
Basic Usage
Options
How Batching Works
When you call execute(), the request is queued internally. The queue is
flushed (sent as a single HTTP POST) when either condition is met:
- The queue reaches
batchSizeLimit — dispatched immediately.
- The
dispatchInterval timer fires — dispatched on the next tick.
Each request in the batch gets its own Promise. The batch response is an array
of JSON-RPC responses; each is matched to its original request by id and the
corresponding Promise is resolved or rejected.
When to Use It
Batching is useful when your application makes many independent queries in rapid
succession — for example, fetching balances for a list of addresses or querying
multiple contract states. Instead of N separate HTTP round-trips, you get one.
connectComet() and the high-level StargateClient.connect() don’t use batching by default. To enable it, create the batch client manually and pass it to the CometBFT client’s create() method, then pass that to StargateClient.create().
