Client configuration

PolyesterClient

new PolyesterClient(config: PolyesterClientConfig)

Properties: one lazy getter per service (auth, accounts, apiKeys, subaccounts, candles, chainAnalytics, marketData, marketOverview, orderbook, heatmap, lifecycle, trades, orders, triggers, balances, transfers, internalTransfers, tradingWithdraws, autoWithdraw, deposit, addressBook, guardSigner, socialVerification, zipper, mfa, claims, checkpoints, changelog, rewards, vip, fees, tradingRateLimits), plus realtime (the shared RealtimeClient) and catalog (the ClientCatalog).

The constructor validates configuration at runtime. Invalid environments, unsupported wire formats, a non-function fetch, or combining catalog with catalogSnapshot or catalogCell throw ConfigurationError.

Tree-shakable cores

Each client has a core that takes the same config and wires transports, realtime, the catalog, and auth, without a getter for the other services:

Reach a service through its accessor in @polyester/sdk/services/<name>, so a bundle only includes the services it calls:

import { PolyesterCore, POLYESTER_TESTNET_ENVIRONMENT } from "@polyester/sdk";
import { marketOverviewService } from "@polyester/sdk/services/market-overview";

const core = new PolyesterCore({ environment: POLYESTER_TESTNET_ENVIRONMENT });
const { markets } = await marketOverviewService(core).list({ limit: 5 });

An accessor creates its service on first use and returns the same instance afterwards. The full clients are the cores plus a getter per accessor, so client.orders === ordersService(client). The browser and server cores keep their own members (setAccountSigner, session, verifySession(), and the rest).

Each subpath exports one accessor named after the client getter plus Service (ordersService, addressBookService): accounts, address-book, api-keys, auto-withdraw, balances, candles, chain-analytics, changelog, checkpoints, claims, deposit, fees, guard-signer, heatmap, internal-transfers, lifecycle, market-data, market-overview, mfa, orderbook, orders, rate-limits (tradingRateLimitsService), rewards, social-verification, subaccounts, trades, trading-withdraws, transfers, triggers, vip, and zipper.

Auth providers

interface JwtAuthProvider {
	kind: "jwt";
	getToken: () => string | null | Promise<string | null>;
}

interface ApiKeyEd25519AuthProvider {
	kind: "api-key-ed25519";
	getKeyId: () => string | null | Promise<string | null>;
	getSecretKey: () => Uint8Array | null | Promise<Uint8Array | null>; // 32-byte secret
}

The SDK reads getToken() for every HTTP request and realtime authentication check. Keep it cheap and return the current credential, including null after logout.

PolyesterBrowserClient

new PolyesterBrowserClient(config: PolyesterBrowserClientConfig)

Extends the base config (minus auth, which it manages) with:

Additional members: auth is narrowed to AccountSignerAuthService (login/logout/sessions/events, see the Auth reference), and setAccountSigner(signer | null) swaps the signer at runtime.

Token storage implementations:

createMemoryAuthTokenStorage(initialToken?)
createCookieAuthTokenStorage({ cookieName?, path?, secure?, sameSite? })

On public hosts, cookie names stay stable. Browser storage scopes the bearer and display-session cookies by port on loopback, .localhost, and RFC1918 private IPv4 hosts, including default HTTP (80) and HTTPS (443) ports, so local and LAN apps cannot read or overwrite each other's sessions.

PolyesterServerClient

new PolyesterServerClient(config: PolyesterServerClientConfig)

Extends the base config with:

Members: session, hasAuthProvider, hasBearerToken, hasUsableBearerToken, hasDisplaySession, and verifySession(): Promise<Me | null>, where null means unauthenticated and every other failure throws.

Factories

createPolyesterServerClientFromRequest({ environment, request, ...baseOptions });
createPolyesterServerClientFromCookies({ environment, cookies, ...baseOptions });

Both parse the session cookies, attach a JWT provider when a valid bearer token is present, and return a configured PolyesterServerClient. baseOptions are interceptors, realtime, wireFormat, fetch, catalog, catalogSnapshot, catalogCell, transports, and realtimeClient. createPolyesterServerCoreFromRequest and createPolyesterServerCoreFromCookies take the same parameters and return a PolyesterServerCore. cookies may be a Request, a string record, or a synchronous .get(name) store returning a string or { value: string }; await asynchronous framework helpers before passing their store. A Request derives the cookie location from its URL. For a local framework store, pass cookieLocation with its hostname, port, and protocol so the factory reads the matching port-scoped bearer and display cookies. parseSessionCookie(cookies, environment, { cookieLocation?, tokenCookieName? }) lives in @polyester/sdk/server-session and returns the bearerToken alongside display data. The root export provides POLYESTER_AUTH_TOKEN_COOKIE_NAME and POLYESTER_SESSION_COOKIE_NAME. Both server factories accept tokenCookieName when browser token storage uses a custom cookieName; pass its base name, without a port suffix. The root helper resolveAuthCookieName(name, location?) computes the matching name from an AuthCookieLocation (hostname, port, protocol), defaulting to the browser location when available. On a server, supply the location for local requests. Local ports default to 80 for HTTP and 443 for HTTPS; local reads do not fall back to unsuffixed cookies.

The display-session base name is polyester_session_4; use the constant rather than hard-coding its name. Version 4 resets display sessions created with the previous fingerprint format.

Request options

Every service method takes an options object as its last parameter:

interface PolyesterRequestOptions {
	signal?: AbortSignal; // cancel the request
	timeoutMs?: number; // call deadline; rejects with TimeoutError when it passes
}

interface PolyesterMutationOptions extends PolyesterRequestOptions {
	stepUpToken?: string | null; // MFA fresh step-up proof (sent as X-Auth-Step-Up)
}

Reads take PolyesterRequestOptions; mutations take PolyesterMutationOptions.

timeoutMs must be a positive integer of at most 2147483647; other values throw ValidationError. It is also sent to the backend as the Connect deadline.

Environments

POLYESTER_TESTNET_ENVIRONMENT: PolyesterEnvironment
createPolyesterEnvironment(params: CreatePolyesterEnvironmentParams): PolyesterEnvironment

See Environments for the full parameter reference and validation rules.

Package entry points

Utilities (root export)

Related Topics