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, deposit, addressBook, guardSigner, socialVerification, whiteboard, zipper, mfa, vip, fees, tradingRateLimits, claims), plus realtime (the shared RealtimeClient) and catalog (the ClientCatalog). (whiteboard is a collaboration service peripheral to trading and has no dedicated reference page.)

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

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. 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
}

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

Reads take PolyesterRequestOptions; mutations take PolyesterMutationOptions.

Environments

POLYESTER_DEVNET_ENVIRONMENT: PolyesterEnvironment
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