# @stacks/network

> Library for Stacks network operations

Latest version **7.6.0** (published 2026-07-29) · MIT license · 0 weekly downloads

## Install

```sh
npm install @stacks/network
pnpm add @stacks/network
yarn add @stacks/network
bun add @stacks/network
```

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 7.6.0 |
| Published | 2026-07-29 |
| First published | 2020-09-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 2 |
| Unpacked size | 78 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 975 |
| Author | Hiro Systems PBC |
| Maintainers | blockstack-devops, stacks-foundation, jannik-stacks, rafa-stacks |
| Keywords | blockstack, network, stacks |

## Links

- npm: https://www.npmjs.com/package/@stacks/network
- Repository: https://github.com/stx-labs/stacks.js
- Homepage: https://hiro.so/stacks-js
- Issues: https://github.com/blockstack/blockstack.js/issues
- npm.io page: https://npm.io/package/@stacks/network

## Dependencies (2)

- [cross-fetch](https://npm.io/package/cross-fetch.md) ^3.1.5
- [@stacks/common](https://npm.io/package/@stacks/common.md) ^7.6.0

## Recent versions

- 7.6.0 (latest) — 2026-07-29
- 7.6.1-pr.1880.0 (pr) — 2026-09-16
- 7.4.1-beta.3 (beta) — 2026-05-22
- 7.0.0-next.89 (next) — 2024-10-25
- 6.12.2-nakamoto.0 (nakamoto) — 2024-03-21
- 4.4.0-stacks2.1-alpha.0 (alpha) — 2022-08-23
- 1.3.0-beta-1 (bns-2) — 2021-04-16
- 7.5.1-pr.1854.0 — 2026-07-13
- 7.5.0 — 2026-06-23
- 7.4.1-pr.1854.5 — 2026-06-21
- 7.4.1-pr.1854.4 — 2026-06-12
- 7.4.1-pr.1854.3 — 2026-06-02
- 7.4.1-pr.1854.2 — 2026-05-28
- 7.4.1-pr.1854.1 — 2026-05-27
- 7.4.1-pr.1854.0 — 2026-05-27
- … 668 more at https://npm.io/package/@stacks/network/versions

## README

# @stacks/network

Network and API library for working with Stacks blockchain nodes.

## Installation

```
npm install @stacks/network
```

## Usage

### Create a Stacks mainnet, testnet or mocknet network

```typescript
import { StacksMainnet, StacksTestnet, StacksMocknet } from '@stacks/network';

const network = new StacksMainnet();

const testnet = new StacksTestnet();

const mocknet = new StacksMocknet();
```

### Set a custom node URL

```typescript
const network = new StacksMainnet({ url: 'https://www.mystacksnode.com/' });
```

### Check if network is mainnet

```typescript
const isMainnet = network.isMainnet();
```

### Network usage in transaction building

```typescript
import { makeSTXTokenTransfer } from '@stacks/transactions';

const txOptions = {
  network,
  recipient: 'SP2BS6HD7TN34V8Z5BNF8Q2AW3K8K2DPV4264CF26',
  amount: new BigNum(12345),
  senderKey: 'b244296d5907de9864c0b0d51f98a13c52890be0404e83f273144cd5b9960eed01',
};

const transaction = await makeSTXTokenTransfer(txOptions);
```

### Use the built-in API key middleware

Some Stacks APIs make use API keys to provide less rate-limited plans.

```typescript
import { createApiKeyMiddleware, createFetchFn, StacksMainnet } from '@stacks/network';
import { broadcastTransaction, getNonce, makeSTXTokenTransfer } from '@stacks/transactions';

const myApiMiddleware = createApiKeyMiddleware('example_e8e044a3_41d8b0fe_3dd3988ef302');
const myFetchFn = createFetchFn(myApiMiddleware); // middlewares can be used to create a new fetch function
const myMainnet = new StacksMainnet({ fetchFn: myFetchFn }); // the fetchFn options can be passed to a StacksNetwork to override the default fetch function

const txOptions = {
  recipient: 'SP3FGQ8Z7JY9BWYZ5WM53E0M9NK7WHJF0691NZ159',
  amount: 12345n,
  senderKey: 'b244296d5907de9864c0b0d51f98a13c52890be0404e83f273144cd5b9960eed01',
  memo: 'some memo',
  anchorMode: AnchorMode.Any,
  network: myMainnet, // make sure to pass in the custom network object
};
const transaction = await makeSTXTokenTransfer(txOptions); // fee-estimation will use the custom fetchFn

const response = await broadcastTransaction(transaction, myMainnet); // make sure to broadcast via the custom network object

// stacks.js functions, which take a StacksNetwork object will use the custom fetchFn
const nonce = await getNonce('SP3FGQ8Z7JY9BWYZ5WM53E0M9NK7WHJF0691NZ159', myMainnet);
```

### Use custom middleware

Middleware can be used to hook into network calls before sending a request or after receiving a response.

```typescript
import { createFetchFn, RequestContext, ResponseContext, StacksTestnet } from '@stacks/network';
import { broadcastTransaction, getNonce, makeSTXTokenTransfer } from '@stacks/transactions';

const preMiddleware = (ctx: RequestContext) => {
  ctx.init.headers = new Headers();
  ctx.init.headers.set('x-foo', 'bar'); // override headers and set new `x-foo` header
};
const postMiddleware = (ctx: ResponseContext) => {
  console.log(await ctx.response.json()); // log response body as json
};

const fetchFn = createFetchFn({ pre: preMiddleware, post: preMiddleware }); // a middleware can contain `pre`, `post`, or both
const network = new StacksTestnet({ fetchFn });

// stacks.js functions, which take a StacksNetwork object will use the custom fetchFn
const nonce = await getNonce('SP3FGQ8Z7JY9BWYZ5WM53E0M9NK7WHJF0691NZ159', network);
```

### Get various API URLs

```typescript
const txBroadcastUrl = network.getBroadcastApiUrl();

const feeEstimateUrl = network.getTransferFeeEstimateApiUrl();

const address = 'SP2BS6HD7TN34V8Z5BNF8Q2AW3K8K2DPV4264CF26';
const accountInfoUrl = network.getAccountApiUrl(address);

const contractName = 'hello_world';
const abiUrl = network.getAbiApiUrl(address, contractName);

const functionName = 'hello';
const readOnlyFunctionCallUrl = network.getReadOnlyFunctionCallApiUrl(
  address,
  contractName,
  functionName
);

const nodeInfoUrl = network.getInfoUrl();

const blockTimeUrl = network.getBlockTimeInfoUrl();

const poxInfoUrl = network.getPoxInfoUrl();
```

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