@cexyio/cexy 0.1.0-dev.6 → 0.1.0-dev.7

package/README.md

@@ -46,6 +46,8 @@ const cexy = new CexyClient({
 });
 
 const balances = await cexy.account.balances();
+// A sub-account's balances (parent account only; same shape, incl. held_incoming):
+const subBalances = await cexy.account.subAccountBalances("sub-account-id");
 const open = await cexy.trading.openOrders({ symbol: "BTC/USDT" });
 
 const placed = await cexy.trading.placeOrder({
@@ -94,7 +96,7 @@ Give both `apiKey` and `apiSecret`, or neither: passing only one throws at const
 | `markets` | `list`, `get`, `orderbook`, `trades`, `iterateTrades`, `candles` | public |
 | `assets`, `networks`, `fees`, `pools` | `list`, `get` / `list` / `get` / `list`, `get` | public |
 | `time()`, `config()` | | public |
-| `account` | `balances`, `balance`, `ledger`, `notifications`, `subAccounts`, `apiKeys` (+ iterators) | read |
+| `account` | `balances`, `balance`, `ledger`, `notifications`, `subAccounts`, `subAccountBalances`, `apiKeys` (+ iterators) | read |
 | `exports` | `deposits`, `ledger`, `orders`, `trades`, `withdrawals` (CSV text) | read |
 | `wallet` | `deposits`, `deposit`, `withdrawals`, `withdrawal`, `withdrawalAddresses`, `depositAddress` (+ iterators) | read |
 | `trading` | `openOrders`, `order`, `orderByClientId`, `orderHistory`, `trades` (+ iterators) | read |
@@ -106,6 +108,13 @@ asset/network (later calls return the same one). Always use the `memo` too when
 
 There are no withdrawal or transfer methods: API keys cannot withdraw or transfer funds.
 
+**Held incoming transfers.** Each balance has `held_incoming`: incoming internal transfers still
+held, as `{ transfer_id, amount, available_at }`. Their sum is **already included in `locked`**, so
+never add them to `locked` or `total` again. There are at most 100 entries, soonest `available_at`
+first (millisecond precision), with no sender identity. An entry disappears once the transfer is
+released (the amount moves to `available`) or cancelled by the exchange. It is always an array
+(`[]` when none, including from servers that predate the field).
+
 ## Amounts
 
 Every amount is an exact decimal **string** (`"0.00150000"`), in responses and requests. JS numbers are
@@ -153,7 +162,8 @@ try {
 ## Retries and idempotency
 
 - Timeout per attempt: `timeoutMs` (default 10 s). Retries: `maxRetries` (default 3), exponential backoff with full jitter.
-- Retried: network errors, timeouts and responses with `retryable: true`.
+- Retried: network errors, timeouts and responses with `retryable: true` (and 409 `CONCURRENT_MODIFICATION`).
+  A 4xx is never retried except 429 and 409 `CONCURRENT_MODIFICATION`, whatever its body says.
 - 429 waits at least `Retry-After` / `details.retry_after_seconds`. Server wait hints are untrusted: unusable
   values are ignored, and a hint longer than 120 s (`MAX_SERVER_WAIT_MS`) is never waited: the call fails at
   once with `RateLimitError`, whose `retryAfterMs` still has the server's value. The client-side rate limiter
@@ -285,7 +295,7 @@ Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
 ## For tool builders
 
 The package exports its building blocks: the `OPERATIONS` table (method, path, auth and scope for each of the
-40 operations), all model types, the error classes, `paginate()`, `RateLimiter`, the `Authenticator`
+41 operations), all model types, the error classes, `paginate()`, `RateLimiter`, the `Authenticator`
 interface (HMAC signing will plug in here) and `userAgentSuffix` to identify your tool.
 
 ## Development

package/dist/index.cjs

@@ -146,7 +146,7 @@ var CLIENT_ERROR_CODES = { UNEXPECTED_REDIRECT: "UNEXPECTED_REDIRECT" };
 function isKnownErrorCode(code) {
   return KNOWN_CODES.has(code);
 }
-var DEFAULT_RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var DEFAULT_RETRYABLE_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 var MAX_SERVER_WAIT_MS = 12e4;
 function retryAfterMs(headers, details) {
   let best = null;
@@ -296,6 +296,7 @@ var OPERATIONS = {
   get_ledger: op("GET", "/api/v1/account/ledger", "api_key", "read", "account.ledger"),
   list_notifications: op("GET", "/api/v1/account/notifications", "api_key", "read", "account.notifications"),
   list_sub_accounts: op("GET", "/api/v1/account/sub-accounts", "api_key", "read", "account.subAccounts"),
+  sub_account_balances: op("GET", "/api/v1/account/sub-accounts/{id}/balances", "api_key", "read", "account.subAccountBalances"),
   list_api_keys: op("GET", "/api/v1/account/api-keys", "api_key", "read", "account.apiKeys"),
   // Exports (read)
   export_deposits: op("GET", "/api/v1/exports/deposits", "api_key", "read", "exports.deposits"),
@@ -326,6 +327,7 @@ var OPERATIONS = {
 
 // src/http.ts
 var IDEMPOTENT_OPS = /* @__PURE__ */ new Set(["join_pool", "exit_pool"]);
+var REPEAT_SAFE_MUTATIONS = /* @__PURE__ */ new Set(["join_pool", "exit_pool", "cancel_all"]);
 var BACKOFF_BASE_MS = 500;
 var BACKOFF_MAX_MS = 1e4;
 var Transport = class {
@@ -337,13 +339,14 @@ var Transport = class {
    * Sends a request with the standard retry policy: retryable errors and network failures are
    * retried. Pool join/exit carry an `Idempotency-Key` reused on every attempt (the server
    * honours it there, which makes their retries safe); the other mutations routed here
-   * (cancel-all) are naturally repeatable and send no key. `placeOrder` and `cancelOrder` use
-   * `attempt()` with their own policies.
+   * (cancel-all) are naturally repeatable and send no key. Any other mutation is sent once.
+   * `placeOrder` and `cancelOrder` use `attempt()` with their own policies.
    */
   async request(spec, opts = {}) {
     const info = OPERATIONS[spec.op];
     const idempotencyKey = IDEMPOTENT_OPS.has(spec.op) ? spec.idempotencyKey ?? opts.idempotencyKey ?? newId() : void 0;
-    const maxRetries = opts.maxRetries ?? this.config.maxRetries;
+    const repeatSafe = info.method === "GET" || REPEAT_SAFE_MUTATIONS.has(spec.op);
+    const maxRetries = repeatSafe ? opts.maxRetries ?? this.config.maxRetries : 0;
     for (let attempt = 0; ; attempt++) {
       try {
         return await this.attempt({ ...spec, idempotencyKey }, opts);
@@ -458,6 +461,7 @@ var Transport = class {
     const path = info.path.replace(/\{(\w+)\}/g, (_m, name) => {
       const v = pathParams[name];
       if (typeof v !== "string" || v === "") throw new CexyConfigError(`${info.sdkMethod}(): ${name} is required`);
+      if (v === "." || v === "..") throw new CexyConfigError(`${info.sdkMethod}(): ${name} must not be "." or ".."`);
       return encodeURIComponent(v);
     });
     const url = new URL(this.config.baseUrl.replace(/\/+$/, "") + path);
@@ -480,7 +484,11 @@ function serverHintMs(err) {
 }
 function isRetryable(err) {
   if (err instanceof CexyConnectionError) return true;
-  if (err instanceof CexyApiError) return err.retryable || err.code === "CONCURRENT_MODIFICATION";
+  if (err instanceof CexyApiError) {
+    const concurrent = err.code === "CONCURRENT_MODIFICATION";
+    if (err.status >= 400 && err.status < 500 && err.status !== 429 && !(err.status === 409 && concurrent)) return false;
+    return err.retryable || concurrent;
+  }
   return false;
 }
 function isAmbiguous(err) {
@@ -752,12 +760,22 @@ var PoolsResource = class extends Resource {
     return this.data({ op: "exit_pool", pathParams: { symbol }, body }, opts);
   }
 };
+function withHeldIncoming(b) {
+  if (!b || typeof b !== "object" || Array.isArray(b.held_incoming)) return b;
+  return { ...b, held_incoming: [] };
+}
 var AccountResource = class extends Resource {
-  balances(opts) {
-    return this.data({ op: "list_balances" }, opts);
+  /**
+   * Balances per asset. `held_incoming` lists incoming internal transfers still held; their sum is
+   * already included in `locked` (never add it again). Always an array (`[]` when none).
+   */
+  async balances(opts) {
+    const rows = await this.data({ op: "list_balances" }, opts);
+    return Array.isArray(rows) ? rows.map(withHeldIncoming) : rows;
   }
-  balance(asset, opts) {
-    return this.data({ op: "get_balance", pathParams: { asset } }, opts);
+  /** One asset's balance. `held_incoming`: incoming transfers still held, already inside `locked`. */
+  async balance(asset, opts) {
+    return withHeldIncoming(await this.data({ op: "get_balance", pathParams: { asset } }, opts));
   }
   ledger(params, opts) {
     return this.page({ op: "get_ledger", query: params }, opts);
@@ -774,6 +792,20 @@ var AccountResource = class extends Resource {
   subAccounts(opts) {
     return this.data({ op: "list_sub_accounts" }, opts);
   }
+  /**
+   * A sub-account's balances, read by its PARENT account: the same shape as `balances()`
+   * (zero balances omitted), including `held_incoming`, whose sum is already inside `locked`.
+   * The server currently returns them ordered by asset symbol; don't rely on the order.
+   * An id that is not one of the caller's sub-accounts (or a call with the sub-account's own
+   * key) gets `NotFoundError`; a sub-account's own key reads its balances with `balances()`.
+   * A malformed id gets 400 (`ValidationError`); a key without the `read` scope gets 403
+   * `FORBIDDEN` (`ForbiddenError`). `id` must be non-empty and not "." or ".."; it is sent as
+   * one URL path segment.
+   */
+  async subAccountBalances(id, opts) {
+    const rows = await this.data({ op: "sub_account_balances", pathParams: { id } }, opts);
+    return Array.isArray(rows) ? rows.map(withHeldIncoming) : rows;
+  }
   /** Your API keys (metadata only; secrets are never returned). */
   apiKeys(opts) {
     return this.data({ op: "list_api_keys" }, opts);
@@ -1040,7 +1072,7 @@ var TradingResource = class extends Resource {
 };
 
 // src/version.ts
-var VERSION = "0.1.0-dev.6";
+var VERSION = "0.1.0-dev.7";
 var USER_AGENT = `cexy-typescript/${VERSION}`;
 
 // src/ws/emitter.ts

package/dist/index.d.cts

@@ -102,6 +102,7 @@ declare const OPERATIONS: {
     readonly get_ledger: OperationInfo;
     readonly list_notifications: OperationInfo;
     readonly list_sub_accounts: OperationInfo;
+    readonly sub_account_balances: OperationInfo;
     readonly list_api_keys: OperationInfo;
     readonly export_deposits: OperationInfo;
     readonly export_ledger: OperationInfo;
@@ -189,8 +190,8 @@ declare class Transport {
      * Sends a request with the standard retry policy: retryable errors and network failures are
      * retried. Pool join/exit carry an `Idempotency-Key` reused on every attempt (the server
      * honours it there, which makes their retries safe); the other mutations routed here
-     * (cancel-all) are naturally repeatable and send no key. `placeOrder` and `cancelOrder` use
-     * `attempt()` with their own policies.
+     * (cancel-all) are naturally repeatable and send no key. Any other mutation is sent once.
+     * `placeOrder` and `cancelOrder` use `attempt()` with their own policies.
      */
     request(spec: CallSpec, opts?: RequestOptions): Promise<RawResponse>;
     /**
@@ -205,7 +206,11 @@ declare class Transport {
     buildUrl(info: OperationInfo, pathParams?: Record<string, string>, query?: Record<string, unknown>): URL;
     redact(text: string): string;
 }
-/** Retryable = a network failure/timeout, or an API error with `retryable: true` (incl. 409 CONCURRENT_MODIFICATION). */
+/**
+ * Retryable = a network failure/timeout, or an API error with `retryable: true` (incl. 409
+ * CONCURRENT_MODIFICATION). A 4xx is never retryable except 429 and 409 CONCURRENT_MODIFICATION,
+ * whatever its body says.
+ */
 declare function isRetryable(err: unknown): boolean;
 
 interface paths {
@@ -314,6 +319,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/account/sub-accounts/{id}/balances": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * A sub-account's balances, for its parent.
+         * @description The same shape as `/account/balances`, zero balances omitted: what the sub-account holds, so its funds can be shown and moved back. Only the parent may read it; any id that is not one of the caller's sub-accounts is not found.
+         */
+        get: operations["sub_account_balances"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/assets": {
         parameters: {
             query?: never;
@@ -1041,6 +1066,8 @@ interface components {
             /** @description Asset symbol. */
             asset: string;
             available: components["schemas"]["Amount"];
+            /** @description Internal transfers to this account still held, soonest released first; empty when none. Their sum is part of `locked`. Shows at most 100. */
+            held_incoming: components["schemas"]["HeldIncomingResponse"][];
             locked: components["schemas"]["Amount"];
             pending: components["schemas"]["Amount"];
             total: components["schemas"]["Amount"];
@@ -1326,6 +1353,17 @@ interface components {
          * @example 507f1f77bcf86cd799439011
          */
         FuturesTransferId: string;
+        /** @description An internal transfer credited to `locked` and not yet available. */
+        HeldIncomingResponse: {
+            amount: components["schemas"]["Amount"];
+            /**
+             * Format: date-time
+             * @description When it becomes available, unless an operator cancels it before then.
+             */
+            available_at: string;
+            /** @description The transfer. */
+            transfer_id: string;
+        };
         /** @description Adds liquidity to a pool. */
         JoinPoolRequest: {
             base_amount: components["schemas"]["Amount"];
@@ -2081,6 +2119,49 @@ interface operations {
             };
         };
     };
+    sub_account_balances: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Sub-account id */
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The sub-account's balances */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["BalanceResponse"][];
+                    };
+                };
+            };
+            /** @description Malformed sub-account id */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description No such sub-account on this account */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     list_assets: {
         parameters: {
             query?: never;
@@ -3301,6 +3382,8 @@ type ApiScope = S["ApiScope"];
 type Asset = S["AssetResponse"];
 type AssetNetwork = S["AssetNetworkResponse"];
 type Balance = S["BalanceResponse"];
+/** An incoming internal transfer still held (see `Balance.held_incoming`). */
+type HeldIncoming = S["HeldIncomingResponse"];
 type CancelAllRequest = S["CancelAllRequest"];
 type CancelAllResult = S["CancelAllResponse"];
 /** Why one order could not be cancelled (`CancelAllResult.failures`). */
@@ -3458,13 +3541,29 @@ declare class PoolsResource extends Resource {
     exit(symbol: string, body: ExitPoolRequest, opts?: RequestOptions): Promise<ExitPoolResult>;
 }
 declare class AccountResource extends Resource {
+    /**
+     * Balances per asset. `held_incoming` lists incoming internal transfers still held; their sum is
+     * already included in `locked` (never add it again). Always an array (`[]` when none).
+     */
     balances(opts?: RequestOptions): Promise<Balance[]>;
+    /** One asset's balance. `held_incoming`: incoming transfers still held, already inside `locked`. */
     balance(asset: string, opts?: RequestOptions): Promise<Balance>;
     ledger(params?: Q<"get_ledger">, opts?: RequestOptions): Promise<Page<LedgerEntry>>;
     iterateLedger(params?: Q<"get_ledger">, iter?: IterateOptions & RequestOptions): AsyncGenerator<LedgerEntry, void, undefined>;
     notifications(params?: Q<"list_notifications">, opts?: RequestOptions): Promise<Page<Notification>>;
     iterateNotifications(params?: Q<"list_notifications">, iter?: IterateOptions & RequestOptions): AsyncGenerator<Notification, void, undefined>;
     subAccounts(opts?: RequestOptions): Promise<SubAccount[]>;
+    /**
+     * A sub-account's balances, read by its PARENT account: the same shape as `balances()`
+     * (zero balances omitted), including `held_incoming`, whose sum is already inside `locked`.
+     * The server currently returns them ordered by asset symbol; don't rely on the order.
+     * An id that is not one of the caller's sub-accounts (or a call with the sub-account's own
+     * key) gets `NotFoundError`; a sub-account's own key reads its balances with `balances()`.
+     * A malformed id gets 400 (`ValidationError`); a key without the `read` scope gets 403
+     * `FORBIDDEN` (`ForbiddenError`). `id` must be non-empty and not "." or ".."; it is sent as
+     * one URL path segment.
+     */
+    subAccountBalances(id: string, opts?: RequestOptions): Promise<Balance[]>;
     /** Your API keys (metadata only; secrets are never returned). */
     apiKeys(opts?: RequestOptions): Promise<ApiKey[]>;
 }
@@ -4167,11 +4266,11 @@ declare function isLedgerReference<T extends LedgerReferenceType>(ref: LedgerRef
 }>;
 
 /** SDK version, kept in sync with package.json (a test enforces this). */
-declare const VERSION = "0.1.0-dev.6";
+declare const VERSION = "0.1.0-dev.7";
 /** Default User-Agent product token. */
-declare const USER_AGENT = "cexy-typescript/0.1.0-dev.6";
+declare const USER_AGENT = "cexy-typescript/0.1.0-dev.7";
 
 /** True for loopback hosts, the only ones where plain-text transport may be allowed. */
 declare function isLocalHost(hostname: string): boolean;
 
-export { AccountResource, type Amount, type ApiKey, ApiKeyAuthenticator, type ApiScope, type Asset, type AssetNetwork, AssetsResource, type AuthRequest, type AuthResult, type AuthenticatedFrame, AuthenticationError, type Authenticator, type Balance, type BalanceUpdatedEvent, type BookLevel, CLIENT_ERROR_CODES, CancelAllInterruptedError, type CancelAllParams, type CancelAllRequest, type CancelAllResult, type CancelAllStopReason, type CancelAllUntilDoneResult, type CancelFailure, type Candle, type CandleInterval, CexyApiError, type CexyApiErrorInit, CexyClient, type CexyClientOptions, CexyConfigError, CexyConnectionError, CexyError, CexyTimeoutError, CexyWebSocket, CexyWebSocketError, type CexyWebSocketEvents, type CexyWebSocketOptions, type CloseInfo, ConflictError, type CursorParams, DEFAULT_BASE_URL, DEFAULT_RPM_ANONYMOUS, DEFAULT_RPM_WITH_KEY, DEFAULT_WS_URL, type Deposit, type DepositAddress, type DepositEvent, type DepositId, type DepositStatus, type ErrorBody, type ErrorCode, type ErrorFrame, type EventMap, type ExchangeConfig, type ExitPoolRequest, type ExitPoolResult, ExportsResource, type FeeSchedule, FeesResource, type FetchLike, type Fill, ForbiddenError, type FuturesTransferId, InvalidAmountError, type IterateOptions, type JoinPoolRequest, type JoinPoolResult, JurisdictionBlockedError, KNOWN_EVENT_TYPES, type KnownErrorCode, type KnownLedgerReference, type LedgerEntry, type LedgerEntryKind, type LedgerReference, type LedgerReferenceType, type LiquidityRole, type Listener, LiveOrderBook, type LiveOrderBookEvents, type LiveOrderBookOptions, MAX_SERVER_WAIT_MS, type MaintenanceState, type Market, type MarketStatus, type MarketStatusEvent, MarketsResource, type Network, NetworksResource, NotFoundError, type Notification, type NotificationKind, OPERATIONS, type OperationAuth, type OperationId, type OperationInfo, type OperationScope, type Order, type OrderBook, type OrderBookUpdateData, type OrderBookUpdateEvent, type OrderEvent, type OrderId, type OrderSide, OrderStateUnknownError, type OrderStatus, type OrderType, PRIVATE_CHANNELS, type Page, type PlaceOrderRequest, type PlaceOrderResponse, type PlaceOrderResult, type PongFrame, type Pool, type PoolId, type PoolStatus, PoolsResource, type PublicTrade, type QueryOf, RateLimitError, RateLimiter, type RateLimiterOptions, type RateLimiterState, type ReconnectOptions, type RequestOptions, type ResyncReason, type RetryInfo, SUPPORTED_PROTOCOL_VERSION, ServerError, type ServerTime, type SessionRevokedData, type SessionRevokedEvent, type SnapshotSource, type SortDirection, type SubAccount, type SubscribeResult, type SubscribedFrame, type TickerUpdateEvent, type TimeInForce, type TradeId, type TradeNewEvent, TradingResource, type TriggerDirection, TypedEmitter, USER_AGENT, type UnknownLedgerReference, UnprocessableError, type UnsubscribedFrame, type UserId, VERSION, ValidationError, WS_BOOK_DEPTH, WalletResource, type WebSocketConstructor, type WebSocketLike, type WelcomeFrame, type Withdrawal, type WithdrawalAddress, type WithdrawalId, type WithdrawalStatus, type WithdrawalUpdatedEvent, type WsEvent, type WsLogger, assertAmountFields, type components, errorFromResponse, isAmount, isKnownErrorCode, isLedgerReference, isLocalHost, isRetryable, type operations, paginate, type paths };
+export { AccountResource, type Amount, type ApiKey, ApiKeyAuthenticator, type ApiScope, type Asset, type AssetNetwork, AssetsResource, type AuthRequest, type AuthResult, type AuthenticatedFrame, AuthenticationError, type Authenticator, type Balance, type BalanceUpdatedEvent, type BookLevel, CLIENT_ERROR_CODES, CancelAllInterruptedError, type CancelAllParams, type CancelAllRequest, type CancelAllResult, type CancelAllStopReason, type CancelAllUntilDoneResult, type CancelFailure, type Candle, type CandleInterval, CexyApiError, type CexyApiErrorInit, CexyClient, type CexyClientOptions, CexyConfigError, CexyConnectionError, CexyError, CexyTimeoutError, CexyWebSocket, CexyWebSocketError, type CexyWebSocketEvents, type CexyWebSocketOptions, type CloseInfo, ConflictError, type CursorParams, DEFAULT_BASE_URL, DEFAULT_RPM_ANONYMOUS, DEFAULT_RPM_WITH_KEY, DEFAULT_WS_URL, type Deposit, type DepositAddress, type DepositEvent, type DepositId, type DepositStatus, type ErrorBody, type ErrorCode, type ErrorFrame, type EventMap, type ExchangeConfig, type ExitPoolRequest, type ExitPoolResult, ExportsResource, type FeeSchedule, FeesResource, type FetchLike, type Fill, ForbiddenError, type FuturesTransferId, type HeldIncoming, InvalidAmountError, type IterateOptions, type JoinPoolRequest, type JoinPoolResult, JurisdictionBlockedError, KNOWN_EVENT_TYPES, type KnownErrorCode, type KnownLedgerReference, type LedgerEntry, type LedgerEntryKind, type LedgerReference, type LedgerReferenceType, type LiquidityRole, type Listener, LiveOrderBook, type LiveOrderBookEvents, type LiveOrderBookOptions, MAX_SERVER_WAIT_MS, type MaintenanceState, type Market, type MarketStatus, type MarketStatusEvent, MarketsResource, type Network, NetworksResource, NotFoundError, type Notification, type NotificationKind, OPERATIONS, type OperationAuth, type OperationId, type OperationInfo, type OperationScope, type Order, type OrderBook, type OrderBookUpdateData, type OrderBookUpdateEvent, type OrderEvent, type OrderId, type OrderSide, OrderStateUnknownError, type OrderStatus, type OrderType, PRIVATE_CHANNELS, type Page, type PlaceOrderRequest, type PlaceOrderResponse, type PlaceOrderResult, type PongFrame, type Pool, type PoolId, type PoolStatus, PoolsResource, type PublicTrade, type QueryOf, RateLimitError, RateLimiter, type RateLimiterOptions, type RateLimiterState, type ReconnectOptions, type RequestOptions, type ResyncReason, type RetryInfo, SUPPORTED_PROTOCOL_VERSION, ServerError, type ServerTime, type SessionRevokedData, type SessionRevokedEvent, type SnapshotSource, type SortDirection, type SubAccount, type SubscribeResult, type SubscribedFrame, type TickerUpdateEvent, type TimeInForce, type TradeId, type TradeNewEvent, TradingResource, type TriggerDirection, TypedEmitter, USER_AGENT, type UnknownLedgerReference, UnprocessableError, type UnsubscribedFrame, type UserId, VERSION, ValidationError, WS_BOOK_DEPTH, WalletResource, type WebSocketConstructor, type WebSocketLike, type WelcomeFrame, type Withdrawal, type WithdrawalAddress, type WithdrawalId, type WithdrawalStatus, type WithdrawalUpdatedEvent, type WsEvent, type WsLogger, assertAmountFields, type components, errorFromResponse, isAmount, isKnownErrorCode, isLedgerReference, isLocalHost, isRetryable, type operations, paginate, type paths };

package/dist/index.d.ts

@@ -102,6 +102,7 @@ declare const OPERATIONS: {
     readonly get_ledger: OperationInfo;
     readonly list_notifications: OperationInfo;
     readonly list_sub_accounts: OperationInfo;
+    readonly sub_account_balances: OperationInfo;
     readonly list_api_keys: OperationInfo;
     readonly export_deposits: OperationInfo;
     readonly export_ledger: OperationInfo;
@@ -189,8 +190,8 @@ declare class Transport {
      * Sends a request with the standard retry policy: retryable errors and network failures are
      * retried. Pool join/exit carry an `Idempotency-Key` reused on every attempt (the server
      * honours it there, which makes their retries safe); the other mutations routed here
-     * (cancel-all) are naturally repeatable and send no key. `placeOrder` and `cancelOrder` use
-     * `attempt()` with their own policies.
+     * (cancel-all) are naturally repeatable and send no key. Any other mutation is sent once.
+     * `placeOrder` and `cancelOrder` use `attempt()` with their own policies.
      */
     request(spec: CallSpec, opts?: RequestOptions): Promise<RawResponse>;
     /**
@@ -205,7 +206,11 @@ declare class Transport {
     buildUrl(info: OperationInfo, pathParams?: Record<string, string>, query?: Record<string, unknown>): URL;
     redact(text: string): string;
 }
-/** Retryable = a network failure/timeout, or an API error with `retryable: true` (incl. 409 CONCURRENT_MODIFICATION). */
+/**
+ * Retryable = a network failure/timeout, or an API error with `retryable: true` (incl. 409
+ * CONCURRENT_MODIFICATION). A 4xx is never retryable except 429 and 409 CONCURRENT_MODIFICATION,
+ * whatever its body says.
+ */
 declare function isRetryable(err: unknown): boolean;
 
 interface paths {
@@ -314,6 +319,26 @@ interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/account/sub-accounts/{id}/balances": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * A sub-account's balances, for its parent.
+         * @description The same shape as `/account/balances`, zero balances omitted: what the sub-account holds, so its funds can be shown and moved back. Only the parent may read it; any id that is not one of the caller's sub-accounts is not found.
+         */
+        get: operations["sub_account_balances"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/assets": {
         parameters: {
             query?: never;
@@ -1041,6 +1066,8 @@ interface components {
             /** @description Asset symbol. */
             asset: string;
             available: components["schemas"]["Amount"];
+            /** @description Internal transfers to this account still held, soonest released first; empty when none. Their sum is part of `locked`. Shows at most 100. */
+            held_incoming: components["schemas"]["HeldIncomingResponse"][];
             locked: components["schemas"]["Amount"];
             pending: components["schemas"]["Amount"];
             total: components["schemas"]["Amount"];
@@ -1326,6 +1353,17 @@ interface components {
          * @example 507f1f77bcf86cd799439011
          */
         FuturesTransferId: string;
+        /** @description An internal transfer credited to `locked` and not yet available. */
+        HeldIncomingResponse: {
+            amount: components["schemas"]["Amount"];
+            /**
+             * Format: date-time
+             * @description When it becomes available, unless an operator cancels it before then.
+             */
+            available_at: string;
+            /** @description The transfer. */
+            transfer_id: string;
+        };
         /** @description Adds liquidity to a pool. */
         JoinPoolRequest: {
             base_amount: components["schemas"]["Amount"];
@@ -2081,6 +2119,49 @@ interface operations {
             };
         };
     };
+    sub_account_balances: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                /** @description Sub-account id */
+                id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The sub-account's balances */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        data: components["schemas"]["BalanceResponse"][];
+                    };
+                };
+            };
+            /** @description Malformed sub-account id */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            /** @description No such sub-account on this account */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     list_assets: {
         parameters: {
             query?: never;
@@ -3301,6 +3382,8 @@ type ApiScope = S["ApiScope"];
 type Asset = S["AssetResponse"];
 type AssetNetwork = S["AssetNetworkResponse"];
 type Balance = S["BalanceResponse"];
+/** An incoming internal transfer still held (see `Balance.held_incoming`). */
+type HeldIncoming = S["HeldIncomingResponse"];
 type CancelAllRequest = S["CancelAllRequest"];
 type CancelAllResult = S["CancelAllResponse"];
 /** Why one order could not be cancelled (`CancelAllResult.failures`). */
@@ -3458,13 +3541,29 @@ declare class PoolsResource extends Resource {
     exit(symbol: string, body: ExitPoolRequest, opts?: RequestOptions): Promise<ExitPoolResult>;
 }
 declare class AccountResource extends Resource {
+    /**
+     * Balances per asset. `held_incoming` lists incoming internal transfers still held; their sum is
+     * already included in `locked` (never add it again). Always an array (`[]` when none).
+     */
     balances(opts?: RequestOptions): Promise<Balance[]>;
+    /** One asset's balance. `held_incoming`: incoming transfers still held, already inside `locked`. */
     balance(asset: string, opts?: RequestOptions): Promise<Balance>;
     ledger(params?: Q<"get_ledger">, opts?: RequestOptions): Promise<Page<LedgerEntry>>;
     iterateLedger(params?: Q<"get_ledger">, iter?: IterateOptions & RequestOptions): AsyncGenerator<LedgerEntry, void, undefined>;
     notifications(params?: Q<"list_notifications">, opts?: RequestOptions): Promise<Page<Notification>>;
     iterateNotifications(params?: Q<"list_notifications">, iter?: IterateOptions & RequestOptions): AsyncGenerator<Notification, void, undefined>;
     subAccounts(opts?: RequestOptions): Promise<SubAccount[]>;
+    /**
+     * A sub-account's balances, read by its PARENT account: the same shape as `balances()`
+     * (zero balances omitted), including `held_incoming`, whose sum is already inside `locked`.
+     * The server currently returns them ordered by asset symbol; don't rely on the order.
+     * An id that is not one of the caller's sub-accounts (or a call with the sub-account's own
+     * key) gets `NotFoundError`; a sub-account's own key reads its balances with `balances()`.
+     * A malformed id gets 400 (`ValidationError`); a key without the `read` scope gets 403
+     * `FORBIDDEN` (`ForbiddenError`). `id` must be non-empty and not "." or ".."; it is sent as
+     * one URL path segment.
+     */
+    subAccountBalances(id: string, opts?: RequestOptions): Promise<Balance[]>;
     /** Your API keys (metadata only; secrets are never returned). */
     apiKeys(opts?: RequestOptions): Promise<ApiKey[]>;
 }
@@ -4167,11 +4266,11 @@ declare function isLedgerReference<T extends LedgerReferenceType>(ref: LedgerRef
 }>;
 
 /** SDK version, kept in sync with package.json (a test enforces this). */
-declare const VERSION = "0.1.0-dev.6";
+declare const VERSION = "0.1.0-dev.7";
 /** Default User-Agent product token. */
-declare const USER_AGENT = "cexy-typescript/0.1.0-dev.6";
+declare const USER_AGENT = "cexy-typescript/0.1.0-dev.7";
 
 /** True for loopback hosts, the only ones where plain-text transport may be allowed. */
 declare function isLocalHost(hostname: string): boolean;
 
-export { AccountResource, type Amount, type ApiKey, ApiKeyAuthenticator, type ApiScope, type Asset, type AssetNetwork, AssetsResource, type AuthRequest, type AuthResult, type AuthenticatedFrame, AuthenticationError, type Authenticator, type Balance, type BalanceUpdatedEvent, type BookLevel, CLIENT_ERROR_CODES, CancelAllInterruptedError, type CancelAllParams, type CancelAllRequest, type CancelAllResult, type CancelAllStopReason, type CancelAllUntilDoneResult, type CancelFailure, type Candle, type CandleInterval, CexyApiError, type CexyApiErrorInit, CexyClient, type CexyClientOptions, CexyConfigError, CexyConnectionError, CexyError, CexyTimeoutError, CexyWebSocket, CexyWebSocketError, type CexyWebSocketEvents, type CexyWebSocketOptions, type CloseInfo, ConflictError, type CursorParams, DEFAULT_BASE_URL, DEFAULT_RPM_ANONYMOUS, DEFAULT_RPM_WITH_KEY, DEFAULT_WS_URL, type Deposit, type DepositAddress, type DepositEvent, type DepositId, type DepositStatus, type ErrorBody, type ErrorCode, type ErrorFrame, type EventMap, type ExchangeConfig, type ExitPoolRequest, type ExitPoolResult, ExportsResource, type FeeSchedule, FeesResource, type FetchLike, type Fill, ForbiddenError, type FuturesTransferId, InvalidAmountError, type IterateOptions, type JoinPoolRequest, type JoinPoolResult, JurisdictionBlockedError, KNOWN_EVENT_TYPES, type KnownErrorCode, type KnownLedgerReference, type LedgerEntry, type LedgerEntryKind, type LedgerReference, type LedgerReferenceType, type LiquidityRole, type Listener, LiveOrderBook, type LiveOrderBookEvents, type LiveOrderBookOptions, MAX_SERVER_WAIT_MS, type MaintenanceState, type Market, type MarketStatus, type MarketStatusEvent, MarketsResource, type Network, NetworksResource, NotFoundError, type Notification, type NotificationKind, OPERATIONS, type OperationAuth, type OperationId, type OperationInfo, type OperationScope, type Order, type OrderBook, type OrderBookUpdateData, type OrderBookUpdateEvent, type OrderEvent, type OrderId, type OrderSide, OrderStateUnknownError, type OrderStatus, type OrderType, PRIVATE_CHANNELS, type Page, type PlaceOrderRequest, type PlaceOrderResponse, type PlaceOrderResult, type PongFrame, type Pool, type PoolId, type PoolStatus, PoolsResource, type PublicTrade, type QueryOf, RateLimitError, RateLimiter, type RateLimiterOptions, type RateLimiterState, type ReconnectOptions, type RequestOptions, type ResyncReason, type RetryInfo, SUPPORTED_PROTOCOL_VERSION, ServerError, type ServerTime, type SessionRevokedData, type SessionRevokedEvent, type SnapshotSource, type SortDirection, type SubAccount, type SubscribeResult, type SubscribedFrame, type TickerUpdateEvent, type TimeInForce, type TradeId, type TradeNewEvent, TradingResource, type TriggerDirection, TypedEmitter, USER_AGENT, type UnknownLedgerReference, UnprocessableError, type UnsubscribedFrame, type UserId, VERSION, ValidationError, WS_BOOK_DEPTH, WalletResource, type WebSocketConstructor, type WebSocketLike, type WelcomeFrame, type Withdrawal, type WithdrawalAddress, type WithdrawalId, type WithdrawalStatus, type WithdrawalUpdatedEvent, type WsEvent, type WsLogger, assertAmountFields, type components, errorFromResponse, isAmount, isKnownErrorCode, isLedgerReference, isLocalHost, isRetryable, type operations, paginate, type paths };
+export { AccountResource, type Amount, type ApiKey, ApiKeyAuthenticator, type ApiScope, type Asset, type AssetNetwork, AssetsResource, type AuthRequest, type AuthResult, type AuthenticatedFrame, AuthenticationError, type Authenticator, type Balance, type BalanceUpdatedEvent, type BookLevel, CLIENT_ERROR_CODES, CancelAllInterruptedError, type CancelAllParams, type CancelAllRequest, type CancelAllResult, type CancelAllStopReason, type CancelAllUntilDoneResult, type CancelFailure, type Candle, type CandleInterval, CexyApiError, type CexyApiErrorInit, CexyClient, type CexyClientOptions, CexyConfigError, CexyConnectionError, CexyError, CexyTimeoutError, CexyWebSocket, CexyWebSocketError, type CexyWebSocketEvents, type CexyWebSocketOptions, type CloseInfo, ConflictError, type CursorParams, DEFAULT_BASE_URL, DEFAULT_RPM_ANONYMOUS, DEFAULT_RPM_WITH_KEY, DEFAULT_WS_URL, type Deposit, type DepositAddress, type DepositEvent, type DepositId, type DepositStatus, type ErrorBody, type ErrorCode, type ErrorFrame, type EventMap, type ExchangeConfig, type ExitPoolRequest, type ExitPoolResult, ExportsResource, type FeeSchedule, FeesResource, type FetchLike, type Fill, ForbiddenError, type FuturesTransferId, type HeldIncoming, InvalidAmountError, type IterateOptions, type JoinPoolRequest, type JoinPoolResult, JurisdictionBlockedError, KNOWN_EVENT_TYPES, type KnownErrorCode, type KnownLedgerReference, type LedgerEntry, type LedgerEntryKind, type LedgerReference, type LedgerReferenceType, type LiquidityRole, type Listener, LiveOrderBook, type LiveOrderBookEvents, type LiveOrderBookOptions, MAX_SERVER_WAIT_MS, type MaintenanceState, type Market, type MarketStatus, type MarketStatusEvent, MarketsResource, type Network, NetworksResource, NotFoundError, type Notification, type NotificationKind, OPERATIONS, type OperationAuth, type OperationId, type OperationInfo, type OperationScope, type Order, type OrderBook, type OrderBookUpdateData, type OrderBookUpdateEvent, type OrderEvent, type OrderId, type OrderSide, OrderStateUnknownError, type OrderStatus, type OrderType, PRIVATE_CHANNELS, type Page, type PlaceOrderRequest, type PlaceOrderResponse, type PlaceOrderResult, type PongFrame, type Pool, type PoolId, type PoolStatus, PoolsResource, type PublicTrade, type QueryOf, RateLimitError, RateLimiter, type RateLimiterOptions, type RateLimiterState, type ReconnectOptions, type RequestOptions, type ResyncReason, type RetryInfo, SUPPORTED_PROTOCOL_VERSION, ServerError, type ServerTime, type SessionRevokedData, type SessionRevokedEvent, type SnapshotSource, type SortDirection, type SubAccount, type SubscribeResult, type SubscribedFrame, type TickerUpdateEvent, type TimeInForce, type TradeId, type TradeNewEvent, TradingResource, type TriggerDirection, TypedEmitter, USER_AGENT, type UnknownLedgerReference, UnprocessableError, type UnsubscribedFrame, type UserId, VERSION, ValidationError, WS_BOOK_DEPTH, WalletResource, type WebSocketConstructor, type WebSocketLike, type WelcomeFrame, type Withdrawal, type WithdrawalAddress, type WithdrawalId, type WithdrawalStatus, type WithdrawalUpdatedEvent, type WsEvent, type WsLogger, assertAmountFields, type components, errorFromResponse, isAmount, isKnownErrorCode, isLedgerReference, isLocalHost, isRetryable, type operations, paginate, type paths };

package/dist/index.js

@@ -144,7 +144,7 @@ var CLIENT_ERROR_CODES = { UNEXPECTED_REDIRECT: "UNEXPECTED_REDIRECT" };
 function isKnownErrorCode(code) {
   return KNOWN_CODES.has(code);
 }
-var DEFAULT_RETRYABLE_STATUS = /* @__PURE__ */ new Set([408, 429, 500, 502, 503, 504]);
+var DEFAULT_RETRYABLE_STATUS = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
 var MAX_SERVER_WAIT_MS = 12e4;
 function retryAfterMs(headers, details) {
   let best = null;
@@ -294,6 +294,7 @@ var OPERATIONS = {
   get_ledger: op("GET", "/api/v1/account/ledger", "api_key", "read", "account.ledger"),
   list_notifications: op("GET", "/api/v1/account/notifications", "api_key", "read", "account.notifications"),
   list_sub_accounts: op("GET", "/api/v1/account/sub-accounts", "api_key", "read", "account.subAccounts"),
+  sub_account_balances: op("GET", "/api/v1/account/sub-accounts/{id}/balances", "api_key", "read", "account.subAccountBalances"),
   list_api_keys: op("GET", "/api/v1/account/api-keys", "api_key", "read", "account.apiKeys"),
   // Exports (read)
   export_deposits: op("GET", "/api/v1/exports/deposits", "api_key", "read", "exports.deposits"),
@@ -324,6 +325,7 @@ var OPERATIONS = {
 
 // src/http.ts
 var IDEMPOTENT_OPS = /* @__PURE__ */ new Set(["join_pool", "exit_pool"]);
+var REPEAT_SAFE_MUTATIONS = /* @__PURE__ */ new Set(["join_pool", "exit_pool", "cancel_all"]);
 var BACKOFF_BASE_MS = 500;
 var BACKOFF_MAX_MS = 1e4;
 var Transport = class {
@@ -335,13 +337,14 @@ var Transport = class {
    * Sends a request with the standard retry policy: retryable errors and network failures are
    * retried. Pool join/exit carry an `Idempotency-Key` reused on every attempt (the server
    * honours it there, which makes their retries safe); the other mutations routed here
-   * (cancel-all) are naturally repeatable and send no key. `placeOrder` and `cancelOrder` use
-   * `attempt()` with their own policies.
+   * (cancel-all) are naturally repeatable and send no key. Any other mutation is sent once.
+   * `placeOrder` and `cancelOrder` use `attempt()` with their own policies.
    */
   async request(spec, opts = {}) {
     const info = OPERATIONS[spec.op];
     const idempotencyKey = IDEMPOTENT_OPS.has(spec.op) ? spec.idempotencyKey ?? opts.idempotencyKey ?? newId() : void 0;
-    const maxRetries = opts.maxRetries ?? this.config.maxRetries;
+    const repeatSafe = info.method === "GET" || REPEAT_SAFE_MUTATIONS.has(spec.op);
+    const maxRetries = repeatSafe ? opts.maxRetries ?? this.config.maxRetries : 0;
     for (let attempt = 0; ; attempt++) {
       try {
         return await this.attempt({ ...spec, idempotencyKey }, opts);
@@ -456,6 +459,7 @@ var Transport = class {
     const path = info.path.replace(/\{(\w+)\}/g, (_m, name) => {
       const v = pathParams[name];
       if (typeof v !== "string" || v === "") throw new CexyConfigError(`${info.sdkMethod}(): ${name} is required`);
+      if (v === "." || v === "..") throw new CexyConfigError(`${info.sdkMethod}(): ${name} must not be "." or ".."`);
       return encodeURIComponent(v);
     });
     const url = new URL(this.config.baseUrl.replace(/\/+$/, "") + path);
@@ -478,7 +482,11 @@ function serverHintMs(err) {
 }
 function isRetryable(err) {
   if (err instanceof CexyConnectionError) return true;
-  if (err instanceof CexyApiError) return err.retryable || err.code === "CONCURRENT_MODIFICATION";
+  if (err instanceof CexyApiError) {
+    const concurrent = err.code === "CONCURRENT_MODIFICATION";
+    if (err.status >= 400 && err.status < 500 && err.status !== 429 && !(err.status === 409 && concurrent)) return false;
+    return err.retryable || concurrent;
+  }
   return false;
 }
 function isAmbiguous(err) {
@@ -750,12 +758,22 @@ var PoolsResource = class extends Resource {
     return this.data({ op: "exit_pool", pathParams: { symbol }, body }, opts);
   }
 };
+function withHeldIncoming(b) {
+  if (!b || typeof b !== "object" || Array.isArray(b.held_incoming)) return b;
+  return { ...b, held_incoming: [] };
+}
 var AccountResource = class extends Resource {
-  balances(opts) {
-    return this.data({ op: "list_balances" }, opts);
+  /**
+   * Balances per asset. `held_incoming` lists incoming internal transfers still held; their sum is
+   * already included in `locked` (never add it again). Always an array (`[]` when none).
+   */
+  async balances(opts) {
+    const rows = await this.data({ op: "list_balances" }, opts);
+    return Array.isArray(rows) ? rows.map(withHeldIncoming) : rows;
   }
-  balance(asset, opts) {
-    return this.data({ op: "get_balance", pathParams: { asset } }, opts);
+  /** One asset's balance. `held_incoming`: incoming transfers still held, already inside `locked`. */
+  async balance(asset, opts) {
+    return withHeldIncoming(await this.data({ op: "get_balance", pathParams: { asset } }, opts));
   }
   ledger(params, opts) {
     return this.page({ op: "get_ledger", query: params }, opts);
@@ -772,6 +790,20 @@ var AccountResource = class extends Resource {
   subAccounts(opts) {
     return this.data({ op: "list_sub_accounts" }, opts);
   }
+  /**
+   * A sub-account's balances, read by its PARENT account: the same shape as `balances()`
+   * (zero balances omitted), including `held_incoming`, whose sum is already inside `locked`.
+   * The server currently returns them ordered by asset symbol; don't rely on the order.
+   * An id that is not one of the caller's sub-accounts (or a call with the sub-account's own
+   * key) gets `NotFoundError`; a sub-account's own key reads its balances with `balances()`.
+   * A malformed id gets 400 (`ValidationError`); a key without the `read` scope gets 403
+   * `FORBIDDEN` (`ForbiddenError`). `id` must be non-empty and not "." or ".."; it is sent as
+   * one URL path segment.
+   */
+  async subAccountBalances(id, opts) {
+    const rows = await this.data({ op: "sub_account_balances", pathParams: { id } }, opts);
+    return Array.isArray(rows) ? rows.map(withHeldIncoming) : rows;
+  }
   /** Your API keys (metadata only; secrets are never returned). */
   apiKeys(opts) {
     return this.data({ op: "list_api_keys" }, opts);
@@ -1038,7 +1070,7 @@ var TradingResource = class extends Resource {
 };
 
 // src/version.ts
-var VERSION = "0.1.0-dev.6";
+var VERSION = "0.1.0-dev.7";
 var USER_AGENT = `cexy-typescript/${VERSION}`;
 
 // src/ws/emitter.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cexyio/cexy",
-  "version": "0.1.0-dev.6",
+  "version": "0.1.0-dev.7",
   "description": "Official TypeScript/JavaScript SDK for the CEXY.io REST and WebSocket API",
   "license": "MIT",
   "author": "CEXY.io",