@aetherwealth/sdk 0.1.36 → 0.2.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Aether Wealth
+Copyright (c) 2026 Aether Wealth Advisors Pvt Ltd
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,9 +4,9 @@ Typed TypeScript client for the **Aether Wealth** public API. Programmatic
 access to your trading journal, accounts, analytics, alerts, market data, and
 diary over the public REST surface (`/api/public/v1/…`).
 
-> **Keep your API key secret.** Authentication uses a public API key
-> (`aw_live_…`) sent as a bearer token. Treat it like a password — never commit
-> it or ship it to an untrusted client.
+> **Keep your API key secret.** Authentication uses an API key for the public API
+> (`aw_live_…`) sent as a bearer token. It is a server-side secret: treat it like
+> a password — never commit it or ship it to an untrusted client.
 
 ## Install
 
@@ -32,7 +32,7 @@ const stats = await client.stats.summary({ pair: 'EURUSD' })
 
 ## Authentication
 
-Each request sends your public API key as `Authorization: Bearer <apiKey>`. The
+Each request sends your secret API key as `Authorization: Bearer <apiKey>`. The
 key scopes every operation to its owner — you never pass `userId` in a request
 body. `auth` is a discriminated union (one member today, `apiKey`) so future
 auth modes can be added without breaking existing callers.
@@ -71,7 +71,7 @@ non-browser runtime that happens to define `window`, set
 | `client.accounts` | `list` · `create` · `update` · `delete` · `trades` · `tradesAll` |
 | `client.stats` | `summary` |
 | `client.alerts` | `list` · `createPrice` · `createTrendline` · `update` · `delete` · `listIndicator` · `createIndicator` · `updateIndicator` · `deleteIndicator` |
-| `client.market` | `config` · `calendar` · `macroSeries` · `macro` |
+| `client.market` | `config` · `calendar` · `macroSeries` · `macro` · `subscribe` |
 | `client.diary` | `list` · `get` · `upsert` · `delete` · `pages` · `listAll` |
 
 List methods return `{ data, pagination }`; single-item methods return the
@@ -98,6 +98,62 @@ for await (const trade of client.trades.listAll({ pair: 'EURUSD' })) {
 
 Iteration starts at `query.page` if given, else page 1.
 
+## Live market stream
+
+`client.market.subscribe` mints a short-lived ticket from aether-backend and
+opens one reconnecting WebSocket for up to 25 symbols. The user API key needs
+`market:read`; it is sent only on the HTTPS ticket request, never in the
+WebSocket URL.
+
+```ts
+const stop = client.market.subscribe(
+  { symbols: ['EURUSD', 'GBPUSD'] },
+  {
+    onUpdate(update) {
+      console.log(update.symbol, update.candle.close)
+    },
+    onError(error) {
+      console.error(error.message)
+    },
+    onStatus(status) {
+      if (status.state === 'terminal') {
+        console.error('stream stopped permanently', status.error)
+      }
+    },
+  },
+)
+
+// Idempotent; also available through the optional AbortSignal input.
+stop()
+```
+
+The V1 feed is fixed to `1m`. `candle.close` is the latest observed price, not
+an executable bid/ask quote. Network failures, 5xx ticket responses, transient
+408/425/429 responses, missed heartbeat pongs, and transient socket closes
+reconnect automatically with a fresh ticket; a 429 waits at least as long as
+`Retry-After`. The backend's planned `4001` reauthentication close is also
+transient and remints the ticket.
+
+Other ticket 4xx responses, the backend's explicit
+`market_stream_unavailable` response, unscoped non-retryable gateway errors,
+and policy/auth socket closes stop that subscription. They call `onError` and
+emit an `onStatus` event whose state is `terminal`; no later reconnect occurs.
+Retryable gateway errors reconnect. A non-retryable error scoped to `symbol`
+is reported as `AetherMarketStreamGatewayError` while the socket stays alive
+for unaffected symbols. Local and whole-stream gateway policy failures use
+`AetherMarketStreamTerminalError`; ticket HTTP failures keep their typed
+`AetherApiError` subclass.
+
+One `AetherClient` may have at most five active `market.subscribe()` calls,
+with up to 25 symbols per call. A sixth call throws
+`AetherMarketStreamTerminalError` with code `MARKET_STREAM_LIMIT`. Calling the
+returned unsubscribe function—or reaching a terminal failure—immediately frees
+that slot.
+
+The package's conditional Node export supplies the `ws` transport. Runtimes
+resolving the universal entry, including edge bundlers, use their native
+`WebSocket`, keeping that entry free of Node-only built-ins.
+
 ## Timeouts & cancellation
 
 Every request is bounded by `timeoutMs` (default 30s), overridable per call. A
@@ -201,7 +257,10 @@ const trade = parseTrade(await client.trades.get(id)) // throws on shape drift
 
 ## Not covered
 
-Live candles and AI chat conversations are streamed/tRPC-only on the backend
-and are intentionally **not** part of this REST SDK — reach them through
-`@aetherwealth/client-core` (used by the CLI and MCP server). API-key
+AI chat conversations remain tRPC-only and are not part of this SDK. API-key
 management is likewise out of scope: an API key can't provision other keys.
+
+## License
+
+MIT. See the `LICENSE` file included with this package. Service use is governed
+by the [Aether Wealth Terms of Service](https://aetherwealth.ai/terms).

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { AccountsResource, AlertsResource, DiaryResource, MarketResource, StatsResource, TradesResource } from './types.js';
+import type { AccountsResource, AetherWebSocketFactory, AlertsResource, DiaryResource, MarketResource, StatsResource, TradesResource } from './types.js';
 export type AetherFetchInit = {
     method?: 'GET' | 'POST' | 'PATCH' | 'DELETE' | 'PUT';
     query?: Record<string, string | number | boolean | undefined | null | string[]>;
@@ -14,7 +14,7 @@ export type AetherFetchInit = {
     /** When set, sent as the `Idempotency-Key` header so a retried create dedups. */
     idempotencyKey?: string;
 };
-/** API-key auth: a public key (`aw_live_…`) sent as `Authorization: Bearer`. */
+/** API-key auth: a user API key (`aw_live_…`) sent as `Authorization: Bearer`. */
 export type ApiKeyAuth = {
     type: 'apiKey';
     apiKey: string;
@@ -69,6 +69,8 @@ export type AetherClientConfig = {
         status: number;
         ms: number;
     }) => void;
+    /** Override WebSocket construction (primarily for tests or custom runtimes). */
+    webSocketFactory?: AetherWebSocketFactory;
 };
 /** Default per-request timeout budget (ms). */
 export declare const DEFAULT_TIMEOUT_MS = 30000;

package/dist/client.js

@@ -2,8 +2,8 @@
  * AetherClient — typed HTTP client for the AetherWealth **public API**
  * (`/api/public/v1/<domain>/<action>`, POST-RPC, `{success, <key>}` envelopes).
  *
- * Auth: every public route is authenticated with a public API key sent as
- * `Authorization: Bearer aw_live_…`. Configure it via
+ * Auth: every public route is authenticated with a user API key sent as
+ * `Authorization: Bearer aw_live_…`. The key is a server-side secret. Configure it via
  * `auth: {type: 'apiKey', apiKey}`. `auth` is a discriminated union so an
  * `oauth`/`hmac` member can be added later without breaking existing callers.
  *
@@ -78,6 +78,13 @@ function assertHttpsUnlessLoopback(baseUrl) {
         throw new Error(`AetherClient: baseUrl must not contain a query, fragment, or credentials: "${baseUrl}"`);
     }
 }
+function defaultWebSocketFactory(url) {
+    const NativeWebSocket = globalThis.WebSocket;
+    if (!NativeWebSocket) {
+        throw new Error('AetherClient: this runtime has no native WebSocket; pass webSocketFactory explicitly');
+    }
+    return new NativeWebSocket(url);
+}
 /** Append one query entry, skipping null/undefined and repeating array values. */
 function appendQueryParam(params, key, value) {
     if (value === undefined || value === null)
@@ -248,7 +255,10 @@ export class AetherClient {
         this.accounts = createAccountsResource(this);
         this.stats = createStatsResource(this);
         this.alerts = createAlertsResource(this);
-        this.market = createMarketResource(this);
+        this.market = createMarketResource(this, {
+            baseUrl,
+            webSocketFactory: config.webSocketFactory ?? defaultWebSocketFactory
+        });
         this.diary = createDiaryResource(this);
     }
     /**

package/dist/client.node.d.ts

@@ -0,0 +1,5 @@
+import { type AetherClientConfig, AetherClient as UniversalAetherClient } from './client.js';
+/** Node transport entry; callers can still provide a custom factory. */
+export declare class AetherClient extends UniversalAetherClient {
+    constructor(config: AetherClientConfig);
+}

package/dist/client.node.js

@@ -0,0 +1,12 @@
+import NodeWebSocket from 'ws';
+import { AetherClient as UniversalAetherClient } from './client.js';
+/** Node transport entry; callers can still provide a custom factory. */
+export class AetherClient extends UniversalAetherClient {
+    constructor(config) {
+        super({
+            ...config,
+            webSocketFactory: config.webSocketFactory ??
+                (url => new NodeWebSocket(url))
+        });
+    }
+}

package/dist/errors.d.ts

@@ -76,6 +76,27 @@ export declare class AetherRateLimitError extends AetherApiError {
         responseBody?: unknown;
     });
 }
+export type AetherMarketStreamTerminalErrorCode = 'MARKET_STREAM_LIMIT' | 'MARKET_STREAM_TICKET_RESPONSE' | 'MARKET_STREAM_GATEWAY_REJECTED' | 'MARKET_STREAM_SOCKET_POLICY';
+/** A structured error frame emitted by the live market gateway. */
+export declare class AetherMarketStreamGatewayError extends Error {
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly symbol: string | undefined;
+    constructor(message: string, opts: {
+        code: string;
+        retryable: boolean;
+        symbol?: string;
+    });
+}
+/** A local stream failure that reconnecting cannot resolve. */
+export declare class AetherMarketStreamTerminalError extends Error {
+    readonly code: AetherMarketStreamTerminalErrorCode;
+    readonly cause: unknown;
+    constructor(message: string, opts: {
+        code: AetherMarketStreamTerminalErrorCode;
+        cause?: unknown;
+    });
+}
 export declare class AetherNetworkError extends Error {
     readonly cause: unknown;
     readonly path: string;

package/dist/errors.js

@@ -92,6 +92,30 @@ export class AetherRateLimitError extends AetherApiError {
         this.retryAfterSeconds = opts.retryAfterSeconds;
     }
 }
+/** A structured error frame emitted by the live market gateway. */
+export class AetherMarketStreamGatewayError extends Error {
+    code;
+    retryable;
+    symbol;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'AetherMarketStreamGatewayError';
+        this.code = opts.code;
+        this.retryable = opts.retryable;
+        this.symbol = opts.symbol;
+    }
+}
+/** A local stream failure that reconnecting cannot resolve. */
+export class AetherMarketStreamTerminalError extends Error {
+    code;
+    cause;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'AetherMarketStreamTerminalError';
+        this.code = opts.code;
+        this.cause = opts.cause;
+    }
+}
 export class AetherNetworkError extends Error {
     cause;
     path;

package/dist/index.d.ts

@@ -5,8 +5,8 @@
  * (`/api/public/v1/<domain>/<action>`). Reusable in any Node/Bun/edge runtime
  * that needs programmatic access to AetherWealth data.
  *
- * Auth — every public route is authenticated with a **public API key**
- * (`aw_live_…`) sent as `Authorization: Bearer …`:
+ * Auth — every public route is authenticated with a **user API key**
+ * (`aw_live_…`) sent as `Authorization: Bearer …`. The key is a server-side secret:
  *
  * ```ts
  * const client = new AetherClient({
@@ -20,8 +20,9 @@
  */
 export type { AetherAuth, AetherClientConfig, AetherFetchInit, ApiKeyAuth } from './client.js';
 export { AetherClient, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from './client.js';
-export { AetherApiError, AetherAuthError, AetherForbiddenError, AetherNetworkError, AetherNotFoundError, AetherRateLimitError, AetherTimeoutError, AetherValidationError, classifyError, parseRetryAfter } from './errors.js';
+export type { AetherMarketStreamTerminalErrorCode } from './errors.js';
+export { AetherApiError, AetherAuthError, AetherForbiddenError, AetherMarketStreamGatewayError, AetherMarketStreamTerminalError, AetherNetworkError, AetherNotFoundError, AetherRateLimitError, AetherTimeoutError, AetherValidationError, classifyError, parseRetryAfter } from './errors.js';
 export type { RetryOptions } from './retry.js';
 export { computeDelay, withRetry } from './retry.js';
 export { accountSchema, alertSchema, dedupModeSchema, diaryEntrySchema, economicEventSchema, indicatorAlertSchema, indicatorConditionSchema, macroSeriesPointSchema, macroSeriesResultSchema, marketConfigSchema, paginationSchema, parseAccount, parseAlert, parseDiaryEntry, parseEconomicEvent, parseIndicatorAlert, parseMacroSeriesResult, parseMarketConfig, parseTrade, parseTradingStats, priceConditionSchema, tradeDirectionSchema, tradeSchema, tradeStatusSchema, tradingStatsSchema, triggerTypeSchema } from './schemas.js';
-export type { Account, AccountsResource, Alert, AlertsResource, AlertType, ApiEnvelope, CalendarQuery, CalendarResult, CloseTradeInput, CreateAccountInput, CreateIndicatorAlertInput, CreatePriceAlertInput, CreateTradeInput, CreateTrendlineAlertInput, DedupMode, DiaryEntry, DiaryListQuery, DiaryResource, EconomicEvent, EconomicEventMinimal, EconomicEventRich, IdempotencyOptions, IndicatorAlert, IndicatorCondition, ListAlertsQuery, MacroQuery, MacroRange, MacroSeriesQuery, MacroSeriesResult, MarketConfig, MarketResource, PaginatedResponse, PaginationMeta, PriceCondition, SeriesOp, StatsQuery, StatsResource, ThresholdOp, Trade, TradeDirection, TradeListQuery, TradeStatus, TradeStatusFilter, TradesResource, TradingStats, TriggerType, UpdateAccountInput, UpdateAlertInput, UpdateIndicatorAlertInput, UpdateTradeInput, UpsertDiaryInput } from './types.js';
+export type { Account, AccountsResource, AetherWebSocket, AetherWebSocketFactory, Alert, AlertsResource, AlertType, ApiEnvelope, CalendarQuery, CalendarResult, CloseTradeInput, CreateAccountInput, CreateIndicatorAlertInput, CreatePriceAlertInput, CreateTradeInput, CreateTrendlineAlertInput, DedupMode, DiaryEntry, DiaryListQuery, DiaryResource, EconomicEvent, EconomicEventMinimal, EconomicEventRich, IdempotencyOptions, IndicatorAlert, IndicatorCondition, ListAlertsQuery, LiveCandle, LiveMarketUpdate, MacroQuery, MacroRange, MacroSeriesQuery, MacroSeriesResult, MarketConfig, MarketResource, MarketStreamState, MarketStreamStatus, PaginatedResponse, PaginationMeta, PriceCondition, SeriesOp, StatsQuery, StatsResource, SubscribeLiveMarketHandlers, SubscribeLiveMarketInput, ThresholdOp, Trade, TradeDirection, TradeListQuery, TradeStatus, TradeStatusFilter, TradesResource, TradingStats, TriggerType, UpdateAccountInput, UpdateAlertInput, UpdateIndicatorAlertInput, UpdateTradeInput, UpsertDiaryInput } from './types.js';

package/dist/index.js

@@ -5,8 +5,8 @@
  * (`/api/public/v1/<domain>/<action>`). Reusable in any Node/Bun/edge runtime
  * that needs programmatic access to AetherWealth data.
  *
- * Auth — every public route is authenticated with a **public API key**
- * (`aw_live_…`) sent as `Authorization: Bearer …`:
+ * Auth — every public route is authenticated with a **user API key**
+ * (`aw_live_…`) sent as `Authorization: Bearer …`. The key is a server-side secret:
  *
  * ```ts
  * const client = new AetherClient({
@@ -19,6 +19,6 @@
  * modes can be added without breaking callers. See the README for setup.
  */
 export { AetherClient, DEFAULT_BASE_URL, DEFAULT_TIMEOUT_MS } from './client.js';
-export { AetherApiError, AetherAuthError, AetherForbiddenError, AetherNetworkError, AetherNotFoundError, AetherRateLimitError, AetherTimeoutError, AetherValidationError, classifyError, parseRetryAfter } from './errors.js';
+export { AetherApiError, AetherAuthError, AetherForbiddenError, AetherMarketStreamGatewayError, AetherMarketStreamTerminalError, AetherNetworkError, AetherNotFoundError, AetherRateLimitError, AetherTimeoutError, AetherValidationError, classifyError, parseRetryAfter } from './errors.js';
 export { computeDelay, withRetry } from './retry.js';
 export { accountSchema, alertSchema, dedupModeSchema, diaryEntrySchema, economicEventSchema, indicatorAlertSchema, indicatorConditionSchema, macroSeriesPointSchema, macroSeriesResultSchema, marketConfigSchema, paginationSchema, parseAccount, parseAlert, parseDiaryEntry, parseEconomicEvent, parseIndicatorAlert, parseMacroSeriesResult, parseMarketConfig, parseTrade, parseTradingStats, priceConditionSchema, tradeDirectionSchema, tradeSchema, tradeStatusSchema, tradingStatsSchema, triggerTypeSchema } from './schemas.js';

package/dist/index.node.d.ts

@@ -0,0 +1,2 @@
+export { AetherClient } from './client.node.js';
+export * from './index.js';

package/dist/index.node.js

@@ -0,0 +1,2 @@
+export { AetherClient } from './client.node.js';
+export * from './index.js';

package/dist/resources/market.d.ts

@@ -1,8 +1,12 @@
 import type { AetherClient } from '../client.js';
-import type { MarketResource } from '../types.js';
+import type { AetherWebSocketFactory, MarketResource } from '../types.js';
+type MarketResourceOptions = {
+    baseUrl: string;
+    webSocketFactory: AetherWebSocketFactory;
+};
 /**
- * `market` — read-only market context via the public API
- * `POST /api/public/v1/market/*`. Live candles are NOT available over REST
- * (tRPC-only) and are intentionally absent from the SDK.
+ * `market` — read-only market context via the public REST API plus live
+ * 1-minute candle updates through the authenticated backend WebSocket gateway.
  */
-export declare function createMarketResource(client: AetherClient): MarketResource;
+export declare function createMarketResource(client: AetherClient, options: MarketResourceOptions): MarketResource;
+export {};

package/dist/resources/market.js

@@ -1,13 +1,419 @@
+import { AetherApiError, AetherMarketStreamGatewayError, AetherMarketStreamTerminalError, AetherRateLimitError } from '../errors.js';
 import { parseEconomicEvent, parseMacroSeriesResult, parseMarketConfig } from '../schemas.js';
 import { pluck } from './envelope.js';
 import { assertEachShape, assertShape } from './validate.js';
 const MACRO_RANGES = ['3m', '6m', '12m', '24m', 'all'];
+const LIVE_TIMEFRAME = '1m';
+const MAX_LIVE_SYMBOLS = 25;
+const MAX_CONCURRENT_LIVE_STREAMS = 5;
+const LIVE_SYMBOL_PATTERN = /^[A-Z0-9]{2,16}$/;
+const HEARTBEAT_INTERVAL_MS = 30_000;
+const HEARTBEAT_TIMEOUT_MS = 10_000;
+const MAX_RECONNECT_DELAY_MS = 30_000;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const TERMINAL_WEBSOCKET_CLOSE_CODES = new Set([1008, 1009, 4003, 4401, 4403]);
+const PONG = Symbol('pong');
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function invokeSafely(callback, value) {
+    try {
+        callback?.(value);
+    }
+    catch {
+        // Consumer callbacks must not corrupt the socket lifecycle.
+    }
+}
+function socketCloseError(event) {
+    const message = `market.subscribe: WebSocket closed (${event.code}${event.reason ? ` ${event.reason}` : ''})`;
+    if (!TERMINAL_WEBSOCKET_CLOSE_CODES.has(event.code))
+        return new Error(message);
+    return new AetherMarketStreamTerminalError(message, { code: 'MARKET_STREAM_SOCKET_POLICY' });
+}
+function isTerminalTicketError(error) {
+    return (error instanceof AetherMarketStreamTerminalError ||
+        (error instanceof AetherApiError &&
+            (error.code === 'market_stream_unavailable' ||
+                (error.status >= 400 &&
+                    error.status < 500 &&
+                    ![408, 425, 429].includes(error.status)))));
+}
+function closeSafely(socket, code, reason) {
+    try {
+        socket.close(code, reason);
+    }
+    catch {
+        // Closing is cleanup; a custom WebSocket implementation must not block teardown.
+    }
+}
+function normalizeLiveSymbols(input) {
+    if (!Array.isArray(input) || input.length === 0) {
+        throw new Error('market.subscribe: at least one symbol is required');
+    }
+    const symbols = [
+        ...new Set(input.map(symbol => {
+            if (typeof symbol !== 'string' || symbol.trim().length === 0) {
+                throw new Error('market.subscribe: every symbol must be a non-empty string');
+            }
+            const normalized = symbol.trim().toUpperCase();
+            if (!LIVE_SYMBOL_PATTERN.test(normalized)) {
+                throw new Error('market.subscribe: symbols must contain 2-16 uppercase letters or digits');
+            }
+            return normalized;
+        }))
+    ];
+    if (symbols.length > MAX_LIVE_SYMBOLS) {
+        throw new Error(`market.subscribe: at most ${MAX_LIVE_SYMBOLS} symbols are allowed`);
+    }
+    return symbols;
+}
+function streamUrl(baseUrl, ticket) {
+    const url = new URL('/websocket/market-data', baseUrl);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    url.searchParams.set('ticket', ticket);
+    return url.toString();
+}
+function frameText(data) {
+    if (typeof data === 'string')
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new TextDecoder().decode(data);
+    if (ArrayBuffer.isView(data)) {
+        return new TextDecoder().decode(new Uint8Array(data.buffer, data.byteOffset, data.byteLength));
+    }
+    return null;
+}
+function finiteNumber(value) {
+    let parsed = NaN;
+    if (typeof value === 'number')
+        parsed = value;
+    if (typeof value === 'string' && value.trim().length > 0)
+        parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function parseLiveUpdate(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const frame = raw;
+    if (frame['type'] !== 'live_tick')
+        return null;
+    if (typeof frame['symbol'] !== 'string' || frame['timeframe'] !== LIVE_TIMEFRAME) {
+        throw new Error('market.subscribe: received an invalid live_tick identity');
+    }
+    const data = frame['data'];
+    if (!data || typeof data !== 'object') {
+        throw new Error('market.subscribe: received live_tick without candle data');
+    }
+    const candle = data;
+    const epoch = finiteNumber(candle['epoch']);
+    const open = finiteNumber(candle['open']);
+    const high = finiteNumber(candle['high']);
+    const low = finiteNumber(candle['low']);
+    const close = finiteNumber(candle['close']);
+    const volume = finiteNumber(candle['volume']);
+    if ([epoch, open, high, low, close, volume].some(value => value === null)) {
+        throw new Error('market.subscribe: received invalid live_tick candle values');
+    }
+    const timestamp = frame['timestamp'];
+    if (timestamp !== undefined && finiteNumber(timestamp) === null) {
+        throw new Error('market.subscribe: received an invalid live_tick timestamp');
+    }
+    return {
+        symbol: frame['symbol'].toUpperCase(),
+        timeframe: LIVE_TIMEFRAME,
+        candle: {
+            epoch: epoch,
+            open: open,
+            high: high,
+            low: low,
+            close: close,
+            volume: volume
+        },
+        ...(timestamp === undefined ? {} : { timestamp: finiteNumber(timestamp) })
+    };
+}
+function assertStreamTicket(ticket) {
+    if (!ticket ||
+        typeof ticket.ticket !== 'string' ||
+        ticket.ticket.length === 0 ||
+        !Number.isFinite(ticket.expiresAt)) {
+        throw new AetherMarketStreamTerminalError('market.subscribe: ticket endpoint returned an invalid response', { code: 'MARKET_STREAM_TICKET_RESPONSE' });
+    }
+}
+function parseGatewayError(frame, symbolSet) {
+    if (!frame || typeof frame !== 'object' || frame.type !== 'error') {
+        return null;
+    }
+    const errorFrame = frame;
+    const message = typeof errorFrame['message'] === 'string' ? errorFrame['message'] : 'unknown error';
+    const symbol = typeof errorFrame['symbol'] === 'string'
+        ? errorFrame['symbol'].trim().toUpperCase()
+        : undefined;
+    if (symbol && !symbolSet.has(symbol)) {
+        throw new Error(`market.subscribe: received gateway error for unsubscribed symbol ${symbol}`);
+    }
+    return new AetherMarketStreamGatewayError(`market.subscribe: gateway error: ${message}`, {
+        code: typeof errorFrame['code'] === 'string' ? errorFrame['code'] : 'gateway_rejected',
+        retryable: errorFrame['retryable'] === true,
+        ...(symbol ? { symbol } : {})
+    });
+}
+function parseLiveMessage(data, symbolSet) {
+    const text = frameText(data);
+    if (text === 'pong')
+        return PONG;
+    if (text === null)
+        throw new Error('market.subscribe: received a non-text frame');
+    const frame = JSON.parse(text);
+    if (frame && typeof frame === 'object' && frame.type === 'pong')
+        return PONG;
+    const gatewayError = parseGatewayError(frame, symbolSet);
+    if (gatewayError)
+        throw gatewayError;
+    const update = parseLiveUpdate(frame);
+    if (update && !symbolSet.has(update.symbol)) {
+        throw new Error(`market.subscribe: received live_tick for unsubscribed symbol ${update.symbol}`);
+    }
+    return update;
+}
+function handleLiveMessageError(error, socket, reportError, terminate) {
+    if (error instanceof AetherMarketStreamGatewayError) {
+        if (error.retryable) {
+            reportError(error);
+            closeSafely(socket, 1012, 'retryable gateway error');
+            return;
+        }
+        if (error.symbol) {
+            reportError(error);
+            return;
+        }
+        terminate(new AetherMarketStreamTerminalError(error.message, {
+            code: 'MARKET_STREAM_GATEWAY_REJECTED',
+            cause: error
+        }));
+        return;
+    }
+    if (error instanceof AetherMarketStreamTerminalError) {
+        terminate(error);
+        return;
+    }
+    reportError(error);
+}
+function subscribeLiveMarket(client, options, input, handlers, releaseSlot) {
+    const symbols = normalizeLiveSymbols(input.symbols);
+    const symbolSet = new Set(symbols);
+    const reconnectJitter = 0.75 + Math.random() * 0.5;
+    const requestAbort = new AbortController();
+    let stopped = false;
+    let socket = null;
+    let reconnectAttempt = 0;
+    let generation = 0;
+    let reconnectTimer = null;
+    let heartbeatTimer = null;
+    let pongTimer = null;
+    const reportStatus = (state, error) => invokeSafely(handlers.onStatus, { state, reconnectAttempt, ...(error ? { error } : {}) });
+    const reportError = (error) => invokeSafely(handlers.onError, error);
+    const clearHeartbeatTimers = () => {
+        if (heartbeatTimer)
+            clearInterval(heartbeatTimer);
+        if (pongTimer)
+            clearTimeout(pongTimer);
+        heartbeatTimer = null;
+        pongTimer = null;
+    };
+    const clearTimers = () => {
+        if (reconnectTimer)
+            clearTimeout(reconnectTimer);
+        reconnectTimer = null;
+        clearHeartbeatTimers();
+    };
+    const terminate = (error) => {
+        if (stopped)
+            return;
+        stopped = true;
+        generation += 1;
+        clearTimers();
+        input.signal?.removeEventListener('abort', unsubscribe);
+        requestAbort.abort(error);
+        const activeSocket = socket;
+        socket = null;
+        if (activeSocket && (activeSocket.readyState === 0 || activeSocket.readyState === 1)) {
+            closeSafely(activeSocket, 1000, 'subscription terminated');
+        }
+        releaseSlot();
+        reportError(error);
+        reportStatus('terminal', error);
+    };
+    const scheduleReconnect = (error) => {
+        if (stopped || reconnectTimer)
+            return;
+        reconnectAttempt += 1;
+        const backoffDelay = Math.round(Math.min(1_000 * 2 ** (reconnectAttempt - 1) * reconnectJitter, MAX_RECONNECT_DELAY_MS));
+        const retryAfterDelay = error instanceof AetherRateLimitError && error.retryAfterSeconds !== null
+            ? error.retryAfterSeconds * 1_000
+            : 0;
+        const delay = Math.min(Math.max(backoffDelay, retryAfterDelay), MAX_TIMER_DELAY_MS);
+        reconnectTimer = setTimeout(() => {
+            reconnectTimer = null;
+            connect().catch(error => reportError(toError(error)));
+        }, delay);
+        reportStatus('reconnecting', error);
+    };
+    const isInactive = (candidateGeneration) => stopped || candidateGeneration !== generation;
+    const handleConnectFailure = (error) => {
+        if (stopped)
+            return;
+        const normalized = toError(error);
+        if (isTerminalTicketError(normalized)) {
+            terminate(normalized);
+            return;
+        }
+        reportError(normalized);
+        scheduleReconnect(normalized);
+    };
+    const handleSocketMessage = (data, activeSocket) => {
+        if (stopped || socket !== activeSocket)
+            return;
+        try {
+            const update = parseLiveMessage(data, symbolSet);
+            if (update === PONG) {
+                if (pongTimer)
+                    clearTimeout(pongTimer);
+                pongTimer = null;
+                return;
+            }
+            if (update)
+                invokeSafely(handlers.onUpdate, update);
+        }
+        catch (error) {
+            handleLiveMessageError(toError(error), activeSocket, reportError, terminate);
+        }
+    };
+    const bindSocket = (nextSocket, socketGeneration) => {
+        nextSocket.onopen = () => {
+            if (isInactive(socketGeneration) || socket !== nextSocket)
+                return;
+            try {
+                nextSocket.send(JSON.stringify({
+                    type: 'subscribe',
+                    subscriptions: symbols.map(symbol => ({ symbol, timeframe: LIVE_TIMEFRAME }))
+                }));
+                heartbeatTimer = setInterval(() => {
+                    if (!stopped && socket === nextSocket && nextSocket.readyState === 1) {
+                        try {
+                            nextSocket.send(JSON.stringify({ type: 'ping' }));
+                            if (pongTimer)
+                                clearTimeout(pongTimer);
+                            pongTimer = setTimeout(() => {
+                                if (stopped ||
+                                    socket !== nextSocket ||
+                                    nextSocket.readyState !== 1) {
+                                    return;
+                                }
+                                const error = new Error('market.subscribe: heartbeat pong timeout');
+                                clearHeartbeatTimers();
+                                socket = null;
+                                closeSafely(nextSocket, 1012, 'heartbeat pong timeout');
+                                reportError(error);
+                                scheduleReconnect(error);
+                            }, HEARTBEAT_TIMEOUT_MS);
+                        }
+                        catch (error) {
+                            reportError(toError(error));
+                            closeSafely(nextSocket, 1011, 'heartbeat send failed');
+                        }
+                    }
+                }, HEARTBEAT_INTERVAL_MS);
+            }
+            catch (error) {
+                reportError(toError(error));
+                closeSafely(nextSocket, 1011, 'subscription send failed');
+                return;
+            }
+            reconnectAttempt = 0;
+            reportStatus('connected');
+        };
+        nextSocket.onmessage = event => handleSocketMessage(event.data, nextSocket);
+        nextSocket.onerror = () => {
+            if (!stopped && socket === nextSocket) {
+                reportError(new Error('market.subscribe: WebSocket error'));
+            }
+        };
+        nextSocket.onclose = event => {
+            if (socket !== nextSocket)
+                return;
+            clearHeartbeatTimers();
+            socket = null;
+            if (isInactive(socketGeneration))
+                return;
+            const error = socketCloseError(event);
+            if (error instanceof AetherMarketStreamTerminalError)
+                terminate(error);
+            else
+                scheduleReconnect(error);
+        };
+    };
+    const connect = async () => {
+        if (stopped)
+            return;
+        const thisGeneration = ++generation;
+        reportStatus(reconnectAttempt === 0 ? 'connecting' : 'reconnecting');
+        if (stopped)
+            return;
+        try {
+            const ticket = await client.request('/api/market-data/stream-ticket', {
+                method: 'POST',
+                body: {},
+                signal: requestAbort.signal
+            });
+            if (isInactive(thisGeneration))
+                return;
+            assertStreamTicket(ticket);
+            const nextSocket = options.webSocketFactory(streamUrl(options.baseUrl, ticket.ticket));
+            if (isInactive(thisGeneration)) {
+                closeSafely(nextSocket, 1000, 'subscription cancelled');
+                return;
+            }
+            socket = nextSocket;
+            bindSocket(nextSocket, thisGeneration);
+        }
+        catch (error) {
+            handleConnectFailure(error);
+        }
+    };
+    const unsubscribe = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        generation += 1;
+        clearTimers();
+        input.signal?.removeEventListener('abort', unsubscribe);
+        requestAbort.abort(new Error('market subscription cancelled'));
+        const activeSocket = socket;
+        socket = null;
+        if (activeSocket && (activeSocket.readyState === 0 || activeSocket.readyState === 1)) {
+            closeSafely(activeSocket, 1000, 'subscription cancelled');
+        }
+        releaseSlot();
+        reportStatus('disconnected');
+    };
+    if (input.signal?.aborted) {
+        stopped = true;
+        releaseSlot();
+        reportStatus('disconnected');
+    }
+    else {
+        input.signal?.addEventListener('abort', unsubscribe, { once: true });
+        connect().catch(error => reportError(toError(error)));
+    }
+    return unsubscribe;
+}
 /**
- * `market` — read-only market context via the public API
- * `POST /api/public/v1/market/*`. Live candles are NOT available over REST
- * (tRPC-only) and are intentionally absent from the SDK.
+ * `market` — read-only market context via the public REST API plus live
+ * 1-minute candle updates through the authenticated backend WebSocket gateway.
  */
-export function createMarketResource(client) {
+export function createMarketResource(client, options) {
+    let activeStreams = 0;
     return {
         async config() {
             // `{success, data}` — client.request unwraps `data`.
@@ -85,6 +491,26 @@ export function createMarketResource(client) {
             const result = await client.request('/api/public/v1/market/macro', { method: 'POST', body });
             // `null` (no series) passes through; a present series is shape-checked.
             return assertShape(client.validateResponses, parseMacroSeriesResult, result);
+        },
+        subscribe(input, handlers) {
+            if (activeStreams >= MAX_CONCURRENT_LIVE_STREAMS) {
+                throw new AetherMarketStreamTerminalError(`market.subscribe: at most ${MAX_CONCURRENT_LIVE_STREAMS} concurrent streams are allowed per client`, { code: 'MARKET_STREAM_LIMIT' });
+            }
+            activeStreams += 1;
+            let released = false;
+            const releaseSlot = () => {
+                if (released)
+                    return;
+                released = true;
+                activeStreams -= 1;
+            };
+            try {
+                return subscribeLiveMarket(client, options, input, handlers, releaseSlot);
+            }
+            catch (error) {
+                releaseSlot();
+                throw error;
+            }
         }
     };
 }

package/dist/types.d.ts

@@ -475,6 +475,57 @@ export type MacroSeriesResult = {
     cachedAt?: number;
 };
 export type MacroRange = '3m' | '6m' | '12m' | '24m' | 'all';
+/** The current in-progress 1-minute candle for a live market symbol. */
+export type LiveCandle = {
+    epoch: number;
+    open: number;
+    high: number;
+    low: number;
+    /** Latest observed market price; it is not an executable quote. */
+    close: number;
+    volume: number;
+};
+export type LiveMarketUpdate = {
+    symbol: string;
+    /** Live public streams currently use the backend's fixed 1-minute feed. */
+    timeframe: '1m';
+    candle: LiveCandle;
+    timestamp?: number;
+};
+export type MarketStreamState = 'connecting' | 'connected' | 'reconnecting' | 'disconnected' | 'terminal';
+export type MarketStreamStatus = {
+    /** `terminal` means this subscription has stopped and will not reconnect. */
+    state: MarketStreamState;
+    reconnectAttempt: number;
+    error?: Error;
+};
+export type SubscribeLiveMarketInput = {
+    /** One to 25 market symbols. Timeframe is intentionally fixed by the backend. */
+    symbols: readonly string[];
+    signal?: AbortSignal;
+};
+export type SubscribeLiveMarketHandlers = {
+    onUpdate: (update: LiveMarketUpdate) => void;
+    onStatus?: (status: MarketStreamStatus) => void;
+    /** Reports malformed frames plus transient and terminal connection failures. */
+    onError?: (error: Error) => void;
+};
+/** Minimal WebSocket surface used by the SDK and injectable in tests. */
+export interface AetherWebSocket {
+    readonly readyState: number;
+    onopen: (() => void) | null;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror: ((event: unknown) => void) | null;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+    }) => void) | null;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+export type AetherWebSocketFactory = (url: string) => AetherWebSocket;
 /** Args for `market.macro` — an object (not positional) so the two same-typed
  *  `currency`/`indicator` strings can't be silently transposed. */
 export type MacroQuery = {
@@ -491,6 +542,13 @@ export interface MarketResource {
     macroSeries(query: MacroSeriesQuery): Promise<EconomicEventRich[]>;
     /** fxmacrodata time series for a currency+indicator (`/api/public/v1/market/macro`). */
     macro(query: MacroQuery): Promise<MacroSeriesResult | null>;
+    /**
+     * Open one independently managed backend stream for the supplied symbols.
+     * Returns an immediate, idempotent unsubscribe function.
+     * A client can hold at most five active streams; a sixth call throws
+     * `AetherMarketStreamTerminalError` until another stream stops.
+     */
+    subscribe(input: SubscribeLiveMarketInput, handlers: SubscribeLiveMarketHandlers): () => void;
 }
 export type DiaryEntry = {
     id: string;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@aetherwealth/sdk",
-    "version": "0.1.36",
-    "description": "Official Aether Wealth SDK: a typed TypeScript client for the Aether Wealth public API — trades, accounts, analytics, alerts, market data, macro calendar, and diary.",
+    "version": "0.2.1",
+    "description": "Official typed TypeScript SDK for Aether Wealth journals, accounts, analytics, alerts, and forex and crypto market data.",
     "type": "module",
     "sideEffects": false,
     "main": "./dist/index.js",
@@ -10,6 +10,7 @@
     "exports": {
         ".": {
             "types": "./dist/index.d.ts",
+            "node": "./dist/index.node.js",
             "import": "./dist/index.js",
             "default": "./dist/index.js"
         },
@@ -24,6 +25,7 @@
         "node": ">=18"
     },
     "dependencies": {
+        "ws": "^8.21.0",
         "zod": "^4.4.3"
     },
     "publishConfig": {
@@ -41,15 +43,10 @@
         "market data",
         "technical indicators"
     ],
-    "author": "Aether Wealth <support@aetherwealth.ai>",
+    "author": "Aether Wealth Advisors Pvt Ltd <infra@aetherwealth.ai>",
     "license": "MIT",
     "homepage": "https://aetherwealth.ai/sdk",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/Opus-Aether-AI/webapp.git",
-        "directory": "packages/sdk"
-    },
     "bugs": {
-        "url": "https://github.com/Opus-Aether-AI/webapp/issues"
+        "email": "infra@aetherwealth.ai"
     }
 }