> ## Documentation Index
> Fetch the complete documentation index at: https://cosmos-docs-cosmjs-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# @cosmjs/json-rpc

> JSON-RPC 2.0 protocol implementation

JSON-RPC 2.0 protocol implementation used by `@cosmjs/tendermint-rpc` for HTTP and WebSocket RPC communication.

```bash theme={"system"}
npm install @cosmjs/json-rpc
```

## JsonRpcClient

Sends JSON-RPC requests over a generic messaging connection.

| Method        | Parameters                                                               | Returns                           |
| ------------- | ------------------------------------------------------------------------ | --------------------------------- |
| `constructor` | `connection: SimpleMessagingConnection<JsonRpcRequest, JsonRpcResponse>` | `JsonRpcClient`                   |
| `run`         | `request: JsonRpcRequest`                                                | `Promise<JsonRpcSuccessResponse>` |

```typescript theme={"system"}
interface SimpleMessagingConnection<Request, Response> {
  readonly responseStream: Stream<Response>;
  readonly sendRequest: (request: Request) => void;
}
```

`JsonRpcClient` uses the instantiation `SimpleMessagingConnection<JsonRpcRequest, JsonRpcResponse>`: the stream emits already-parsed responses, and `sendRequest` receives structured request objects (not strings).

## Parsing Functions

| Function                      | Parameters      | Returns                                                        |
| ----------------------------- | --------------- | -------------------------------------------------------------- |
| `parseJsonRpcResponse`        | `data: unknown` | `JsonRpcResponse`                                              |
| `parseJsonRpcSuccessResponse` | `data: unknown` | `JsonRpcSuccessResponse`                                       |
| `parseJsonRpcErrorResponse`   | `data: unknown` | `JsonRpcErrorResponse`                                         |
| `parseJsonRpcRequest`         | `data: unknown` | `JsonRpcRequest`                                               |
| `parseJsonRpcId`              | `data: unknown` | `JsonRpcId \| null` (returns `null` if no valid id is present) |

## Type Guards

| Function                   | Parameters                  | Returns                              |
| -------------------------- | --------------------------- | ------------------------------------ |
| `isJsonRpcSuccessResponse` | `response: JsonRpcResponse` | `response is JsonRpcSuccessResponse` |
| `isJsonRpcErrorResponse`   | `response: JsonRpcResponse` | `response is JsonRpcErrorResponse`   |

```typescript theme={"system"}
import { parseJsonRpcResponse, isJsonRpcErrorResponse } from "@cosmjs/json-rpc";

const response = parseJsonRpcResponse(data);

if (isJsonRpcErrorResponse(response)) {
  console.error("RPC error:", response.error.message);
} else {
  console.info("Result:", response.result);
}
```

## ID Generation

| Function        | Parameters | Returns                              |
| --------------- | ---------- | ------------------------------------ |
| `makeJsonRpcId` | —          | `number` (assignable to `JsonRpcId`) |

## Key Types

### JsonRpcRequest

```typescript theme={"system"}
interface JsonRpcRequest {
  readonly jsonrpc: "2.0";
  readonly id: JsonRpcId;
  readonly method: string;
  readonly params: JsonCompatibleArray | JsonCompatibleDictionary;
}
```

### JsonRpcSuccessResponse

```typescript theme={"system"}
interface JsonRpcSuccessResponse {
  readonly jsonrpc: "2.0";
  readonly id: JsonRpcId;
  readonly result: any;
}
```

### JsonRpcErrorResponse

```typescript theme={"system"}
interface JsonRpcErrorResponse {
  readonly jsonrpc: "2.0";
  readonly id: JsonRpcId | null;
  readonly error: JsonRpcError;
}
```

### JsonRpcError

```typescript theme={"system"}
interface JsonRpcError {
  readonly code: number;
  readonly message: string;
  readonly data?: JsonCompatibleValue;
}
```

### JsonRpcId

```typescript theme={"system"}
type JsonRpcId = number | string;
```

### JsonRpcResponse

```typescript theme={"system"}
type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
```

## Error Codes

The `jsonRpcCode` object provides standard JSON-RPC 2.0 error codes:

| Code   | Constant                          | Description                                                                          |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------ |
| -32700 | `parseError`                      | Invalid JSON                                                                         |
| -32600 | `invalidRequest`                  | JSON is not a valid request                                                          |
| -32601 | `methodNotFound`                  | Method does not exist                                                                |
| -32602 | `invalidParams`                   | Invalid method parameters                                                            |
| -32603 | `internalError`                   | Internal JSON-RPC error                                                              |
| -32000 | `jsonRpcCode.serverError.default` | Server error (default slot of the `-32000` to `-32099` implementation-defined range) |