# @stacks/rpc-client

> Typed JavaScript/TypeScript client for Stacks core RPC endpoints.

Latest version **2.0.1** (published 2026-04-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @stacks/rpc-client
pnpm add @stacks/rpc-client
yarn add @stacks/rpc-client
bun add @stacks/rpc-client
```

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.1 |
| Published | 2026-04-24 |
| First published | 2020-10-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=22 |
| Dependencies | 1 |
| Unpacked size | 311 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 0 |
| Maintainers | ablankstein, blockstack-devops, stacks-foundation, jannik-stacks, rafa-stacks |

## Links

- npm: https://www.npmjs.com/package/@stacks/rpc-client
- Repository: https://github.com/stx-labs/stacks-core-rpc-client
- Homepage: https://github.com/stx-labs/stacks-core-rpc-client#readme
- Issues: https://github.com/stx-labs/stacks-core-rpc-client/issues
- npm.io page: https://npm.io/package/@stacks/rpc-client

## Dependencies (1)

- [openapi-fetch](https://npm.io/package/openapi-fetch.md) ^0.14.0

## Recent versions

- 2.0.1 (latest) — 2026-04-24
- 2.0.0 — 2026-04-23
- 0.8.18 — 2021-04-27
- 0.8.17 — 2021-04-27
- 0.8.16-alpha.c9a9a89.0 — 2021-04-27
- 0.8.16-alpha.6513a9a.0 — 2021-04-23
- 0.8.16-alpha.d98f6ed.0 — 2021-04-21
- 0.8.16-alpha.ed96f37.0 — 2021-04-19
- 0.8.16-alpha.7de75b0.0 — 2021-04-19
- 0.8.16-alpha.139647e.0 — 2021-04-06
- 0.8.16-alpha.71d36ee.0 — 2021-04-06
- 0.8.16-alpha.8e6c40b.0 — 2021-04-06
- 0.8.16-alpha.4306f7b.0 — 2021-04-06
- 0.8.16-alpha.a457fd8.0 — 2021-04-06
- 0.8.16-alpha.1818252.0 — 2021-04-06
- … 300 more at https://npm.io/package/@stacks/rpc-client/versions

## README

# @stacks/rpc-client

Typed JavaScript/TypeScript client for the Stacks core RPC API.

This package is generated from the Stacks core OpenAPI definition and ships as ESM-first with CJS compatibility.

## Install

```bash
npm install @stacks/rpc-client
```

## Runtime and Development Targets

- Runtime support: Node `>=22`
- Local development baseline: Node `24`

## Quick Start

```ts
import { createCoreRpcClient } from "@stacks/rpc-client";

const client = createCoreRpcClient({
  baseUrl: "http://localhost:20443",
  authToken: process.env.STACKS_RPC_AUTH_TOKEN,
});

const info = await client.request("GET", "/v2/info");
console.log(info.stacks_tip_height);
```

## Usage with `@stacks/network`

`createCoreRpcClient` accepts a `@stacks/network` instance directly, so you can
reuse an existing network configuration without duplicating the base URL or
custom fetch:

```ts
import { createCoreRpcClient } from "@stacks/rpc-client";
import { STACKS_TESTNET } from "@stacks/network";

const client = createCoreRpcClient(STACKS_TESTNET);
const info = await client.request("GET", "/v2/info");
```

A second `overrides` argument lets you layer on options like `authToken` while
still deriving everything else from the network:

```ts
const client = createCoreRpcClient(STACKS_TESTNET, {
  authToken: process.env.STACKS_RPC_AUTH_TOKEN,
});
```

## Custom Headers

Use the `headers` option to attach an API key or any other custom headers to
every outgoing request:

```ts
const client = createCoreRpcClient({
  baseUrl: "https://api.hiro.so",
  headers: {
    "x-api-key": process.env.STACKS_API_KEY,
  },
});
```

This also works alongside `@stacks/network`:

```ts
const client = createCoreRpcClient(STACKS_TESTNET, {
  headers: { "x-api-key": process.env.STACKS_API_KEY },
});
```

## Example RPC Calls

Every call through `client.request()` is fully typed — the path autocompletes
and the return type matches the OpenAPI schema.

### Get node info

```ts
const info = await client.request("GET", "/v2/info");
// info is typed as NodeInfo
console.log(info.stacks_tip_height, info.burn_block_height);
```

### Get PoX details

```ts
const pox = await client.request("GET", "/v2/pox");
// pox is typed as PoxInfo
console.log(pox.reward_cycle_length, pox.next_cycle);
```

### Fetch account data

```ts
const account = await client.request("GET", "/v2/accounts/{address}", {
  params: { path: { address: "SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7" } },
});
// account is typed as AccountData
console.log(account.balance, account.nonce);
```

### Call a read-only contract function (authenticated)

```ts
const result = await client.request(
  "POST",
  "/v2/contracts/call-read/{deployer_address}/{contract_name}/{function_name}",
  {
    params: {
      path: {
        deployer_address: "SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7",
        contract_name: "my-contract",
        function_name: "get-balance",
      },
    },
    body: { sender: "SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7", arguments: [] },
  },
);
// result is typed as ReadOnlyFunctionResult
console.log(result.okay, result.result);
```

## Using Exported Types

All response schemas are re-exported as named types so you can annotate your own
code without reaching into the generated schema:

```ts
import type { NodeInfo, PoxInfo, AccountData } from "@stacks/rpc-client";

function summarize(info: NodeInfo, pox: PoxInfo): string {
  return `tip=${info.stacks_tip_height} cycle=${pox.reward_cycle_id}`;
}
```

You can also derive the response type for any endpoint using `CoreRpcResponse`:

```ts
import type { CoreRpcResponse } from "@stacks/rpc-client";

type PoxResponse = CoreRpcResponse<"GET", "/v2/pox">;
```

## Error Handling

Failed requests throw a `CoreRpcError` with structured metadata:

```ts
import { CoreRpcError, createCoreRpcClient } from "@stacks/rpc-client";

const client = createCoreRpcClient();

try {
  await client.request("POST", "/v3/block_proposal", { body: {} });
} catch (error) {
  if (error instanceof CoreRpcError) {
    console.error(error.status); // HTTP status code
    console.error(error.url);    // request URL
    console.error(error.details); // parsed error body
  }
}
```

## Auth Behavior

`authToken` is attached to the `authorization` header only for RPC endpoints
that declare `rpcAuth` in the spec.

## Raw Client Access

When you need full control over the response (headers, streaming, middleware),
use `client.raw` — the underlying `openapi-fetch` client:

```ts
const { data, error, response } = await client.raw.GET("/v2/info");
console.log(response.headers.get("x-request-id"));
```

## Usage (CJS)

```js
const { createCoreRpcClient } = require("@stacks/rpc-client");

const client = createCoreRpcClient({
  baseUrl: "http://localhost:20443",
});

client.request("GET", "/v2/info").then(console.log);
```

## Generation Workflow

Types are generated by `openapi-typescript` from a pinned upstream URL:

- `https://raw.githubusercontent.com/stacks-network/stacks-core/d7f37b5388b490427d6705e17a9b016aee8fccb0/docs/rpc/openapi.yaml`

Commands:

```bash
npm run generate
npm run generate:check
```

`generate:check` fails when checked-in generated output is stale.

## Scripts

```bash
npm run typecheck
npm test
npm run build
npm pack --dry-run
```

## Generator Alternatives

- `openapi-typescript` + `openapi-fetch` (current choice): minimal runtime, high type safety, flexible wrapper layer.
- OpenAPI Generator `typescript-fetch`: fuller generated SDK surface, but heavier and more verbose output.
- Orval: useful when you want opinionated API client generation (often frontend-focused workflows).

---
_Source: https://npm.io/package/@stacks/rpc-client · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._