JavaScript SDK

The official Node.js client for SpaceRouter Proxy. Promise-based API, TypeScript types included.

Install

npm install @spacenetwork/spacerouter

Requires Node.js 18 or later. Browser and Bun support are on the roadmap.

SPACE-payment example

import { SpaceRouter, SpaceRouterSPACE } from "@spacenetwork/spacerouter";

const payment = new SpaceRouterSPACE({
  gatewayMgmtUrl: "https://gateway.spacerouter.org",
  wallet,                                          // your ClientPaymentWallet
});

const router = new SpaceRouter("0xYOUR_WALLET_ADDRESS", {
  gatewayUrl: "https://gateway.spacerouter.org",
  payment,
  region: "KR",
  ipType: "residential",
});

const response = await router.get("https://httpbin.org/ip");
console.log(await response.json());
router.close();

The first positional argument is the consumer's wallet address (lowercase 0x-hex). The payment helper signs the per-request EIP-191 challenge that the gateway requires.

Constructor

new SpaceRouter(payerAddress: string, options: {
  gatewayUrl?: string;             // default: "https://gateway.spacerouter.org"
  payment: SpaceRouterSPACE;       // required — signs per-request challenges
  protocol?: "http";               // "http" only — socks5 not supported in v1.5+
  region?: string;                 // 2-letter ISO country code
  ipType?: "residential" | "mobile" | "business" | "hosting";
  timeout?: number;                // default: 30000 (ms)
})

Methods

await router.request(method, url, options?)
await router.get(url, options?)
await router.post(url, options?)
await router.put(url, options?)
await router.patch(url, options?)
await router.delete(url, options?)
await router.head(url, options?)

// Per-request routing override
const krRouter = router.withRouting({ region: "KR", ipType: "residential" });

// Always close when done
router.close();

options accepts headers, body, and an AbortSignal:

const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 5000);

const r = await router.post("https://api.example.com/v1/items", {
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ name: "widget" }),
  signal: ctrl.signal,
});

The response object

interface ProxyResponse {
  status: number;
  headers: Record<string, string>;
  body: ReadableStream;
  text(): Promise<string>;
  json(): Promise<unknown>;
  nodeId: string;  // ID of the Provider that served this request
}

Errors

All errors extend SpaceRouterError:

Class	HTTP	Raised when
AuthenticationError	407	Payment headers missing or challenge signature rejected.
QuotaExceededError	402	Escrow balance below the request's price, or legacy Proxy-Authorization: Basic detected (api_key_auth_deprecated).
RateLimitError	429	Rate limited. Has retryAfter.
NoNodesAvailableError	503	No Provider matches your region/type filter.
UpstreamError	502	Provider couldn't reach the target site.

import { NoNodesAvailableError } from "@spacenetwork/spacerouter";

try {
  await router.get("https://httpbin.org/ip");
} catch (err) {
  if (err instanceof NoNodesAvailableError) {
    console.log("No matching nodes — try another region");
  } else {
    throw err;
  }
}

Pay with SPACE

The JavaScript SDK uses on-chain SPACE payment as its only auth mechanism — every request constructed via SpaceRouter is paid per byte from the consumer's escrow balance. See the Pay with SPACE guide for the wallet/escrow setup, the protocol details, and the matching Python reference implementation.