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

package/dist/index.d.ts

@@ -54,6 +54,11 @@ declare class RateLimiter {
     get state(): RateLimiterState;
     /** Waits until a request may be sent, then takes a token. */
     acquire(signal?: AbortSignal): Promise<void>;
+    /**
+     * How long `acquire()` would wait right now, in ms (0 when a request may go at once). Lets a
+     * caller with a time budget, such as the cancelAll untilDone loop, count the limiter's wait.
+     */
+    pendingWaitMs(): number;
     /** Adapts to the server's rate-limit headers. Never raises the configured limit. */
     update(headers: Headers): void;
     /**
@@ -97,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;
@@ -184,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>;
     /**
@@ -200,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 {
@@ -309,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;
@@ -731,8 +761,10 @@ interface paths {
         get?: never;
         put?: never;
         /**
-         * Cancels every open order, optionally within one market.
-         * @description Best-effort: a failure on one order does not stop the rest, and every outcome is reported. A panic-button endpoint that stops at the first problem is worse than useless.
+         * Cancels every open order, and every stop order that has not triggered, optionally within
+         * @description one market.
+         *
+         *     Best-effort: a failure on one order does not stop the rest, and every outcome is reported. A panic-button endpoint that stops at the first problem is worse than useless. A stop waiting for its trigger (`pending_trigger`) is cancelled too and its reservation released, so nothing fires into the market after the call.
          *
          *     An order still being placed when the call starts (status `pending`, for as long as its own placement request runs) is waited for, up to 500 ms per call in total: cancelled if it opens, reported in `already_closed` if it fills or is refused, and in `failed` with code `INVALID_STATE` if it is still being placed at the deadline. Orders placed after the call starts are not part of it. At most 500 orders per call; `has_more` says there are others.
          *
@@ -1034,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"];
@@ -1117,6 +1151,11 @@ interface components {
             /** @description Network code. */
             network: string;
         };
+        /**
+         * @description Unique identifier of a deposit.
+         * @example 507f1f77bcf86cd799439011
+         */
+        DepositId: string;
         /** @description A deposit. */
         DepositResponse: {
             /** @description Address that received it. */
@@ -1198,7 +1237,7 @@ interface components {
          *     Serialized as `SCREAMING_SNAKE_CASE`. Adding a variant is backwards-compatible; renaming or removing one is a breaking API change.
          * @enum {string}
          */
-        ErrorCode: "VALIDATION_FAILED" | "MALFORMED_REQUEST" | "INVALID_CURSOR" | "PRECISION_EXCEEDED" | "BELOW_MINIMUM" | "ABOVE_MAXIMUM" | "INVALID_ADDRESS" | "MEMO_REQUIRED" | "UNAUTHENTICATED" | "INVALID_CREDENTIALS" | "TOKEN_EXPIRED" | "SESSION_REVOKED" | "TWO_FACTOR_REQUIRED" | "TWO_FACTOR_INVALID" | "FRESH_TWO_FACTOR_REQUIRED" | "FORBIDDEN" | "API_KEY_NOT_ALLOWED" | "FUTURES_RESTRICTED" | "ACCOUNT_FROZEN" | "ACCOUNT_ON_HOLD" | "EMAIL_NOT_VERIFIED" | "REGION_BLOCKED" | "JURISDICTION_BLOCKED" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "ALREADY_EXISTS" | "INVALID_STATE" | "IDEMPOTENCY_KEY_CONFLICT" | "WINDOW_OPEN" | "EVIDENCE_CONTRADICTS" | "AMOUNT_MISMATCH" | "CONCURRENT_MODIFICATION" | "INSUFFICIENT_FUNDS" | "INSUFFICIENT_FEE_FUNDS" | "MARKET_UNAVAILABLE" | "DEPOSIT_DISABLED" | "WITHDRAWAL_DISABLED" | "SELF_TRADE_BLOCKED" | "LIMIT_EXCEEDED" | "RATE_LIMITED" | "INTERNAL" | "SERVICE_UNAVAILABLE" | "UNDER_MAINTENANCE" | "ENGINE_OVERLOADED";
+        ErrorCode: "VALIDATION_FAILED" | "MALFORMED_REQUEST" | "INVALID_CURSOR" | "PRECISION_EXCEEDED" | "BELOW_MINIMUM" | "ABOVE_MAXIMUM" | "INVALID_ADDRESS" | "MEMO_REQUIRED" | "UNAUTHENTICATED" | "INVALID_CREDENTIALS" | "TOKEN_EXPIRED" | "SESSION_REVOKED" | "TWO_FACTOR_REQUIRED" | "TWO_FACTOR_INVALID" | "FRESH_TWO_FACTOR_REQUIRED" | "FORBIDDEN" | "API_KEY_NOT_ALLOWED" | "FUTURES_RESTRICTED" | "ACCOUNT_FROZEN" | "ACCOUNT_ON_HOLD" | "EMAIL_NOT_VERIFIED" | "REGION_BLOCKED" | "JURISDICTION_BLOCKED" | "NOT_FOUND" | "METHOD_NOT_ALLOWED" | "ALREADY_EXISTS" | "INVALID_STATE" | "IDEMPOTENCY_KEY_CONFLICT" | "WINDOW_OPEN" | "EVIDENCE_CONTRADICTS" | "AMOUNT_MISMATCH" | "CONCURRENT_MODIFICATION" | "INSUFFICIENT_FUNDS" | "INSUFFICIENT_FEE_FUNDS" | "MARKET_UNAVAILABLE" | "DEPOSIT_DISABLED" | "WITHDRAWAL_DISABLED" | "SELF_TRADE_BLOCKED" | "LIMIT_EXCEEDED" | "PRICE_UNAVAILABLE" | "RATE_LIMITED" | "INTERNAL" | "SERVICE_UNAVAILABLE" | "UNDER_MAINTENANCE" | "ENGINE_OVERLOADED";
         /** @description The top-level error envelope. */
         ErrorResponse: {
             error: components["schemas"]["ErrorBody"];
@@ -1309,14 +1348,26 @@ interface components {
             /** @description Trade id. */
             trade_id: string;
         };
+        /**
+         * @description Unique identifier of a futures collateral transfer.
+         * @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"];
-            /**
-             * @description How far, in percent, the offered ratio may sit from the pool's own before the request is refused rather than repriced. Defaults to 1%.
-             * @example 1
-             */
-            max_ratio_deviation_percent?: string | null;
+            max_ratio_deviation_percent?: components["schemas"]["Amount"] | null;
             quote_amount: components["schemas"]["Amount"];
         };
         /** @description What a join produced. */
@@ -1330,7 +1381,7 @@ interface components {
          * @description What a ledger entry records.
          * @enum {string}
          */
-        LedgerEntryKind: "deposit" | "deposit_reversal" | "withdrawal_debit" | "withdrawal_fee" | "withdrawal_fee_reserve" | "withdrawal_release" | "withdrawal_fee_release" | "order_reserve" | "withdrawal_reserve" | "order_release" | "trade_debit" | "trade_credit" | "trade_fee" | "transfer_out" | "transfer_in" | "adjustment_credit" | "adjustment_debit" | "rebate" | "pool_join" | "pool_exit" | "futures_transfer_reserve" | "futures_transfer_release" | "futures_collateral_sent" | "futures_collateral_returned" | "trade_fee_revenue" | "withdrawal_fee_revenue" | "futures_transfer_fee_revenue" | "futures_hyperliquid_cost" | "futures_transfer_discrepancy" | "exchange_capital";
+        LedgerEntryKind: "deposit" | "deposit_reversal" | "withdrawal_debit" | "withdrawal_fee" | "withdrawal_fee_reserve" | "withdrawal_release" | "withdrawal_fee_release" | "order_reserve" | "withdrawal_reserve" | "order_release" | "trade_debit" | "trade_credit" | "trade_fee" | "transfer_out" | "transfer_in" | "transfer_in_held" | "transfer_release" | "transfer_reversal" | "adjustment_credit" | "adjustment_debit" | "rebate" | "pool_join" | "pool_exit" | "futures_transfer_reserve" | "futures_transfer_release" | "futures_collateral_sent" | "futures_collateral_returned" | "trade_fee_revenue" | "withdrawal_fee_revenue" | "withdrawal_refund" | "withdrawal_fee_revenue_reversal" | "futures_transfer_fee_revenue" | "futures_hyperliquid_cost" | "futures_transfer_discrepancy" | "exchange_capital";
         /** @description One entry from the account's ledger. */
         LedgerEntryResponse: {
             /** @description Asset symbol. */
@@ -1347,14 +1398,55 @@ interface components {
             kind: components["schemas"]["LedgerEntryKind"];
             locked_delta: components["schemas"]["Amount"];
             pending_delta: components["schemas"]["Amount"];
-            /** @description What caused the entry. */
-            reference: unknown;
+            reference: components["schemas"]["LedgerReference"];
             /**
              * Format: int64
              * @description Position in this account's history for this asset.
              */
             sequence: number;
         };
+        /** @description What caused a ledger entry: one kind of cause per variant, told apart by `type`. */
+        LedgerReference: {
+            deposit_id: components["schemas"]["DepositId"];
+            /** @enum {string} */
+            type: "deposit";
+        } | {
+            /** @enum {string} */
+            type: "withdrawal";
+            withdrawal_id: components["schemas"]["WithdrawalId"];
+        } | {
+            order_id: components["schemas"]["OrderId"];
+            /** @enum {string} */
+            type: "order";
+        } | {
+            order_id: components["schemas"]["OrderId"];
+            trade_id: components["schemas"]["TradeId"];
+            /** @enum {string} */
+            type: "trade";
+        } | {
+            counterparty_user_id: components["schemas"]["UserId"];
+            /** @description Shared reference linking both halves. */
+            transfer_ref: string;
+            /** @enum {string} */
+            type: "transfer";
+        } | {
+            operator_user_id: components["schemas"]["UserId"];
+            /** @enum {string} */
+            type: "adjustment";
+        } | {
+            pool_id: components["schemas"]["PoolId"];
+            /** @enum {string} */
+            type: "pool";
+        } | {
+            futures_transfer_id: components["schemas"]["FuturesTransferId"];
+            /** @enum {string} */
+            type: "futures_transfer";
+        } | {
+            /** @description Short machine-readable cause. */
+            cause: string;
+            /** @enum {string} */
+            type: "system";
+        };
         /**
          * @description Whether a fill added liquidity (maker) or removed it (taker).
          * @enum {string}
@@ -1514,6 +1606,11 @@ interface components {
              */
             timestamp: string;
         };
+        /**
+         * @description Unique identifier of an order.
+         * @example 507f1f77bcf86cd799439011
+         */
+        OrderId: string;
         /** @description An order. */
         OrderResponse: {
             average_price?: components["schemas"]["Amount"] | null;
@@ -1616,6 +1713,11 @@ interface components {
             fills: components["schemas"]["FillResponse"][];
             order: components["schemas"]["OrderResponse"];
         };
+        /**
+         * @description Unique identifier of a liquidity pool.
+         * @example 507f1f77bcf86cd799439011
+         */
+        PoolId: string;
         /**
          * @description A pool as a client sees it.
          *
@@ -1717,6 +1819,11 @@ interface components {
          * @enum {string}
          */
         TimeInForce: "gtc" | "ioc" | "fok" | "post_only";
+        /**
+         * @description Unique identifier of a trade.
+         * @example 507f1f77bcf86cd799439011
+         */
+        TradeId: string;
         /**
          * @description Which way the price must move for a stop to fire.
          *
@@ -1724,6 +1831,11 @@ interface components {
          * @enum {string}
          */
         TriggerDirection: "above" | "below";
+        /**
+         * @description Unique identifier of a user account.
+         * @example 507f1f77bcf86cd799439011
+         */
+        UserId: string;
         /** @description A saved withdrawal address. */
         WithdrawalAddressResponse: {
             /** @description The address. */
@@ -1762,6 +1874,11 @@ interface components {
             reason?: string | null;
             status: components["schemas"]["WithdrawalStatus"];
         };
+        /**
+         * @description Unique identifier of a withdrawal.
+         * @example 507f1f77bcf86cd799439011
+         */
+        WithdrawalId: string;
         /** @description A withdrawal. */
         WithdrawalResponse: {
             /** @description Destination. */
@@ -1818,7 +1935,7 @@ interface components {
          *     against the chain.
          * @enum {string}
          */
-        WithdrawalStatus: "requested" | "pending_approval" | "approved" | "processing" | "broadcast" | "completed" | "rejected" | "cancelled" | "failed" | "broadcast_unknown";
+        WithdrawalStatus: "requested" | "pending_approval" | "approved" | "processing" | "broadcast" | "completed" | "rejected" | "cancelled" | "failed" | "broadcast_unknown" | "reverted";
     };
     responses: never;
     parameters: never;
@@ -2002,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;
@@ -3222,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`). */
@@ -3256,7 +3418,31 @@ type FeeSchedule = S["FeeScheduleResponse"];
 type Fill = S["FillResponse"];
 type JoinPoolRequest = S["JoinPoolRequest"];
 type JoinPoolResult = S["JoinPoolResponse"];
-type LedgerEntry = S["LedgerEntryResponse"];
+/** A ledger entry. `reference` also accepts cause types this SDK version does not know yet. */
+type LedgerEntry = Omit<S["LedgerEntryResponse"], "reference"> & {
+    reference: LedgerReference;
+};
+/** What caused a ledger entry, as documented: one variant per `type`. */
+type KnownLedgerReference = S["LedgerReference"];
+/** The documented `LedgerReference` types. */
+type LedgerReferenceType = KnownLedgerReference["type"];
+/**
+ * A cause type this SDK version does not know yet (the server may add new ones). The object is
+ * kept as sent. Use `isLedgerReference()` to narrow to a documented variant.
+ */
+interface UnknownLedgerReference {
+    type: string;
+    [field: string]: unknown;
+}
+/** `LedgerEntry.reference`: a documented variant or an unknown one; never throws on new types. */
+type LedgerReference = KnownLedgerReference | UnknownLedgerReference;
+type DepositId = S["DepositId"];
+type FuturesTransferId = S["FuturesTransferId"];
+type OrderId = S["OrderId"];
+type PoolId = S["PoolId"];
+type TradeId = S["TradeId"];
+type UserId = S["UserId"];
+type WithdrawalId = S["WithdrawalId"];
 type LedgerEntryKind = S["LedgerEntryKind"];
 type LiquidityRole = S["LiquidityRole"];
 type MaintenanceState = S["MaintenanceState"];
@@ -3355,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[]>;
 }
@@ -3449,6 +3651,8 @@ declare class TradingResource extends Resource {
     cancelOrder(orderId: string, opts?: RequestOptions): Promise<Order>;
     /**
      * Cancels every open order in one market: `cancelAll({ symbol: "BTC/USDT" })`.
+     * This includes stop orders that have not triggered yet (status `pending_trigger`): they are
+     * cancelled and their reservations released, so nothing fires into the market afterwards.
      * To cancel across ALL markets, pass `symbol: null` explicitly: `cancelAll({ symbol: null })`.
      * Omitting `symbol` is an error, so an account-wide cancel never happens by accident
      * (the server itself treats `{}` as every market). An unknown symbol throws `NotFoundError`.
@@ -4050,12 +4254,23 @@ declare function isAmount(value: unknown): value is Amount;
  */
 declare function assertAmountFields(body: Record<string, unknown>, fields: readonly string[], context: string): void;
 
+/**
+ * Narrows a ledger entry's `reference`:
+ * - `isLedgerReference(ref)`: true for any documented variant;
+ * - `isLedgerReference(ref, "trade")`: true only for that variant, typed accordingly.
+ * Unknown (newer) types return false and keep their raw fields.
+ */
+declare function isLedgerReference(ref: LedgerReference): ref is KnownLedgerReference;
+declare function isLedgerReference<T extends LedgerReferenceType>(ref: LedgerReference, type: T): ref is Extract<KnownLedgerReference, {
+    type: T;
+}>;
+
 /** SDK version, kept in sync with package.json (a test enforces this). */
-declare const VERSION = "0.1.0-dev.5";
+declare const VERSION = "0.1.0-dev.7";
 /** Default User-Agent product token. */
-declare const USER_AGENT = "cexy-typescript/0.1.0-dev.5";
+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 DepositStatus, type ErrorBody, type ErrorCode, type ErrorFrame, type EventMap, type ExchangeConfig, type ExitPoolRequest, type ExitPoolResult, ExportsResource, type FeeSchedule, FeesResource, type FetchLike, type Fill, ForbiddenError, InvalidAmountError, type IterateOptions, type JoinPoolRequest, type JoinPoolResult, JurisdictionBlockedError, KNOWN_EVENT_TYPES, type KnownErrorCode, type LedgerEntry, type LedgerEntryKind, 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 OrderSide, OrderStateUnknownError, type OrderStatus, type OrderType, PRIVATE_CHANNELS, type Page, type PlaceOrderRequest, type PlaceOrderResponse, type PlaceOrderResult, type PongFrame, type Pool, 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 TradeNewEvent, TradingResource, type TriggerDirection, TypedEmitter, USER_AGENT, UnprocessableError, type UnsubscribedFrame, VERSION, ValidationError, WS_BOOK_DEPTH, WalletResource, type WebSocketConstructor, type WebSocketLike, type WelcomeFrame, type Withdrawal, type WithdrawalAddress, type WithdrawalStatus, type WithdrawalUpdatedEvent, type WsEvent, type WsLogger, assertAmountFields, type components, errorFromResponse, isAmount, isKnownErrorCode, 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

@@ -137,13 +137,14 @@ var KNOWN_CODES = /* @__PURE__ */ new Set([
   "INTERNAL",
   "SERVICE_UNAVAILABLE",
   "UNDER_MAINTENANCE",
-  "ENGINE_OVERLOADED"
+  "ENGINE_OVERLOADED",
+  "PRICE_UNAVAILABLE"
 ]);
 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;
@@ -293,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"),
@@ -323,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 {
@@ -334,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);
@@ -455,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);
@@ -477,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) {
@@ -543,6 +552,17 @@ var RateLimiter = class {
       await this.#sleep(Math.min(MAX_BLOCK_MS, Math.ceil((1 - this.#tokens) * msPerToken)), signal);
     }
   }
+  /**
+   * How long `acquire()` would wait right now, in ms (0 when a request may go at once). Lets a
+   * caller with a time budget, such as the cancelAll untilDone loop, count the limiter's wait.
+   */
+  pendingWaitMs() {
+    this.#refill();
+    const block = this.#blockedUntil - this.#now();
+    if (block > 0) return block;
+    if (this.#tokens >= 1) return 0;
+    return Math.min(MAX_BLOCK_MS, Math.ceil((1 - this.#tokens) * (6e4 / this.#rpm)));
+  }
   /** Adapts to the server's rate-limit headers. Never raises the configured limit. */
   update(headers) {
     this.#refill();
@@ -738,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);
@@ -760,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);
@@ -1013,8 +1057,10 @@ var TradingResource = class extends Resource {
         if (progress) idle = 0;
         else waitMs = (CANCEL_BACKOFF_S[Math.min(idle++, CANCEL_BACKOFF_S.length - 1)] ?? 15) * 1e3;
       }
-      if (now() - start + waitMs >= budgetMs) {
+      const limiterMs = this.t.config.limiter?.pendingWaitMs() ?? 0;
+      if (now() - start + Math.max(waitMs, limiterMs) >= budgetMs) {
         stopped = "time_budget";
+        if (limiterMs > waitMs) lastErrorCode = "RATE_LIMITED";
         break;
       }
       if (waitMs > 0) await this.t.config.sleep(waitMs, opts?.signal);
@@ -1024,7 +1070,7 @@ var TradingResource = class extends Resource {
 };
 
 // src/version.ts
-var VERSION = "0.1.0-dev.5";
+var VERSION = "0.1.0-dev.7";
 var USER_AGENT = `cexy-typescript/${VERSION}`;
 
 // src/ws/emitter.ts
@@ -1876,4 +1922,21 @@ function canSetUserAgent() {
   return !(typeof g.window !== "undefined" && typeof g.window.document !== "undefined");
 }
 
-export { AccountResource, ApiKeyAuthenticator, AssetsResource, AuthenticationError, CLIENT_ERROR_CODES, CancelAllInterruptedError, CexyApiError, CexyClient, CexyConfigError, CexyConnectionError, CexyError, CexyTimeoutError, CexyWebSocket, CexyWebSocketError, ConflictError, DEFAULT_BASE_URL, DEFAULT_RPM_ANONYMOUS, DEFAULT_RPM_WITH_KEY, DEFAULT_WS_URL, ExportsResource, FeesResource, ForbiddenError, InvalidAmountError, JurisdictionBlockedError, KNOWN_EVENT_TYPES, LiveOrderBook, MAX_SERVER_WAIT_MS, MarketsResource, NetworksResource, NotFoundError, OPERATIONS, OrderStateUnknownError, PRIVATE_CHANNELS, PoolsResource, RateLimitError, RateLimiter, SUPPORTED_PROTOCOL_VERSION, ServerError, TradingResource, TypedEmitter, USER_AGENT, UnprocessableError, VERSION, ValidationError, WS_BOOK_DEPTH, WalletResource, assertAmountFields, errorFromResponse, isAmount, isKnownErrorCode, isLocalHost, isRetryable, paginate };
+// src/ledger.ts
+var KNOWN_LEDGER_REFERENCE_TYPES = /* @__PURE__ */ new Set([
+  "deposit",
+  "withdrawal",
+  "order",
+  "trade",
+  "transfer",
+  "adjustment",
+  "pool",
+  "futures_transfer",
+  "system"
+]);
+function isLedgerReference(ref, type) {
+  if (typeof ref !== "object" || ref === null || typeof ref.type !== "string") return false;
+  return type === void 0 ? KNOWN_LEDGER_REFERENCE_TYPES.has(ref.type) : ref.type === type;
+}
+
+export { AccountResource, ApiKeyAuthenticator, AssetsResource, AuthenticationError, CLIENT_ERROR_CODES, CancelAllInterruptedError, CexyApiError, CexyClient, CexyConfigError, CexyConnectionError, CexyError, CexyTimeoutError, CexyWebSocket, CexyWebSocketError, ConflictError, DEFAULT_BASE_URL, DEFAULT_RPM_ANONYMOUS, DEFAULT_RPM_WITH_KEY, DEFAULT_WS_URL, ExportsResource, FeesResource, ForbiddenError, InvalidAmountError, JurisdictionBlockedError, KNOWN_EVENT_TYPES, LiveOrderBook, MAX_SERVER_WAIT_MS, MarketsResource, NetworksResource, NotFoundError, OPERATIONS, OrderStateUnknownError, PRIVATE_CHANNELS, PoolsResource, RateLimitError, RateLimiter, SUPPORTED_PROTOCOL_VERSION, ServerError, TradingResource, TypedEmitter, USER_AGENT, UnprocessableError, VERSION, ValidationError, WS_BOOK_DEPTH, WalletResource, assertAmountFields, errorFromResponse, isAmount, isKnownErrorCode, isLedgerReference, isLocalHost, isRetryable, paginate };

package/package.json

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