@dshtrading/connector-ccxt 0.6.1 → 0.6.3

package/lib/rest.js

@@ -24,6 +24,13 @@ const INTERVAL_VOCABULARY = [
 	"1w",
 	"1M"
 ];
+/**
+* 登记的所名 = 本包真有 ticker 直连分支的所名（九条）。
+*
+* 此前这里登记 9 个所名、却只有 bybit/okx 两个具名分支，其余 6 个静默落 Binance 兜底 URL
+* （选 kraken 拿到 Binance 的报价）。上一轮把登记面收窄到 3 所；本轮六条分支补齐，
+* 登记面重新等于实现面。未登记所名仍在**任何 fetch 之前**结构化拒绝（见 notImplementedError）。
+*/
 const SUPPORTED_EXCHANGES = [
 	"binance",
 	"okx",
@@ -36,6 +43,45 @@ const SUPPORTED_EXCHANGES = [
 	"htx"
 ];
 /**
+* K 线登记面（2026-10-15 起九条直连分支）。
+*
+* 上一轮曾把 K 线面撤成单分支（binance）并把「按所取 K 线」记为另一张卡；本卡就是那张卡：
+* 九所各有自己的 K 线端点、周期词汇与行结构，周期映射表见 KLINE_INTERVAL_PARAMS。
+* 未登记所名（如 bitstamp）仍在**任何 fetch 之前**结构化拒绝（零请求）。
+*/
+const KLINE_EXCHANGES = [
+	"binance",
+	"okx",
+	"bybit",
+	"gateio",
+	"kucoin",
+	"kraken",
+	"coinbase",
+	"bitfinex",
+	"htx"
+];
+const IMPLEMENTED_EXCHANGES = {
+	ticker: SUPPORTED_EXCHANGES,
+	klines: KLINE_EXCHANGES
+};
+const UNIMPLEMENTED_HINT = {
+	ticker: "ticker has nine implemented direct branches (binance/okx/bybit/gateio/kucoin/kraken/coinbase/bitfinex/htx): use one of them, or the dedicated per-exchange packages @dshtrading/connector-binance / @dshtrading/connector-okx / @dshtrading/connector-bybit.",
+	klines: "klines have nine implemented direct branches (binance/okx/bybit/gateio/kucoin/kraken/coinbase/bitfinex/htx): use one of them, or the dedicated per-exchange packages @dshtrading/connector-binance / @dshtrading/connector-okx / @dshtrading/connector-bybit."
+};
+/** 未实现所名的统一拒绝构造：两处调用点共用，禁止各自复制文案。 */
+function notImplementedError(surface, exchange) {
+	return new TradingServiceError("TRADING_NOT_IMPLEMENTED", `CCXT connector has no ${surface} branch for exchange "${exchange}" (implemented: ${IMPLEMENTED_EXCHANGES[surface].join(", ")}); zero network requests were made. ${UNIMPLEMENTED_HINT[surface]}`);
+}
+/**
+* 行级判空的统一拒绝：上游答了、但没有这个标的的行（≠ 网络故障、≠ 上游故障）。
+*
+* 上游明确报「查不到」的三种形态都归到这里：ticker 的空行、K 线的错误信封，
+* 以及 requestJson 里的 HTTP 404 / 400 + `label=INVALID_*`。
+*/
+function symbolNotFoundError(surface, exchange, symbol) {
+	return new TradingServiceError("TRADING_SYMBOL_NOT_FOUND", `CCXT/${exchange} ${surface} not found: ${symbol} (the venue answered, but without a usable row for this pair)`);
+}
+/**
 * 现货符号归一化（本轮 CCXT 面只做现货）。
 *
 * 入参带规范永续后缀 `-SWAP` 时**显式报 TRADING_UNSUPPORTED_SYMBOL**：此前实现会先剥掉
@@ -49,6 +95,413 @@ function normalizeSymbol(raw) {
 	if (clean.includes("/")) return clean.replace("/", "");
 	return clean;
 }
+/**
+* 各所 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 而表未跟进即探针失败。
+*/
+const QUOTE_TABLES = {
+	okx: [
+		"AED",
+		"AUD",
+		"BRL",
+		"BTC",
+		"ETH",
+		"EUR",
+		"PLN",
+		"SGD",
+		"SOL",
+		"TRY",
+		"USD",
+		"USDC",
+		"USDT"
+	],
+	kucoin: [
+		"BTC",
+		"DOGE",
+		"ETH",
+		"EUR",
+		"KCS",
+		"TRX",
+		"USD1",
+		"USDC",
+		"USDG",
+		"USDT"
+	],
+	gateio: [
+		"BTC",
+		"ETH",
+		"GUSD",
+		"RLUSD",
+		"USD",
+		"USD1",
+		"USDC",
+		"USDT"
+	],
+	kraken: [
+		"AUD",
+		"AUSD",
+		"CAD",
+		"CHF",
+		"DAI",
+		"ETH",
+		"EUR",
+		"EURC",
+		"EUROP",
+		"FIDD",
+		"GBP",
+		"JPY",
+		"PYUSD",
+		"RLUSD",
+		"SOFID",
+		"SOL",
+		"USD",
+		"USD1",
+		"USDC",
+		"USDD",
+		"USDQ",
+		"USDR",
+		"USDT",
+		"XBT"
+	],
+	coinbase: [
+		"AUD",
+		"BRL",
+		"BTC",
+		"CAD",
+		"DAI",
+		"ETH",
+		"EUR",
+		"GBP",
+		"INR",
+		"SGD",
+		"USD",
+		"USDC",
+		"USDT"
+	],
+	bitfinex: [
+		"BTC",
+		"ETH",
+		"EUR",
+		"GBP",
+		"TESTUSD",
+		"TESTUSDT",
+		"USD",
+		"USDT",
+		"XAUT"
+	],
+	htx: [
+		"BRL",
+		"BTC",
+		"ETH",
+		"EUR",
+		"EUROC",
+		"GBP",
+		"HT",
+		"HUSD",
+		"KGST",
+		"PYUSD",
+		"RUB",
+		"TRX",
+		"TRY",
+		"TUSD",
+		"UAH",
+		"USD1",
+		"USDC",
+		"USDD",
+		"USDT",
+		"USTC"
+	]
+};
+/**
+* 裸符号 → `{ base, quote }`，按**该所**的 quote 表最长优先匹配。
+*
+* 只服务需要形态变换的七条分支（`requestSymbol`）；binance/bybit 把裸符号原样发上游，
+* 不经过这里——上游存在 `ETHBNB`/`BTCFDUSD` 这类不在任何 quote 表里的计价对。
+* base 为空（如 `USDT`）或后缀不在该所表内（如 gateio 的 `BTCJPY`、kraken 的 `BTCBRL`）
+* → TRADING_UNSUPPORTED_SYMBOL，文案点名该所与该所的 quote 表：猜一个 quote 会变成给上游发错符号。
+*/
+function splitPair(symbol, exchange) {
+	const clean = symbol.trim().toUpperCase();
+	const table = QUOTE_TABLES[exchange];
+	const quotes = [...table].sort((a, b) => b.length - a.length);
+	for (const quote of quotes) if (clean.length > quote.length && clean.endsWith(quote)) return {
+		base: clean.slice(0, clean.length - quote.length),
+		quote
+	};
+	throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `CCXT connector cannot split "${symbol}" into base+quote for ${exchange}: ${exchange} quotes are ${[...table].sort().join(", ")} (longest match first, base must be non-empty).`);
+}
+/**
+* 各所现货端点的请求符号形态（入参 = `normalizeSymbol` 的裸符号，如 BTCUSDT）。
+*
+* okx/kucoin/coinbase 用 `-`、gateio 用 `_`、kraken 把 BTC 记作 XBT、bitfinex 加 `t`
+* 前缀且 USDT 记作 UST、htx 全小写。导出让离线用例与探针能直接断言拼出来的符号形态
+* （不必为了看一个 URL 去打网络）。
+*/
+function requestSymbol(exchange, sym) {
+	const { base, quote } = splitPair(sym, exchange);
+	switch (exchange) {
+		case "okx":
+		case "kucoin":
+		case "coinbase": return `${base}-${quote}`;
+		case "gateio": return `${base}_${quote}`;
+		case "kraken": return `${base === "BTC" ? "XBT" : base}${quote}`;
+		case "bitfinex": return `t${base}${quote === "USDT" ? "UST" : quote}`;
+		case "htx": return `${base}${quote}`.toLowerCase();
+	}
+}
+/**
+* 上游字段读成数值：缺失、空串或非有限数一律 undefined（判空统一走 symbolNotFoundError）。
+* 各所报价字段有的是字符串（gateio/kucoin/coinbase/bithumb 系）有的是数字（bitfinex/htx 系）。
+*/
+function toNumber(value) {
+	if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+	if (typeof value === "string" && value.trim() !== "") {
+		const parsed = Number(value);
+		return Number.isFinite(parsed) ? parsed : void 0;
+	}
+}
+/**
+* 400 + JSON 正文里 `label` 以 `INVALID_` 开头 = 上游明确说「这个符号/币种不存在」，
+* 不是基础设施故障（gateio 实测 `{"label":"INVALID_CURRENCY_PAIR"}` / `INVALID_CURRENCY`）。
+* 正文不是 JSON 时一律返回 false（bybit 的 403 正文就是非 JSON 的拦截片段）。
+*/
+function invalidSymbolLabel(body) {
+	try {
+		const parsed = JSON.parse(body);
+		return typeof parsed?.label === "string" && parsed.label.startsWith("INVALID_");
+	} catch {
+		return false;
+	}
+}
+/** 上游正文的取证片段：压成单行、截断约 200 字符（进 message，不进日志正文）。 */
+function bodySnippet(body) {
+	return body.replace(/\s+/g, " ").trim().slice(0, 200);
+}
+/**
+* api `Interval` → 各所 K 线周期参数（缺键 = 该所不支持，抛 TRADING_UNSUPPORTED_INTERVAL 且零请求）。
+*
+* 逐所实测口径（原始响应见 `spikes/impl-ccxt-exchange-expansion/klines-*.json` 与同目录 EVIDENCE）：
+* - binance 原文直发；bybit `1/5/15/30/60/240/D/W/M`
+* - okx bar 取 **utc 变体**（`1Dutc`/`1Wutc`/`1Mutc`）：与 connector-okx 同一裁决，
+*   日界对齐 UTC（Binance 口径）；okx 的 `1D` 是 UTC+8 零点，跨连接器会错位 8 小时
+* - gateio 无 1M（实测 400 `invalid interval 1M`）；1w 用上游的 `7d`
+* - kucoin 无 1M（实测 400 `Incorrect candlestick type`）
+* - kraken 周期是**分钟数**（1w=10080、1M=21600）
+* - coinbase granularity 是**秒**，且实测只接受 60/300/900/3600/21600/86400：30m→1800 与
+*   4h→14400 都回 400 `Unsupported granularity`（1w/1M 同），故本词汇表内只支持 1m/5m/15m/1h/1d
+* - bitfinex `1m..1h` 小写、日线及以上大写（`1D`/`1W`/`1M`）；4h 实测上游接受
+* - htx `1min/5min/…/60min/4hour/1day/1mon/1week`
+*/
+const KLINE_INTERVAL_PARAMS = {
+	binance: {
+		"1m": "1m",
+		"5m": "5m",
+		"15m": "15m",
+		"30m": "30m",
+		"1h": "1h",
+		"4h": "4h",
+		"1d": "1d",
+		"1w": "1w",
+		"1M": "1M"
+	},
+	okx: {
+		"1m": "1m",
+		"5m": "5m",
+		"15m": "15m",
+		"30m": "30m",
+		"1h": "1H",
+		"4h": "4H",
+		"1d": "1Dutc",
+		"1w": "1Wutc",
+		"1M": "1Mutc"
+	},
+	bybit: {
+		"1m": "1",
+		"5m": "5",
+		"15m": "15",
+		"30m": "30",
+		"1h": "60",
+		"4h": "240",
+		"1d": "D",
+		"1w": "W",
+		"1M": "M"
+	},
+	gateio: {
+		"1m": "1m",
+		"5m": "5m",
+		"15m": "15m",
+		"30m": "30m",
+		"1h": "1h",
+		"4h": "4h",
+		"1d": "1d",
+		"1w": "7d"
+	},
+	kucoin: {
+		"1m": "1min",
+		"5m": "5min",
+		"15m": "15min",
+		"30m": "30min",
+		"1h": "1hour",
+		"4h": "4hour",
+		"1d": "1day",
+		"1w": "1week"
+	},
+	kraken: {
+		"1m": "1",
+		"5m": "5",
+		"15m": "15",
+		"30m": "30",
+		"1h": "60",
+		"4h": "240",
+		"1d": "1440",
+		"1w": "10080",
+		"1M": "21600"
+	},
+	coinbase: {
+		"1m": "60",
+		"5m": "300",
+		"15m": "900",
+		"1h": "3600",
+		"1d": "86400"
+	},
+	bitfinex: {
+		"1m": "1m",
+		"5m": "5m",
+		"15m": "15m",
+		"30m": "30m",
+		"1h": "1h",
+		"4h": "4h",
+		"1d": "1D",
+		"1w": "1W",
+		"1M": "1M"
+	},
+	htx: {
+		"1m": "1min",
+		"5m": "5min",
+		"15m": "15min",
+		"30m": "30min",
+		"1h": "60min",
+		"4h": "4hour",
+		"1d": "1day",
+		"1w": "1week",
+		"1M": "1mon"
+	}
+};
+/** 周期毫秒时长（closeTime 补算用；1M 以 30 天近似，与 connector-okx 同口径）。 */
+const INTERVAL_MS = {
+	"1m": 6e4,
+	"3m": 18e4,
+	"5m": 3e5,
+	"15m": 9e5,
+	"30m": 18e5,
+	"1h": 36e5,
+	"2h": 72e5,
+	"4h": 144e5,
+	"6h": 216e5,
+	"8h": 288e5,
+	"12h": 432e5,
+	"1d": 864e5,
+	"3d": 2592e5,
+	"1w": 6048e5,
+	"1M": 2592e6
+};
+/** 某所支持的周期（映射表键集；供离线用例与探针断言，不在运行时按上游探测）。 */
+function klineSupportedIntervals(exchange) {
+	return Object.keys(KLINE_INTERVAL_PARAMS[exchange]);
+}
+/**
+* `Interval` → 该所周期参数；该所不支持（coinbase 的 30m/4h/1w/1M、gateio/kucoin 的 1M、
+* 以及任何词汇表外取值）→ TRADING_UNSUPPORTED_INTERVAL，**在 fetch 之前**（零请求）。
+*/
+function klineIntervalParam(exchange, interval) {
+	const param = KLINE_INTERVAL_PARAMS[exchange][interval];
+	if (param === void 0) throw new TradingServiceError("TRADING_UNSUPPORTED_INTERVAL", `CCXT/${exchange} klines: unsupported interval ${String(interval)} — ${exchange} supports ${klineSupportedIntervals(exchange).join("/")}; no network request was made.`);
+	return param;
+}
+/** 单根 K 线的形状判空：任一分量非有限数即整根丢弃（丢行，不猜值）。 */
+function klineRow(openTime, open, high, low, close, volume, closeTime) {
+	const o = toNumber(open);
+	const h = toNumber(high);
+	const l = toNumber(low);
+	const c = toNumber(close);
+	const v = toNumber(volume);
+	if (!Number.isFinite(openTime) || !Number.isFinite(closeTime)) return void 0;
+	if (o === void 0 || h === void 0 || l === void 0 || c === void 0 || v === void 0) return void 0;
+	return {
+		openTime,
+		open: o,
+		high: h,
+		low: l,
+		close: c,
+		volume: v,
+		closeTime
+	};
+}
+/**
+* 行集归一：按 openTime 去重、**升序（旧→新）**排序、只保留最新 limit 根。
+*
+* 九所里只有 binance 与 kraken 的上游序列本来就是升序；okx/kucoin/gateio/coinbase/bitfinex/htx/bybit
+* 都是新→旧。统一在这里归一，消费方拿到的序列与 connector-binance 同向。
+*/
+function finalizeKlines(rows, limit) {
+	const byOpenTime = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		if (row === void 0) continue;
+		byOpenTime.set(row.openTime, row);
+	}
+	const sorted = [...byOpenTime.values()].sort((a, b) => a.openTime - b.openTime);
+	return limit > 0 ? sorted.slice(-limit) : sorted;
+}
+/**
+* 各所单请求的根数参数与上限（超出上限只请求上限内的根数，**不翻页**）。
+* kucoin / kraken / coinbase 的上游没有根数参数（kucoin 固定回 1500、kraken 720、coinbase 300），
+* 一律留空并在 finalizeKlines 里切成 limit 根。
+*/
+const KLINE_LIMIT_PARAMS = {
+	binance: {
+		query: "limit",
+		max: 1e3
+	},
+	okx: {
+		query: "limit",
+		max: 300
+	},
+	bybit: {
+		query: "limit",
+		max: 1e3
+	},
+	gateio: {
+		query: "limit",
+		max: 1e3
+	},
+	kucoin: void 0,
+	kraken: void 0,
+	coinbase: void 0,
+	bitfinex: {
+		query: "limit",
+		max: 1e4
+	},
+	htx: {
+		query: "size",
+		max: 2e3
+	}
+};
 var CcxtRestClient = class {
 	exchange;
 	apiKey;
@@ -63,7 +516,13 @@ var CcxtRestClient = class {
 	async requestJson(url) {
 		try {
 			const res = await this.fetchImpl(url, { headers: { "Accept": "application/json" } });
-			if (!res.ok) throw new TradingServiceError("TRADING_UPSTREAM_ERROR", `CCXT HTTP ${res.status}: ${res.statusText}`);
+			if (!res.ok) {
+				const body = await res.text().catch(() => "");
+				const snippet = bodySnippet(body);
+				if (res.status === 404) throw new TradingServiceError("TRADING_SYMBOL_NOT_FOUND", `CCXT HTTP 404 ${res.statusText}: ${snippet} (${url})`);
+				if (res.status === 400 && invalidSymbolLabel(body)) throw new TradingServiceError("TRADING_SYMBOL_NOT_FOUND", `CCXT HTTP 400 ${res.statusText}: ${snippet}`);
+				throw new TradingServiceError("TRADING_UPSTREAM_ERROR", `CCXT HTTP ${res.status} ${res.statusText}: ${snippet}`);
+			}
 			return await res.json();
 		} catch (err) {
 			if (err instanceof TradingServiceError) throw err;
@@ -72,10 +531,11 @@ var CcxtRestClient = class {
 	}
 	async getTicker(symbol, exchange = this.exchange) {
 		const sym = normalizeSymbol(symbol);
+		if (!SUPPORTED_EXCHANGES.includes(exchange)) throw notImplementedError("ticker", exchange);
 		if (exchange === "bybit") {
 			const url = `https://api.bybit.com/v5/market/tickers?category=spot&symbol=${sym}`;
 			const row = (await this.requestJson(url)).result?.list?.[0];
-			if (!row) throw new TradingServiceError("TRADING_SYMBOL_NOT_FOUND", `CCXT/Bybit ticker not found: ${symbol}`);
+			if (!row) throw symbolNotFoundError("ticker", "bybit", symbol);
 			return {
 				symbol: sym,
 				price: parseFloat(row.lastPrice),
@@ -84,9 +544,9 @@ var CcxtRestClient = class {
 			};
 		}
 		if (exchange === "okx") {
-			const url = `https://www.okx.com/api/v5/market/ticker?instId=${symbol.includes("-") ? symbol : `${sym.replace("USDT", "")}-USDT`}`;
+			const url = `https://www.okx.com/api/v5/market/ticker?instId=${requestSymbol("okx", sym)}`;
 			const row = (await this.requestJson(url)).data?.[0];
-			if (!row) throw new TradingServiceError("TRADING_SYMBOL_NOT_FOUND", `CCXT/OKX ticker not found: ${symbol}`);
+			if (!row) throw symbolNotFoundError("ticker", "okx", symbol);
 			return {
 				symbol: sym,
 				price: parseFloat(row.last),
@@ -94,6 +554,88 @@ var CcxtRestClient = class {
 				timestamp: parseInt(row.ts, 10)
 			};
 		}
+		if (exchange === "gateio") {
+			const url = `https://api.gateio.ws/api/v4/spot/tickers?currency_pair=${requestSymbol("gateio", sym)}`;
+			const res = await this.requestJson(url);
+			const row = Array.isArray(res) ? res[0] : void 0;
+			const price = toNumber(row?.last);
+			const volume = toNumber(row?.base_volume);
+			if (price === void 0 || volume === void 0) throw symbolNotFoundError("ticker", "gateio", symbol);
+			return {
+				symbol: sym,
+				price,
+				volume,
+				timestamp: Date.now()
+			};
+		}
+		if (exchange === "kucoin") {
+			const url = `https://api.kucoin.com/api/v1/market/stats?symbol=${requestSymbol("kucoin", sym)}`;
+			const res = await this.requestJson(url);
+			const price = toNumber(res.data?.last);
+			const volume = toNumber(res.data?.vol);
+			if (res.code !== "200000" || price === void 0 || volume === void 0) throw symbolNotFoundError("ticker", "kucoin", symbol);
+			return {
+				symbol: sym,
+				price,
+				volume,
+				timestamp: typeof res.data?.time === "number" && Number.isFinite(res.data.time) ? res.data.time : Date.now()
+			};
+		}
+		if (exchange === "kraken") {
+			const url = `https://api.kraken.com/0/public/Ticker?pair=${requestSymbol("kraken", sym)}`;
+			const res = await this.requestJson(url);
+			const key = Object.keys(res.result ?? {})[0];
+			const row = key === void 0 ? void 0 : res.result?.[key];
+			const price = toNumber(row?.c?.[0]);
+			const volume = toNumber(row?.v?.[1]);
+			if ((res.error?.length ?? 0) > 0 || price === void 0 || volume === void 0) throw symbolNotFoundError("ticker", "kraken", symbol);
+			return {
+				symbol: sym,
+				price,
+				volume,
+				timestamp: Date.now()
+			};
+		}
+		if (exchange === "coinbase") {
+			const url = `https://api.exchange.coinbase.com/products/${requestSymbol("coinbase", sym)}/ticker`;
+			const res = await this.requestJson(url);
+			const price = toNumber(res.price);
+			const volume = toNumber(res.volume);
+			if (price === void 0 || volume === void 0) throw symbolNotFoundError("ticker", "coinbase", symbol);
+			return {
+				symbol: sym,
+				price,
+				volume,
+				timestamp: Date.now()
+			};
+		}
+		if (exchange === "bitfinex") {
+			const url = `https://api-pub.bitfinex.com/v2/ticker/${requestSymbol("bitfinex", sym)}`;
+			const res = await this.requestJson(url);
+			if (!Array.isArray(res) || res.length === 0) throw symbolNotFoundError("ticker", "bitfinex", symbol);
+			const price = toNumber(res[6]);
+			const volume = toNumber(res[7]);
+			if (price === void 0 || volume === void 0) throw symbolNotFoundError("ticker", "bitfinex", symbol);
+			return {
+				symbol: sym,
+				price,
+				volume,
+				timestamp: Date.now()
+			};
+		}
+		if (exchange === "htx") {
+			const url = `https://api.htx.com/market/detail/merged?symbol=${requestSymbol("htx", sym)}`;
+			const res = await this.requestJson(url);
+			const price = toNumber(res.tick?.close);
+			const volume = toNumber(res.tick?.amount);
+			if (res.status !== "ok" || price === void 0 || volume === void 0) throw symbolNotFoundError("ticker", "htx", symbol);
+			return {
+				symbol: sym,
+				price,
+				volume,
+				timestamp: typeof res.ts === "number" && Number.isFinite(res.ts) ? res.ts : Date.now()
+			};
+		}
 		const url = `https://api.binance.com/api/v3/ticker/24hr?symbol=${sym}`;
 		const data = await this.requestJson(url);
 		return {
@@ -103,26 +645,127 @@ var CcxtRestClient = class {
 			timestamp: data.closeTime
 		};
 	}
+	/**
+	* 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 之前（零请求）。
+	*/
 	async getKlines(symbol, interval = "1d", limit = 100, exchange = this.exchange) {
-		const url = `https://api.binance.com/api/v3/klines?symbol=${normalizeSymbol(symbol)}&interval=${interval}&limit=${limit}`;
-		const data = await this.requestJson(url);
-		if (!Array.isArray(data)) return [];
-		return data.map((r) => ({
-			openTime: r[0],
-			open: parseFloat(r[1]),
-			high: parseFloat(r[2]),
-			low: parseFloat(r[3]),
-			close: parseFloat(r[4]),
-			volume: parseFloat(r[5]),
-			closeTime: r[6]
-		}));
-	}
-	async getBalance() {
-		return {
-			currency: "USDT",
-			available: 1e5,
-			total: 1e5
-		};
+		const sym = normalizeSymbol(symbol);
+		if (!KLINE_EXCHANGES.includes(exchange)) throw notImplementedError("klines", exchange);
+		const venue = exchange;
+		const period = klineIntervalParam(venue, interval);
+		const stepMs = INTERVAL_MS[interval];
+		const cap = KLINE_LIMIT_PARAMS[venue];
+		const cappedLimit = cap === void 0 ? void 0 : Math.min(Math.max(limit, 1), cap.max);
+		const limitQuery = cap === void 0 || cappedLimit === void 0 ? "" : `&${cap.query}=${cappedLimit}`;
+		const limitQueryStart = cap === void 0 || cappedLimit === void 0 ? "" : `?${cap.query}=${cappedLimit}`;
+		switch (venue) {
+			case "binance": {
+				const url = `https://api.binance.com/api/v3/klines?symbol=${sym}&interval=${period}${limitQuery}`;
+				const data = await this.requestJson(url);
+				if (!Array.isArray(data)) return [];
+				return finalizeKlines(data.map((raw) => {
+					if (!Array.isArray(raw)) return void 0;
+					const [openTime, open, high, low, close, volume, closeTime] = raw;
+					return klineRow(Number(openTime), open, high, low, close, volume, Number(closeTime));
+				}), limit);
+			}
+			case "bybit": {
+				const url = `https://api.bybit.com/v5/market/kline?category=spot&symbol=${sym}&interval=${period}&limit=${cappedLimit ?? 200}`;
+				const data = await this.requestJson(url);
+				if (data.retCode !== 0) throw symbolNotFoundError("klines", "bybit", symbol);
+				return finalizeKlines((Array.isArray(data.result?.list) ? data.result.list : []).map((raw) => {
+					if (!Array.isArray(raw)) return void 0;
+					const [openTime, open, high, low, close, volume] = raw;
+					const t = Number(openTime);
+					return klineRow(t, open, high, low, close, volume, t + stepMs - 1);
+				}), limit);
+			}
+			case "okx": {
+				const url = `https://www.okx.com/api/v5/market/candles?instId=${requestSymbol("okx", sym)}&bar=${period}${limitQuery}`;
+				const data = await this.requestJson(url);
+				if (data.code !== "0") throw symbolNotFoundError("klines", "okx", symbol);
+				return finalizeKlines((Array.isArray(data.data) ? data.data : []).map((raw) => {
+					if (!Array.isArray(raw)) return void 0;
+					const [ts, open, high, low, close, volume] = raw;
+					const t = Number(ts);
+					return klineRow(t, open, high, low, close, volume, t + stepMs - 1);
+				}), limit);
+			}
+			case "gateio": {
+				const url = `https://api.gateio.ws/api/v4/spot/candlesticks?currency_pair=${requestSymbol("gateio", sym)}&interval=${period}${limitQuery}`;
+				const data = await this.requestJson(url);
+				if (!Array.isArray(data)) return [];
+				return finalizeKlines(data.map((raw) => {
+					if (!Array.isArray(raw)) return void 0;
+					const [ts, , close, high, low, open, baseVolume] = raw;
+					const t = Number(ts) * 1e3;
+					return klineRow(t, open, high, low, close, baseVolume, t + stepMs - 1);
+				}), limit);
+			}
+			case "kucoin": {
+				const url = `https://api.kucoin.com/api/v1/market/candles?symbol=${requestSymbol("kucoin", sym)}&type=${period}`;
+				const data = await this.requestJson(url);
+				if (data.code !== "200000") throw symbolNotFoundError("klines", "kucoin", symbol);
+				return finalizeKlines((Array.isArray(data.data) ? data.data : []).map((raw) => {
+					if (!Array.isArray(raw)) return void 0;
+					const [ts, open, close, high, low, volume] = raw;
+					const t = Number(ts) * 1e3;
+					return klineRow(t, open, high, low, close, volume, t + stepMs - 1);
+				}), limit);
+			}
+			case "kraken": {
+				const url = `https://api.kraken.com/0/public/OHLC?pair=${requestSymbol("kraken", sym)}&interval=${period}`;
+				const data = await this.requestJson(url);
+				if ((data.error?.length ?? 0) > 0) throw symbolNotFoundError("klines", "kraken", symbol);
+				const rows = Object.values(data.result ?? {}).find((value) => Array.isArray(value));
+				if (!Array.isArray(rows)) return [];
+				return finalizeKlines(rows.map((raw) => {
+					if (!Array.isArray(raw)) return void 0;
+					const [ts, open, high, low, close, , volume] = raw;
+					const t = Number(ts) * 1e3;
+					return klineRow(t, open, high, low, close, volume, t + stepMs - 1);
+				}), limit);
+			}
+			case "coinbase": {
+				const url = `https://api.exchange.coinbase.com/products/${requestSymbol("coinbase", sym)}/candles?granularity=${period}`;
+				const data = await this.requestJson(url);
+				if (!Array.isArray(data)) return [];
+				return finalizeKlines(data.map((raw) => {
+					if (!Array.isArray(raw)) return void 0;
+					const [ts, low, high, open, close, volume] = raw;
+					const t = Number(ts) * 1e3;
+					return klineRow(t, open, high, low, close, volume, t + stepMs - 1);
+				}), limit);
+			}
+			case "bitfinex": {
+				const url = `https://api-pub.bitfinex.com/v2/candles/trade:${period}:${requestSymbol("bitfinex", sym)}/hist${limitQueryStart}`;
+				const data = await this.requestJson(url);
+				if (!Array.isArray(data)) return [];
+				return finalizeKlines(data.map((raw) => {
+					if (!Array.isArray(raw)) return void 0;
+					const [mts, open, close, high, low, volume] = raw;
+					const t = Number(mts);
+					return klineRow(t, open, high, low, close, volume, t + stepMs - 1);
+				}), limit);
+			}
+			case "htx": {
+				const url = `https://api.htx.com/market/history/kline?symbol=${requestSymbol("htx", sym)}&period=${period}${limitQuery}`;
+				const data = await this.requestJson(url);
+				if (data.status !== "ok") throw symbolNotFoundError("klines", "htx", symbol);
+				return finalizeKlines((Array.isArray(data.data) ? data.data : []).map((raw) => {
+					const row = raw;
+					const t = Number(row.id) * 1e3;
+					return klineRow(t, row.open, row.high, row.low, row.close, row.amount, t + stepMs - 1);
+				}), limit);
+			}
+		}
 	}
 	async placeOrder(_creds, req) {
 		const sym = normalizeSymbol(req.symbol);
@@ -146,4 +789,4 @@ var CcxtRestClient = class {
 	}
 };
 //#endregion
-export { CcxtRestClient, INTERVAL_VOCABULARY, SUPPORTED_EXCHANGES, TradingServiceError, normalizeSymbol };
+export { CcxtRestClient, INTERVAL_VOCABULARY, KLINE_EXCHANGES, QUOTE_TABLES, SUPPORTED_EXCHANGES, TradingServiceError, klineIntervalParam, klineSupportedIntervals, normalizeSymbol, requestSymbol, splitPair };