README.mdx

title	@alchemy/common
description	Overview of common
slug	wallets/reference/common
layout	reference

{/* This file is auto-generated by TypeDoc. Do not edit manually. */}

This is a low-level package that is consumed by other Alchemy packages.

Installation

npm install @alchemy/common viem

Key Exports

• alchemyTransport - viem-compatible HTTP transport for Alchemy APIs (supports API key, JWT, or direct URL auth)
• Chain registry - getAlchemyRpcUrl, isChainSupported, getSupportedChainIds
• Custom chain definitions (via @alchemy/common/chains) - chains not yet in viem
• AlchemyRestClient - typed REST client for non-JSON-RPC Alchemy APIs
• Error classes - BaseError, ChainNotFoundError, AccountNotFoundError, ConnectionConfigError, etc.
• Logging - createLogger, setGlobalLoggerConfig, LogLevel
• Utilities - bigIntMultiply, bigIntMax, lowerAddress, assertNever

Usage

import { alchemyTransport } from "@alchemy/common";
import { sepolia } from "viem/chains";
import { createPublicClient } from "viem";

const client = createPublicClient({
  chain: sepolia,
  transport: alchemyTransport({ apiKey: "YOUR_API_KEY" }),
});

License

MIT

Classes

Class	Description
AccountNotFoundError	This error is thrown when an account could not be found to execute a specific action. It extends the BaseError class.
AlchemyApiError	The normalized error family for Alchemy API failures. Both the REST channel (AlchemyRestClient → ServerError/FetchError, which extend this class) and SDK JSON-RPC actions surface failures as AlchemyApiError, so consumers can handle status/code/requestId/retryAfter uniformly:
AlchemyRestClient	A client for making requests to Alchemy's non-JSON-RPC endpoints, with typed routes/bodies/queries (via a RestRequestSchema), bounded retries with exponential backoff (429/5xx/network only, honoring Retry-After), per-attempt timeouts, abort support, and a per-request idempotency id sent as X-Alchemy-Client-Request-Id and surfaced on thrown errors.
BaseError	A custom error class that extends from ViemBaseError. This class allows for error messages to include links to relevant documentation based on provided docsPath and docsSlug parameters. This is based on on viem's BaseError type (obviously from the import and extend) we want the errors here to point to our docs if we supply a docsPath though
ChainNotFoundError	Error class representing a "Chain Not Found" error, typically thrown when no chain is supplied to the client.
ConnectionConfigError	Error class for connection configuration validation failures.
FetchError	Error class representing a "Fetch Error" error, typically thrown when a fetch request fails.
InvalidRequestError	This error is thrown when an invalid request is made. It extends the BaseError class.
MethodUnsupportedError	This error is thrown when an unknown method is called. It extends the BaseError class.
ServerError	Error class representing a "Server Error" error, typically thrown when a server request fails.

Interfaces

Interface	Description
AlchemyTransportConfig	Configuration options for the Alchemy transport. Extends viem's HttpTransportConfig with Alchemy-specific options while omitting options that are not relevant or supported by Alchemy.

Type Aliases

Type Alias	Description
AlchemyApiErrorDetails	Normalized failure metadata shared across REST and JSON-RPC channels.
AlchemyConnectionConfig	TypeScript type derived from the schema for external consumption. This provides clean type inference without exposing Zod implementation details.
AlchemyNetwork	An Alchemy network identifier. Known slugs get autocomplete; arbitrary strings are accepted as an escape hatch so new networks work without an SDK release.
AlchemyRestClientParams	Parameters for creating an AlchemyRestClient instance.
AlchemyTransport	-
ExtractRpcMethod	-
KnownAlchemyNetwork	Known Alchemy network slugs for autocomplete.
NetworkInput	Any accepted network input: a viem Chain, an Alchemy network slug (e.g. "eth-mainnet"), or a CAIP-2 identifier (e.g. "eip155:1", "solana:mainnet").
Never	-
QueryParams	A query-params object; array values serialize as repeated keys.
QueryValue	Values the query serializer accepts (null/undefined entries are skipped).
ResolvedNetwork	A resolved network: the Alchemy slug used for URL construction and REST payloads, plus the numeric chain ID when one exists (EVM only).
RestRequestFn	-
RestRequestOptions	Per-request runtime options; values override the client-level defaults.
RestRequestParams	-
RestRequestSchema	-

Variables

Variable	Description
AlchemyConnectionConfigSchema	Main connection configuration allowing flexible combinations. Can specify URL, auth method, or both together.

Functions

Function	Description
alchemyTransport	Creates an Alchemy HTTP transport for connecting to Alchemy's services.
assertNever	Asserts that a value is never.
bigIntMax	Returns the max bigint in a list of bigints
bigIntMultiply	Given a bigint and a number (which can be a float), returns the bigint value. Note: this function has loss and will round down to the nearest integer.
composeSignals	Combines multiple abort signals into one that aborts when any input aborts. Uses AbortSignal.any where available, with an addEventListener fallback.
getAlchemyRpcUrl	Gets the Alchemy RPC base URL for a given chain ID.
getSupportedChainIds	Gets all supported chain IDs from the registry.
isAlchemyConnectionConfig	Type guard to check if a value is a valid Alchemy connection config.
isAlchemyTransport	A type guard for the transport to determine if it is an Alchemy transport. Used in cases where we would like to do switching depending on the transport.
isChainSupported	Checks if a chain ID is supported by the Alchemy RPC registry.
lowerAddress	Lowercase an address
raise	Raises an error.
resolveNetwork	Resolves any accepted network input — viem Chain, Alchemy network slug, or CAIP-2 identifier — to the Alchemy network slug (and chain ID when one exists). All three forms resolve against the same daikon-generated registry.
sleep	Waits for a duration, rejecting immediately with the signal's reason if the signal aborts first.
validateAlchemyConnectionConfig	Validates an Alchemy connection configuration object.