• Public
  • Public/Protected
  • All

Package network


Network and API library for working with Stacks blockchain nodes.


npm install @stacks/network


Create a Stacks mainnet, testnet or mocknet network

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

const network = new StacksMainnet();

const testnet = new StacksTestnet();

const mocknet = new StacksMocknet();

Set a custom node URL

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

Check if network is mainnet

const isMainnet = network.isMainnet();

Network usage in transaction building

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

const txOptions = {
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.

import { createApiKeyMiddleware, createFetchFn, StacksMainnet } from '@stacks/network';
import { broadcastResponse, 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 broadcastResponse(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.

import { createFetchFn, RequestContext, ResponseContext, StacksTestnet } from '@stacks/network';
import { broadcastResponse, 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

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(

const nodeInfoUrl = network.getInfoUrl();

const blockTimeUrl = network.getBlockTimeInfoUrl();

const poxInfoUrl = network.getPoxInfoUrl();


Type Aliases

FetchFn: ((url: string, init?: RequestInit) => Promise<Response>)

Type declaration

    • (url: string, init?: RequestInit): Promise<Response>
    • Parameters

      • url: string
      • Optional init: RequestInit

      Returns Promise<Response>

StacksNetworkName: typeof StacksNetworks[number]


HIRO_MAINNET_DEFAULT: "https://stacks-node-api.mainnet.stacks.co" = 'https://stacks-node-api.mainnet.stacks.co'
HIRO_MOCKNET_DEFAULT: "http://localhost:3999" = 'http://localhost:3999'
HIRO_TESTNET_DEFAULT: "https://stacks-node-api.testnet.stacks.co" = 'https://stacks-node-api.testnet.stacks.co'
StacksNetworks: readonly ["mainnet", "testnet"] = ...

Network Functions

  • Creates a new middleware from an API key.

    const apiMiddleware = createApiKeyMiddleware("example_e8e044a3_41d8b0fe_3dd3988ef302");
    const fetchFn = createFetchFn(apiMiddleware);
    const network = new StacksMainnet({ fetchFn });

    createFetchFn, StacksNetwork


    Returns FetchMiddleware

  • Creates a new network fetching function, which combines an optional fetch-compatible library with optional middlware.

    const customFetch = createFetchFn(someMiddleware)
    const customFetch = createFetchFn(fetch, someMiddleware)
    const customFetch = createFetchFn(fetch, middlewareA, middlewareB)


    Returns FetchFn

  • Parameters

    Returns FetchFn

  • getFetchOptions(): RequestInit
  • Get fetch options

    Returns RequestInit

  • setFetchOptions(ops: RequestInit): RequestInit
  • Sets global fetch options for stacks.js network calls.


    Users can change the default referrer as well as other options when fetch is used internally by stacks.js:

    setFetchOptions({ referrer: 'no-referrer', referrerPolicy: 'no-referrer', ...otherRequestOptions });

    After calling setFetchOptions all subsequent network calls will use the specified options above.


    MDN Request: https://developer.mozilla.org/en-US/docs/Web/API/Request/Request




    • ops: RequestInit

    Returns RequestInit

    global fetch options after merging with previous options (or defaults)

Generated using TypeDoc