createNetwork

Creates a customized StacksNetwork object from a base network. Supports configuring a custom API key, custom base URL, and custom fetch function. Returns a deep copy — the original network constants are never mutated.

---

Usage

Basic usage

import { createNetwork } from '@stacks/network';

// From a network name string
const network = createNetwork('mainnet');

// From a network constant
import { STACKS_TESTNET } from '@stacks/network';
const network = createNetwork(STACKS_TESTNET);

With an API key

import { createNetwork } from '@stacks/network';

const network = createNetwork('testnet', 'my-hiro-api-key');

With an options object

import { createNetwork } from '@stacks/network';

const network = createNetwork({
  network: 'mainnet',
  apiKey: 'my-hiro-api-key',
});

With custom API key options

import { createNetwork } from '@stacks/network';

const network = createNetwork({
  network: 'mainnet',
  apiKey: 'my-api-key',
  host: /\.example\.com$/,       // default: /(.*)api(.*)(\.stacks\.co|\.hiro\.so)$/i
  httpHeader: 'x-custom-api-key', // default: 'x-api-key'
});

With custom client options

import { createNetwork, STACKS_TESTNET } from '@stacks/network';

const network = createNetwork({
  network: STACKS_TESTNET,
  client: {
    baseUrl: 'https://custom-api.example.com',
    fetch: customFetchFunction,
  },
});

Notes

• Always returns a deep copy of the base network — the original constants (STACKS_MAINNET, etc.) are never modified.

• When an apiKey is provided, it creates an API key middleware that attaches the key as an HTTP header to matching requests.

• The default host pattern for the API key middleware matches Hiro-hosted APIs (*.stacks.co, *.hiro.so).

Reference Link

---

Signature

function createNetwork(network: StacksNetworkName | StacksNetwork): StacksNetwork;

function createNetwork(
  network: StacksNetworkName | StacksNetwork,
  apiKey: string
): StacksNetwork;

function createNetwork(options: {
  network: StacksNetworkName | StacksNetwork;
  client?: ClientOpts;
  apiKey?: string;
  host?: RegExp | string;
  httpHeader?: string;
}): StacksNetwork;

---

Returns

StacksNetwork

A new StacksNetwork object with the specified customizations applied.

---

Parameters

The function has three overloaded call signatures:

Overload 1: Network only

Parameter	Type	Description
network	StacksNetworkName | StacksNetwork	The base network to clone.

Overload 2: Network + API key

Parameter	Type	Description
network	StacksNetworkName | StacksNetwork	The base network to clone.
apiKey	string	API key added as an HTTP header to matching requests.

Overload 3: Options object

Property	Type	Required	Description
network	StacksNetworkName | StacksNetwork	Yes	The base network to clone.
client	ClientOpts	No	Custom client with baseUrl and/or fetch.
apiKey	string	No	API key for the middleware.
host	RegExp | string	No	Host pattern the API key header applies to. Default: /(.*)api(.*)(\.stacks\.co|\.hiro\.so)$/i.
httpHeader	string	No	HTTP header name for the API key. Default: 'x-api-key'.