HTTP client for the Aptos network API. Works standalone or as the transport layer for the Aptos TypeScript SDK.

• HTTP/2 — enabled by default on all platforms
• Multi-runtime — Node.js, Deno, Bun, browsers, and React Native
• Cookie jar — automatic cookie handling in Node, Deno, and Bun
• BCS support — bcsRequest() returns raw ArrayBuffer for binary-encoded responses

npm install @aptos-labs/aptos-client
# or
pnpm add @aptos-labs/aptos-client

import aptosClient from "@aptos-labs/aptos-client";

const { status, data } = await aptosClient<{ chain_id: number }>({
  url: "https://fullnode.mainnet.aptoslabs.com/v1",
  method: "GET",
});

import { jsonRequest, bcsRequest } from "@aptos-labs/aptos-client";

// JSON (same as default export)
const json = await jsonRequest<MyType>({ url, method: "GET" });

// BCS (returns ArrayBuffer)
const bcs = await bcsRequest({ url, method: "GET" });

The package uses conditional exports to select the right implementation for each runtime:

type AptosClientRequest = {
  url: string;
  method: "GET" | "POST";
  body?: unknown;
  params?: Record<string, string | number | bigint | boolean | undefined>;
  headers?: Record<string, string | undefined>;
  overrides?: { WITH_CREDENTIALS?: boolean };
  http2?: boolean;    // Node only — ignored elsewhere
  cookieJar?: CookieJarLike; // Per-request cookie isolation (Node & fetch only)
};

type AptosClientResponse<Res> = {
  status: number;
  statusText: string;
  data: Res;
  config?: any;
  request?: any;
  response?: any;
  headers?: Record<string, string | string[]>;
};

See src/types.ts for the full type definitions with documentation.

v4.1.0 returns to the same HTTP library v2 used (got) while keeping the v4 architecture (ESM, conditional exports, multi-runtime). For most callers the migration is one or two small edits.

If you are on v3.0.0 through v4.0.0, upgrade. Those versions silently return raw compressed bytes instead of parsed JSON whenever the origin sends content-encoding: br/gzip/deflate — which is what the Aptos fullnode and indexer do. 4.1.0 restores v2-era decompression behavior.

• http2: true default; falls back to H1.1 when the server doesn't support H2.
• Brotli / gzip / deflate decompression handled transparently.
• Cookie jar round-trips set-cookie and re-sends cookies on same-origin requests.
• bigint query params are stringified.
• 4xx / 5xx responses do not throw — inspect res.status.
• AptosClientResponse shape: { status, statusText, data, config, request, response, headers } with headers as a plain Record<string, string | string[]>.

• Per-request cookie jar isolation — pass cookieJar: new CookieJar() to keep multi-tenant requests from sharing cookie state.
• Public CookieJar is now exported (with RFC 6265 validation, expiry eviction, per-origin caps, and SameSite=None+Secure enforcement).
• CookieJarLike interface — bring your own jar (e.g. tough-cookie or a database-backed store).
• Conditional exports auto-select the right entry for Node / browser / Deno / Bun / Cloudflare Workers / Vercel Edge / React Native. v2 only shipped Node + browser.
• overrides.WITH_CREDENTIALS (browser entry) maps to fetch's credentials: "omit" | "include".

• CJS require() — the package is ESM-only since v4.0. Use import or await import(...).
• Re-export of got error types — if you handled RequestError / HTTPError directly, import them from got (it's still a direct dependency).
• Node < 22 — the minimum supported Node version is 22.

1. Using require()? → switch to import (or await import() from CJS).
2. Calling Buffer methods on a BCS response? → use new Uint8Array(res.data), new DataView(res.data), or wrap with Buffer.from(res.data).
3. Relying on automatic retries? → add an explicit retry wrapper. (Most consumers — including the Aptos TS SDK — don't need to.)
4. Node version < 22? → upgrade.

That's the full migration. Everything else either works the same, is additive, or is a fixed bug.

Releases are published to npm automatically via GitHub Actions whenever a GitHub release is created. The workflow lives in .github/workflows/publish.yml.

To release a new version:

1. Update the version in package.json (follows semver):

   npm version <major|minor|patch> --no-git-tag-version

2. Update CHANGELOG.md — move any notes under # Unreleased into a new section for the version being released.

3. Commit and push the version bump and changelog update to main:

   git add package.json CHANGELOG.md
   git commit -m "v<VERSION>"
   git push

4. Create a GitHub release with a tag that matches vMAJOR.MINOR.PATCH (e.g. v2.3.0). The tag must match the version in package.json — the publish workflow will fail otherwise. Pre-release tags like v2.3.0-beta.1 are also supported.

The publish workflow will then automatically:

• Validate that the tag matches the expected vMAJOR.MINOR.PATCH[-prerelease] pattern.
• Verify that the tag matches the version field in package.json.
• Install dependencies, build the package, and publish to npm with provenance.