@dshtrading/connector-ccxt 0.6.1 → 0.6.2

package/lib/rest.d.ts

@@ -1,11 +1,27 @@
-import { AccountBalance as AccountBalance$1, Interval as Interval$1, Kline as Kline$1, Order as Order$1, OrderRequest, Position as Position$1, Ticker as Ticker$1, TradingErrorCode } from "@dshtrading/api";
+import { Interval as Interval$1, Kline as Kline$1, Order as Order$1, OrderRequest, Position as Position$1, Ticker as Ticker$1, TradingErrorCode } from "@dshtrading/api";
 //#region src/rest.d.ts
 declare class TradingServiceError extends Error {
   readonly code: TradingErrorCode;
   constructor(code: TradingErrorCode, message: string, cause?: unknown);
 }
 declare const INTERVAL_VOCABULARY: readonly ["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w", "1M"];
+/**
+ * 登记的所名 = 本包真有 ticker 直连分支的所名（九条）。
+ *
+ * 此前这里登记 9 个所名、却只有 bybit/okx 两个具名分支，其余 6 个静默落 Binance 兜底 URL
+ * （选 kraken 拿到 Binance 的报价）。上一轮把登记面收窄到 3 所；本轮六条分支补齐，
+ * 登记面重新等于实现面。未登记所名仍在**任何 fetch 之前**结构化拒绝（见 notImplementedError）。
+ */
 declare const SUPPORTED_EXCHANGES: readonly ["binance", "okx", "bybit", "gateio", "kucoin", "kraken", "coinbase", "bitfinex", "htx"];
+/**
+ * K 线登记面（2026-10-15 起九条直连分支）。
+ *
+ * 上一轮曾把 K 线面撤成单分支（binance）并把「按所取 K 线」记为另一张卡；本卡就是那张卡：
+ * 九所各有自己的 K 线端点、周期词汇与行结构，周期映射表见 KLINE_INTERVAL_PARAMS。
+ * 未登记所名（如 bitstamp）仍在**任何 fetch 之前**结构化拒绝（零请求）。
+ */
+declare const KLINE_EXCHANGES: readonly ["binance", "okx", "bybit", "gateio", "kucoin", "kraken", "coinbase", "bitfinex", "htx"];
+type KlineExchange = (typeof KLINE_EXCHANGES)[number];
 /**
  * 现货符号归一化（本轮 CCXT 面只做现货）。
  *
@@ -14,6 +30,62 @@ declare const SUPPORTED_EXCHANGES: readonly ["binance", "okx", "bybit", "gateio"
  * 不得把 `-SWAP` 落到 spot 端点）。CCXT 的合约面不属本轮范围，要做得走单独的卡。
  */
 declare function normalizeSymbol(raw: string): string;
+/**
+ * 各所 quote 资产表（**按所维护**，2026-10-15 起）。
+ *
+ * 数据来源 = 该所公开挂牌端点的逐所普查（原始响应 `census-*.json` 与派生命题见
+ * `spikes/impl-ccxt-exchange-expansion/EVIDENCE-2026-10-15-quote-census-and-klines.md`）：
+ * - okx `GET /api/v5/public/instruments?instType=SPOT` → `quoteCcy`（剔除空串）
+ * - kucoin `GET /api/v2/symbols` → `quoteCurrency`
+ * - gateio `GET /api/v4/spot/currency_pairs` → `quote`
+ * - kraken `GET /0/public/AssetPairs` → `wsname` 的 quote 段（kraken 的 `quote` 字段是
+ *   Z/X 前缀的旧代号 ZEUR/XXBT，而请求符号用现代形 EUR/XBT）
+ * - coinbase `GET /products` → `quote_currency`
+ * - bitfinex `GET /v2/conf/pub:list:pair:exchange` + `.../pub:list:currency` → 最长货币后缀
+ *   （`UST` 归一成用户写法的 `USDT`；`:` 分隔的挂牌对按分隔符切开）
+ * - htx `GET /v2/settings/common/symbols` → `qcdn`（大写展示形）
+ *
+ * 表只登记上游确实挂牌的 quote：表外计价对在七条变换分支上仍是本地
+ * `TRADING_UNSUPPORTED_SYMBOL` 且零请求——「猜一个 quote」等于给上游发错符号，比本地拒绝更糟。
+ * 每条表都由 `spikes/impl-ccxt-exchange-expansion/run-probe.ts` 按同一条普查规则现场复核
+ * （表 = 普查结果），上游新增 quote 而表未跟进即探针失败。
+ */
+declare const QUOTE_TABLES: Readonly<Record<TransformExchange, readonly string[]>>;
+/**
+ * 裸符号 → `{ base, quote }`，按**该所**的 quote 表最长优先匹配。
+ *
+ * 只服务需要形态变换的七条分支（`requestSymbol`）；binance/bybit 把裸符号原样发上游，
+ * 不经过这里——上游存在 `ETHBNB`/`BTCFDUSD` 这类不在任何 quote 表里的计价对。
+ * base 为空（如 `USDT`）或后缀不在该所表内（如 gateio 的 `BTCJPY`、kraken 的 `BTCBRL`）
+ * → TRADING_UNSUPPORTED_SYMBOL，文案点名该所与该所的 quote 表：猜一个 quote 会变成给上游发错符号。
+ */
+declare function splitPair(symbol: string, exchange: TransformExchange): {
+  base: string;
+  quote: string;
+};
+/**
+ * 需要请求符号**形态变换**的七条分支。
+ *
+ * binance / bybit 不在此列：它们把 `normalizeSymbol` 的裸符号原样发上游，**永不调用
+ * `requestSymbol`/`splitPair`**——上游确实存在 `ETHBNB`/`BTCFDUSD` 这类不在 quote 表里的
+ * 计价对，本地替上游裁决会变成功能回归（上游的错误语义留给上游）。
+ */
+type TransformExchange = 'okx' | 'kucoin' | 'gateio' | 'kraken' | 'coinbase' | 'bitfinex' | 'htx';
+/**
+ * 各所现货端点的请求符号形态（入参 = `normalizeSymbol` 的裸符号，如 BTCUSDT）。
+ *
+ * okx/kucoin/coinbase 用 `-`、gateio 用 `_`、kraken 把 BTC 记作 XBT、bitfinex 加 `t`
+ * 前缀且 USDT 记作 UST、htx 全小写。导出让离线用例与探针能直接断言拼出来的符号形态
+ * （不必为了看一个 URL 去打网络）。
+ */
+declare function requestSymbol(exchange: TransformExchange, sym: string): string;
+/** 某所支持的周期（映射表键集；供离线用例与探针断言，不在运行时按上游探测）。 */
+declare function klineSupportedIntervals(exchange: KlineExchange): readonly Interval$1[];
+/**
+ * `Interval` → 该所周期参数；该所不支持（coinbase 的 30m/4h/1w/1M、gateio/kucoin 的 1M、
+ * 以及任何词汇表外取值）→ TRADING_UNSUPPORTED_INTERVAL，**在 fetch 之前**（零请求）。
+ */
+declare function klineIntervalParam(exchange: KlineExchange, interval: Interval$1): string;
 interface CcxtRestOptions {
   exchange?: string;
   apiKey?: string;
@@ -28,8 +100,17 @@ declare class CcxtRestClient {
   constructor(options?: CcxtRestOptions);
   private requestJson;
   getTicker(symbol: string, exchange?: string): Promise<Ticker$1>;
+  /**
+   * K 线九条直连分支（2026-10-15 起）：周期按所映射（KLINE_INTERVAL_PARAMS）、行结构按所解析，
+   * 输出一律**升序（旧→新）且只含最新 limit 根**。
+   *
+   * `exchange` 是**连接器自有形参**（缺省 = 客户端默认所名）：`@dshtrading/api` 的
+   * `MarketDataService.getKlines(symbol, interval, limit?)` 没有这个形参，服务缝保持与契约同形，
+   * 形参只在本客户端方法与 `crypto_get_klines` 工具上暴露（见包 README「周期与契约」）。
+   * 未登记所名 → TRADING_NOT_IMPLEMENTED、该所不支持的周期 → TRADING_UNSUPPORTED_INTERVAL，
+   * 两者都在 fetch 之前（零请求）。
+   */
   getKlines(symbol: string, interval?: Interval$1, limit?: number, exchange?: string): Promise<Kline$1[]>;
-  getBalance(): Promise<AccountBalance$1>;
   placeOrder(_creds: unknown, req: OrderRequest): Promise<Order$1>;
   cancelOrder(_creds: unknown, orderId: string): Promise<{
     orderId: string;
@@ -37,4 +118,4 @@ declare class CcxtRestClient {
   }>;
 }
 //#endregion
-export { type AccountBalance$1 as AccountBalance, CcxtRestClient, CcxtRestOptions, INTERVAL_VOCABULARY, type Interval$1 as Interval, type Kline$1 as Kline, type Order$1 as Order, type Position$1 as Position, SUPPORTED_EXCHANGES, type Ticker$1 as Ticker, TradingServiceError, normalizeSymbol };
+export { CcxtRestClient, CcxtRestOptions, INTERVAL_VOCABULARY, type Interval$1 as Interval, KLINE_EXCHANGES, type Kline$1 as Kline, KlineExchange, type Order$1 as Order, type Position$1 as Position, QUOTE_TABLES, SUPPORTED_EXCHANGES, type Ticker$1 as Ticker, TradingServiceError, klineIntervalParam, klineSupportedIntervals, normalizeSymbol, requestSymbol, splitPair };