@dshtrading/connector-binance 0.4.1 → 0.6.0

package/lib/index.d.ts

@@ -1,7 +1,7 @@
-import { BinanceRestClient, BinanceRestOptions, INTERVAL_VOCABULARY, TradingServiceError, normalizeBinanceFuturesSymbol } from "./rest.js";
+import { BinanceRestClient, BinanceRestOptions, INTERVAL_VOCABULARY, TradingServiceError, binanceAssetClassOf, binanceContractOf, normalizeBinanceFuturesSymbol, resolveBinanceInstrument } from "./rest.js";
 import { Context, Service } from "@deepseek-ai/cordis";
 import Schema from "@deepseek-ai/schemastery";
-import { DerivativesData, DerivativesHistory, Disposable, Interval, Kline, MarketDataService, Orderbook, Ticker, TradeTick } from "@dshtrading/api";
+import { DerivativesData, DerivativesHistory, Disposable, InstrumentRef, Interval, Kline, MarketDataService, Orderbook, Ticker, TradeTick } from "@dshtrading/api";
 //#region src/index.d.ts
 /**
  * Cordis 插件名 = patch 行 id（TEMPLATES §8）：`dsh-trading-crypto-*` 市场命名空间，
@@ -13,7 +13,7 @@ interface Config {
   enabled: boolean;
   /** 交易安全闸门（铁律 #3）：true 时下单类工具强制 dry-run。 */
   dryRun: boolean;
-  /** 实盘总闸门：默认 false；false 时无论 dryRun 与否都拒绝实盘下单 [S4]。 */
+  /** 实盘镜像：默认 false。它是非权威镜像——只能收紧、永不能授予；实盘授权由 @dshtrading/authority 的人工签署平面裁定 [S4]。 */
   liveTrading: boolean;
 }
 declare const Config: Schema<Config>;
@@ -30,10 +30,7 @@ declare class BinanceMarketDataService extends Service implements MarketDataServ
   constructor(ctx: Context, options?: BinanceRestOptions, name?: string);
   getTicker(symbol: string): Promise<Ticker>;
   getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
-  listInstruments(): Promise<Array<{
-    symbol: string;
-    name?: string;
-  }>>;
+  listInstruments(): Promise<InstrumentRef[]>;
   subscribeTicker(symbol: string, cb: (ticker: Ticker) => void, options?: SubscribeTickerOptions): Disposable;
   /**
    * 盘口快照（api 可选契约 getOrderbook，issue #39）：现货 depth 20 档透传，
@@ -73,15 +70,15 @@ interface PlaceOrderArgs {
 }
 /**
  * 闸门判定结果（三条路径，顺序即铁律 #3 修订版的裁决顺序）：
- *  - `reject`  —— ① 请求实盘（dryRun!==true）而 liveTrading=false：工具返回结构化
+ *  - `reject`  —— ① 请求实盘（dryRun!==true）而未获实盘授权：工具返回结构化
  *                拒绝（不抛异常，模型可读到明确原因与出路）；
  *  - `simulate` —— ② dryRun=true（显式、缺省，或被插件 config.dryRun 强制）：
  *                返回 DRY-RUN 模拟成交回执；
- *  - `live`    —— ③ dryRun=false 且 liveTrading=true：本切片无签名下单能力，
+ *  - `live`    —— ③ dryRun=false 且实盘已获授权：本切片无签名下单能力，
  *                工具抛 TRADING_NOT_IMPLEMENTED 结构化错误。
  *
  * 优先级说明：config.dryRun=true 是「强制模拟」开关，只影响 ②/③ 的归类；
- * 显式 dryRun=false 的实盘意图在 liveTrading=false 时仍走 ① 明确拒绝，
+ * 显式 dryRun=false 的实盘意图在 未获实盘授权时仍走 ① 明确拒绝，
  * 不做静默降级（拒绝语义优先于强制模拟，调用方必须知道实盘意图被拒）。
  */
 type OrderGateVerdict = {
@@ -107,7 +104,7 @@ declare function buildDryRunReceipt(args: PlaceOrderArgs, marketData: Pick<Marke
 interface PlaceOrderToolDeps {
   /** 行情服务（ dry-run 回执的市价参照），按接口取用，不直连 REST。 */
   readonly marketData: Pick<MarketDataService, 'getTicker'>;
-  /** 插件配置（dryRun 强制模拟 / liveTrading 总闸门）。 */
+  /** 插件配置（dryRun 强制模拟 / liveTrading 非权威镜像——实盘授权由 @dshtrading/authority 的人工签署平面裁定）。 */
   readonly config: Config;
 }
 /**
@@ -132,4 +129,4 @@ interface MarketRouterLike {
 declare function routeAllows(ctx: Context, config: Config, market: string): boolean;
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { BinanceMarketDataService, BinanceRestClient, BinanceRestOptions, Config, DryRunReference, INTERVAL_VOCABULARY, MarketRouterLike, OrderGateVerdict, PlaceOrderArgs, PlaceOrderToolDeps, ROUTER_PROVIDER, SubscribeTickerOptions, TRADING_CRYPTO_MARKET_DATA_KEY, TradingServiceError, apply, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, name, normalizeBinanceFuturesSymbol, routeAllows };
+export { BinanceMarketDataService, BinanceRestClient, BinanceRestOptions, Config, DryRunReference, INTERVAL_VOCABULARY, MarketRouterLike, OrderGateVerdict, PlaceOrderArgs, PlaceOrderToolDeps, ROUTER_PROVIDER, SubscribeTickerOptions, TRADING_CRYPTO_MARKET_DATA_KEY, TradingServiceError, apply, binanceAssetClassOf, binanceContractOf, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, name, normalizeBinanceFuturesSymbol, resolveBinanceInstrument, routeAllows };

package/lib/index.js

@@ -1,10 +1,25 @@
-import { BinanceRestClient, INTERVAL_VOCABULARY, TradingServiceError, normalizeBinanceFuturesSymbol } from "./rest.js";
+import { BinanceRestClient, INTERVAL_VOCABULARY, TradingServiceError, binanceAssetClassOf, binanceContractOf, normalizeBinanceFuturesSymbol, resolveBinanceInstrument } from "./rest.js";
+import { liveTradingEnabled } from "@dshtrading/authority";
 import { Service } from "@deepseek-ai/cordis";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import Schema from "@deepseek-ai/schemastery";
 import { createGetIndicatorsTool } from "@dshtrading/indicators/tool";
+import { instrumentFormOf } from "@dshtrading/api";
 //#region src/index.ts
 /**
+* Binance 连接器插件（dsh-trading crypto 切片）：真实 MarketDataService。
+*
+* 能力三角色：
+* - 声明：ctx 键 `tradingCryptoMarketData` 由 @dshtrading/api 的模块增强统一声明；
+* - provide：BinanceMarketDataService（Service 基类，随插件 fiber 自动注销）；
+* - inject：工具经 ctx.inject 等待服务就绪后注册，一律经服务执行，不直连 REST。
+*
+* REST 数据面见 ./rest.ts（可独立单测/脚本消费）；错误词汇映射 @dshtrading/api
+* 的 TradingErrorCode（TradingServiceError.code）。
+*
+* @module @dshtrading/connector-binance
+*/
+/**
 * 互斥激活的注册面（与 connector-okx 的 registerTool 同款，2026-08-31 补齐）：
 * dsh-tools 对同名重复注册直接抛错，互斥纪律下冲突降级为「先到先得 + warn」。
 * 没有这层时，inject 回调就绪顺序不定会让同名工具（含 crypto_get_indicators）
@@ -135,18 +150,19 @@ var BinanceMarketDataService = class extends Service {
 };
 function evaluateOrderGate(config, args) {
 	const requestedDryRun = args.dryRun ?? true;
-	if (!requestedDryRun && !config.liveTrading) return {
+	if (!requestedDryRun && !liveTradingEnabled(config.liveTrading)) return {
 		action: "reject",
 		code: "TRADING_LIVE_TRADING_DISABLED",
-		message: `crypto_place_order rejected: the call requests real execution (dryRun=${String(args.dryRun)}) but live trading is disabled (liveTrading=false). Ask the user to enable liveTrading explicitly after confirmation, or keep dryRun=true for a simulated fill.`
+		message: `crypto_place_order rejected: the call requests real execution (dryRun=${String(args.dryRun)}) but live trading is disabled (no signed live-trading grant from the authority plane). Ask the operator to sign a live-trading grant (packages/authority/bin/sign-live-trading.mjs) after confirmation, or keep dryRun=true for a simulated fill.`
 	};
 	if (requestedDryRun || config.dryRun) return { action: "simulate" };
 	return { action: "live" };
 }
 /** Binance 现货符号形如 BTCUSDT / ETHUSDT：大写字母数字（kit 同款词汇）。 */
 const SPOT_SYMBOL_PATTERN = /^[A-Z0-9]{4,20}$/;
-/** 参数校验（模型调用问题抛普通 Error，与 kit 先例一致；服务故障才用错误词汇）。 */
+/** 参数校验（模型调用错误词汇：合约输入必须显式拒绝，不能落到现货端点）。 */
 function validatePlaceOrderArgs(args) {
+	if (instrumentFormOf(args.symbol) === "perp") throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `crypto_place_order: ${args.symbol} is a perpetual — Binance contract order placement is not implemented in this connector (market data only); use a spot symbol here or route crypto trades to the OKX connector. This path never falls back to the spot endpoint.`);
 	if (!SPOT_SYMBOL_PATTERN.test(args.symbol)) throw new Error(`crypto_place_order: invalid symbol ${JSON.stringify(args.symbol)} — expected an uppercase Binance symbol like BTCUSDT`);
 	if (args.side !== "BUY" && args.side !== "SELL") throw new Error(`crypto_place_order: invalid side ${JSON.stringify(args.side)} — expected BUY or SELL`);
 	if (args.type !== "MARKET" && args.type !== "LIMIT") throw new Error(`crypto_place_order: invalid type ${JSON.stringify(args.type)} — expected MARKET or LIMIT`);
@@ -202,7 +218,7 @@ async function buildDryRunReceipt(args, marketData) {
 function createPlaceOrderTool(deps) {
 	return defineTool({
 		name: "crypto_place_order",
-		description: "Place a Binance spot order, or simulate one. dryRun defaults to true and returns a DRY-RUN simulated fill receipt with the current market price as reference. Real execution (dryRun=false) requires the plugin liveTrading switch to be enabled plus user approval, and is not implemented yet in this slice.",
+		description: "Place a Binance SPOT order, or simulate one. dryRun defaults to true and returns a DRY-RUN simulated fill receipt with the current market price as reference. Real execution (dryRun=false) requires a signed live-trading grant plus user approval, and is not implemented yet in this slice. Perpetual (-SWAP) symbols are rejected with TRADING_UNSUPPORTED_SYMBOL — Binance contract order placement is not implemented; only contract market data is available.",
 		parameters: {
 			symbol: {
 				type: "string",
@@ -232,7 +248,7 @@ function createPlaceOrderTool(deps) {
 			},
 			dryRun: {
 				type: "boolean",
-				description: "true (default) = simulate only and return a DRY-RUN receipt; false = request real execution (gated by liveTrading and user approval)",
+				description: "true (default) = simulate only and return a DRY-RUN receipt; false = request real execution (gated by the signed live-trading authority and user approval)",
 				default: true
 			}
 		},
@@ -356,4 +372,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { BinanceMarketDataService, BinanceRestClient, Config, INTERVAL_VOCABULARY, ROUTER_PROVIDER, TRADING_CRYPTO_MARKET_DATA_KEY, TradingServiceError, apply, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, name, normalizeBinanceFuturesSymbol, routeAllows };
+export { BinanceMarketDataService, BinanceRestClient, Config, INTERVAL_VOCABULARY, ROUTER_PROVIDER, TRADING_CRYPTO_MARKET_DATA_KEY, TradingServiceError, apply, binanceAssetClassOf, binanceContractOf, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, name, normalizeBinanceFuturesSymbol, resolveBinanceInstrument, routeAllows };

package/lib/rest.d.ts

@@ -1,4 +1,4 @@
-import { DerivativesPoint, Interval, Kline, Orderbook, Ticker, TradeTick, TradingErrorCode } from "@dshtrading/api";
+import { DerivativesPoint, InstrumentAssetClass, InstrumentContract, InstrumentForm, InstrumentRef, Interval, Kline, Orderbook, Ticker, TradeTick, TradingErrorCode } from "@dshtrading/api";
 //#region src/rest.d.ts
 /** api 包 TradingError 契约的运行时 Error 实现。 */
 declare class TradingServiceError extends Error {
@@ -22,25 +22,59 @@ declare const INTERVAL_VOCABULARY: readonly string[];
  * OKX 原生 SWAP 形一律归一到 fapi 词汇——BTCUSDT / BTCUSDT-SWAP / BTC-USDT-SWAP → BTCUSDT。
  */
 declare function normalizeBinanceFuturesSymbol(raw: string): string;
+/**
+ * 输入符号 → 形态 + 交易所词汇（2026-10-08 加密永续落地）。
+ *
+ * Binance 现货与永续在交易所侧**同形**（都叫 `BTCUSDT`），形态只能由规范后缀
+ * `-SWAP` 裁决——单一实现是 @dshtrading/api 的 `instrumentFormOf`，这里不另写
+ * 一份 endsWith。永续剥掉后缀后复用既有衍生品归一（同时容忍 OKX 原生形
+ * `BTC-USDT-SWAP`）；现货保持原样交给交易所判存在性（未知符号仍报 -1121）。
+ */
+declare function resolveBinanceInstrument(symbol: string): {
+  form: InstrumentForm;
+  venueSymbol: string;
+};
+/** underlyingType（含 underlyingSubType 逐项兜底）→ 资产类别；未登记/缺失 = undefined。 */
+declare function binanceAssetClassOf(underlyingType: unknown, underlyingSubType: unknown): InstrumentAssetClass | undefined;
+/** USDT-M 合约规格 → InstrumentContract（交易所元数据原样透传；字段缺失即缺省）。 */
+declare function binanceContractOf(row: {
+  readonly contractSize?: unknown;
+  readonly marginAsset?: unknown;
+  readonly filters?: unknown;
+}): InstrumentContract | undefined;
 declare class BinanceRestClient {
   #private;
   constructor(options?: BinanceRestOptions);
   /**
-   * 最新行情：/api/v3/ticker/24hr 提供最新价与 24h 量，/api/v3/ticker/bookTicker 补充 bid/ask。
+   * 最新行情（2026-10-08 形态分流）：现货 /api/v3/ticker/24hr + bookTicker；
+   * 永续（`-SWAP` 后缀）走 USDT-M /fapi/v1/ticker/24hr + bookTicker。
+   * 两条路径各自报结构化错误——绝不用现货报价冒充合约价（降级纪律）。
    */
   getTicker(symbol: string): Promise<Ticker>;
+  /** K 线（2026-10-08 形态分流）：现货 /api/v3/klines；永续 /fapi/v1/klines，行结构同形。 */
   getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
   /**
-   * 全部可交易现货标的名册（GET /api/v3/exchangeInfo，status=TRADING 过滤，Issue #15）。
-   * 输出 symbol 为规范形（BTCUSDT），name 为 baseAsset/quoteAsset（如 BTC/USDT）。
+   * 全部可交易标的名册 = 现货 ∪ USDT-M 永续（2026-10-08 形态维度落地，Issue #15 扩展）。
+   *
+   * - 现货：GET /api/v3/exchangeInfo，`status=TRADING` → `BTCUSDT`（form=spot，
+   *   assetClass=crypto：Binance 现货名册无 TradFi 条目）。
+   * - 永续：GET /fapi/v1/exchangeInfo，`contractType` ∈ {PERPETUAL, TRADIFI_PERPETUAL}
+   *   且 `status=TRADING` → `BTCUSDT-SWAP`（form=perp，与现货成对）；assetClass 取
+   *   underlyingType/underlyingSubType（取不到留空），contract 取 contractSize/
+   *   filters/marginAsset。TradFi 永续的字面量是 TRADIFI_PERPETUAL（实测 217 行），
+   *   只认 PERPETUAL 会把股票/大宗/外汇合约整批漏掉。
+   *
+   * 两半都是名册契约的一部分：任一半失败即抛结构化错误，**不返回半份名册**
+   * （静默半份会让检索排序与可用性判断失真，调用方按错误决定自己的兜底目录）。
+   */
+  listInstruments(): Promise<InstrumentRef[]>;
+  /**
+   * 盘口快照：GET /api/v3/depth（现货）或 /fapi/v1/depth（永续），limit=20 档；
+   * bids 降序 / asks 升序，Binance 原生序。永续不再回落现货 depth（合约盘口
+   * 落到现货端点等于把现货深度伪装成合约深度）。
    */
-  listInstruments(): Promise<Array<{
-    symbol: string;
-    name?: string;
-  }>>;
-  /** 盘口快照：GET /api/v3/depth（limit=20 档；bids 降序 / asks 升序，Binance 原生序）。 */
   getOrderbook(symbol: string): Promise<Orderbook>;
-  /** 最近逐笔成交：GET /api/v3/trades（时间升序；isBuyerMaker=true → 主动卖）。 */
+  /** 最近逐笔成交：GET /api/v3/trades（现货）或 /fapi/v1/trades（永续），时间升序。 */
   getRecentTrades(symbol: string, limit?: number): Promise<TradeTick[]>;
   /** 未平仓合约量：GET /fapi/v1/openInterest（openInterest 以 base 币计，time=快照 ms）。 */
   getFuturesOpenInterest(symbol: string): Promise<{
@@ -77,4 +111,4 @@ declare class BinanceRestClient {
   getFuturesOpenInterestHistory(symbol: string, limit?: number): Promise<DerivativesPoint[]>;
 }
 //#endregion
-export { BinanceRestClient, BinanceRestOptions, INTERVAL_VOCABULARY, TradingServiceError, normalizeBinanceFuturesSymbol };
+export { BinanceRestClient, BinanceRestOptions, INTERVAL_VOCABULARY, TradingServiceError, binanceAssetClassOf, binanceContractOf, normalizeBinanceFuturesSymbol, resolveBinanceInstrument };

package/lib/rest.js

@@ -1,3 +1,4 @@
+import { SWAP_SYMBOL_SUFFIX, instrumentFormOf } from "@dshtrading/api";
 //#region src/rest.ts
 /** api 包 TradingError 契约的运行时 Error 实现。 */
 var TradingServiceError = class extends Error {
@@ -48,6 +49,28 @@ function normalizeBinanceFuturesSymbol(raw) {
 	const clean = requireSymbol(raw).replace(/[-_]/g, "");
 	return clean.endsWith("SWAP") ? clean.slice(0, -4) : clean;
 }
+/**
+* 输入符号 → 形态 + 交易所词汇（2026-10-08 加密永续落地）。
+*
+* Binance 现货与永续在交易所侧**同形**（都叫 `BTCUSDT`），形态只能由规范后缀
+* `-SWAP` 裁决——单一实现是 @dshtrading/api 的 `instrumentFormOf`，这里不另写
+* 一份 endsWith。永续剥掉后缀后复用既有衍生品归一（同时容忍 OKX 原生形
+* `BTC-USDT-SWAP`）；现货保持原样交给交易所判存在性（未知符号仍报 -1121）。
+*/
+function resolveBinanceInstrument(symbol) {
+	const upper = requireSymbol(symbol);
+	const form = instrumentFormOf(upper);
+	if (form === "spot") return {
+		form,
+		venueSymbol: upper
+	};
+	const venueSymbol = normalizeBinanceFuturesSymbol(upper);
+	if (venueSymbol === "") throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Binance: ${JSON.stringify(symbol)} carries the ${SWAP_SYMBOL_SUFFIX} suffix but has no base symbol`);
+	return {
+		form,
+		venueSymbol
+	};
+}
 /** Binance 返回数值均为字符串，宽松转 number（非有限值返回 undefined）。 */
 function num(value) {
 	if (value === "") return void 0;
@@ -136,6 +159,63 @@ function parseTradeRow(row, symbol) {
 		timestamp: num(d.time) ?? Date.now()
 	};
 }
+/**
+* Binance 合约 underlying 元数据 → 资产类别标签。
+*
+* 只登记 Binance 公开字段的**实测取值**；未登记一律 undefined（留空），禁止按符号猜
+* （硬不变量 #2：TradFi 归属只信交易所元数据）。
+*
+* 2026-10-08 可达环境实测取值（924 行 USDT-M exchangeInfo，见
+* spikes/impl-crypto-perp-tradfi/EVIDENCE-reverify-2026-10-08.md）：
+* COIN 704 / EQUITY 179 / HK_EQUITY 15 / COMMODITY 8 / KR_EQUITY 8 / PREMARKET 4 /
+* INDEX 3 / CN_EQUITY 2 / FX 1。
+* - PREMARKET 是 Pre-IPO 股票合约（OPENAI/ANTHROPIC/MOONSHOT/OURA，underlyingSubType
+*   ["Pre-IPO","TradFi"]）⇒ 归 equity；枚举里没有 premarket 成员，投影由字面量裁决而非符号。
+* - FX（USDBRLUSDT）**故意不登记**：枚举没有外汇成员，硬塞进 equity/commodity 就是错标，
+*   按「未登记即留空」兜底（漏标而非错标）。要不要加 FX 成员属契约层决定，不在本连接器内定。
+*/
+const BINANCE_UNDERLYING_ASSET_CLASS = {
+	COIN: "crypto",
+	CRYPTO: "crypto",
+	STOCK: "equity",
+	EQUITY: "equity",
+	HK_EQUITY: "equity",
+	KR_EQUITY: "equity",
+	CN_EQUITY: "equity",
+	PREMARKET: "equity",
+	INDEX: "index",
+	COMMODITY: "commodity"
+};
+/**
+* USDT-M 名册里的永续字面量：加密永续 `PERPETUAL`、TradFi 永续 `TRADIFI_PERPETUAL`
+* （2026-10-08 实测 703 / 217）。只按 `PERPETUAL` 过滤会把全部 TradFi 永续整批漏掉。
+*/
+const BINANCE_PERPETUAL_CONTRACT_TYPES = /* @__PURE__ */ new Set(["PERPETUAL", "TRADIFI_PERPETUAL"]);
+/** underlyingType（含 underlyingSubType 逐项兜底）→ 资产类别；未登记/缺失 = undefined。 */
+function binanceAssetClassOf(underlyingType, underlyingSubType) {
+	const candidates = [underlyingType];
+	if (Array.isArray(underlyingSubType)) candidates.push(...underlyingSubType);
+	for (const candidate of candidates) {
+		if (typeof candidate !== "string") continue;
+		const mapped = BINANCE_UNDERLYING_ASSET_CLASS[candidate.trim().toUpperCase()];
+		if (mapped !== void 0) return mapped;
+	}
+}
+/** USDT-M 合约规格 → InstrumentContract（交易所元数据原样透传；字段缺失即缺省）。 */
+function binanceContractOf(row) {
+	const filters = Array.isArray(row.filters) ? row.filters : [];
+	const multiplier = num(row.contractSize);
+	const tickSize = num(filters.find((f) => f.filterType === "PRICE_FILTER")?.tickSize);
+	const lotSize = num(filters.find((f) => f.filterType === "LOT_SIZE")?.stepSize);
+	const settleCcy = typeof row.marginAsset === "string" && row.marginAsset !== "" ? row.marginAsset : void 0;
+	if (multiplier === void 0 && tickSize === void 0 && lotSize === void 0 && settleCcy === void 0) return;
+	return {
+		...multiplier !== void 0 ? { multiplier } : {},
+		...tickSize !== void 0 ? { tickSize } : {},
+		...lotSize !== void 0 ? { lotSize } : {},
+		...settleCcy !== void 0 ? { settleCcy } : {}
+	};
+}
 var BinanceRestClient = class {
 	#baseUrl;
 	#fapiBaseUrl;
@@ -169,22 +249,28 @@ var BinanceRestClient = class {
 		}
 	}
 	/**
-	* 最新行情：/api/v3/ticker/24hr 提供最新价与 24h 量，/api/v3/ticker/bookTicker 补充 bid/ask。
+	* 最新行情（2026-10-08 形态分流）：现货 /api/v3/ticker/24hr + bookTicker；
+	* 永续（`-SWAP` 后缀）走 USDT-M /fapi/v1/ticker/24hr + bookTicker。
+	* 两条路径各自报结构化错误——绝不用现货报价冒充合约价（降级纪律）。
 	*/
 	async getTicker(symbol) {
-		const sym = requireSymbol(symbol);
-		const [day, book] = await Promise.all([this.#request("/api/v3/ticker/24hr", { symbol: sym }), this.#request("/api/v3/ticker/bookTicker", { symbol: sym })]);
+		const { form, venueSymbol } = resolveBinanceInstrument(symbol);
+		const perp = form === "perp";
+		const prefix = perp ? "/fapi/v1/ticker" : "/api/v3/ticker";
+		const base = perp ? this.#fapiBaseUrl : this.#baseUrl;
+		const [day, book] = await Promise.all([this.#request(`${prefix}/24hr`, { symbol: venueSymbol }, base), this.#request(`${prefix}/bookTicker`, { symbol: venueSymbol }, base)]);
 		const d = day;
 		const b = book;
 		const price = num(d.lastPrice);
-		if (price === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance ticker for ${sym}: missing/invalid lastPrice`);
+		if (price === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance ticker for ${venueSymbol}: missing/invalid lastPrice`);
 		const bid = num(b.bidPrice);
 		const ask = num(b.askPrice);
 		const volume = num(d.volume);
 		const prevClose = num(d.prevClosePrice);
 		const changePercent = num(d.priceChangePercent);
+		const resolvedSymbol = typeof d.symbol === "string" && d.symbol ? d.symbol : venueSymbol;
 		return {
-			symbol: typeof d.symbol === "string" && d.symbol ? d.symbol : sym,
+			symbol: perp ? `${resolvedSymbol}${SWAP_SYMBOL_SUFFIX}` : resolvedSymbol,
 			price,
 			timestamp: Date.now(),
 			...bid !== void 0 ? { bid } : {},
@@ -194,53 +280,93 @@ var BinanceRestClient = class {
 			...changePercent !== void 0 ? { changePercent } : {}
 		};
 	}
+	/** K 线（2026-10-08 形态分流）：现货 /api/v3/klines；永续 /fapi/v1/klines，行结构同形。 */
 	async getKlines(symbol, interval, limit = 100) {
-		const sym = requireSymbol(symbol);
+		const { form, venueSymbol } = resolveBinanceInstrument(symbol);
+		const perp = form === "perp";
 		if (!isInterval(interval)) throw new TradingServiceError("TRADING_UNSUPPORTED_INTERVAL", `Binance klines: unsupported interval ${String(interval)}`);
 		if (!Number.isInteger(limit) || limit < 1 || limit > 1e3) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance klines: limit must be an integer within 1..1000, got ${limit}`);
-		const body = await this.#request("/api/v3/klines", {
-			symbol: sym,
+		const body = await this.#request(perp ? "/fapi/v1/klines" : "/api/v3/klines", {
+			symbol: venueSymbol,
 			interval,
 			limit: String(limit)
-		});
-		if (!Array.isArray(body)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance klines for ${sym}: unexpected response shape`);
-		return body.map((row) => parseKlineRow(row, sym));
+		}, perp ? this.#fapiBaseUrl : this.#baseUrl);
+		if (!Array.isArray(body)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance klines for ${venueSymbol}: unexpected response shape`);
+		return body.map((row) => parseKlineRow(row, venueSymbol));
 	}
 	/**
-	* 全部可交易现货标的名册（GET /api/v3/exchangeInfo，status=TRADING 过滤，Issue #15）。
-	* 输出 symbol 为规范形（BTCUSDT），name 为 baseAsset/quoteAsset（如 BTC/USDT）。
+	* 全部可交易标的名册 = 现货 ∪ USDT-M 永续（2026-10-08 形态维度落地，Issue #15 扩展）。
+	*
+	* - 现货：GET /api/v3/exchangeInfo，`status=TRADING` → `BTCUSDT`（form=spot，
+	*   assetClass=crypto：Binance 现货名册无 TradFi 条目）。
+	* - 永续：GET /fapi/v1/exchangeInfo，`contractType` ∈ {PERPETUAL, TRADIFI_PERPETUAL}
+	*   且 `status=TRADING` → `BTCUSDT-SWAP`（form=perp，与现货成对）；assetClass 取
+	*   underlyingType/underlyingSubType（取不到留空），contract 取 contractSize/
+	*   filters/marginAsset。TradFi 永续的字面量是 TRADIFI_PERPETUAL（实测 217 行），
+	*   只认 PERPETUAL 会把股票/大宗/外汇合约整批漏掉。
+	*
+	* 两半都是名册契约的一部分：任一半失败即抛结构化错误，**不返回半份名册**
+	* （静默半份会让检索排序与可用性判断失真，调用方按错误决定自己的兜底目录）。
 	*/
 	async listInstruments() {
-		const info = await this.#request("/api/v3/exchangeInfo", {});
-		if (!Array.isArray(info?.symbols)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", "Binance exchangeInfo: invalid response shape");
+		const [spotBody, futuresBody] = await Promise.all([this.#request("/api/v3/exchangeInfo", {}), this.#request("/fapi/v1/exchangeInfo", {}, this.#fapiBaseUrl)]);
+		const spotSymbols = spotBody.symbols;
+		if (!Array.isArray(spotSymbols)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", "Binance exchangeInfo: invalid response shape");
+		const futuresSymbols = futuresBody.symbols;
+		if (!Array.isArray(futuresSymbols)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", "Binance futures exchangeInfo: invalid response shape");
 		const result = [];
-		for (const item of info.symbols) if (item && item.status === "TRADING" && typeof item.symbol === "string" && item.symbol) {
-			const name = item.baseAsset && item.quoteAsset ? `${item.baseAsset}/${item.quoteAsset}` : void 0;
+		for (const raw of spotSymbols) {
+			const item = raw;
+			if (item?.status !== "TRADING" || typeof item.symbol !== "string" || item.symbol === "") continue;
+			const name = typeof item.baseAsset === "string" && item.baseAsset !== "" && typeof item.quoteAsset === "string" && item.quoteAsset !== "" ? `${item.baseAsset}/${item.quoteAsset}` : void 0;
 			result.push({
 				symbol: item.symbol,
-				...name ? { name } : {}
+				...name !== void 0 ? { name } : {},
+				form: "spot",
+				assetClass: "crypto"
+			});
+		}
+		for (const raw of futuresSymbols) {
+			const item = raw;
+			if (typeof item?.contractType !== "string" || !BINANCE_PERPETUAL_CONTRACT_TYPES.has(item.contractType) || item.status !== "TRADING" || typeof item.symbol !== "string" || item.symbol === "") continue;
+			const name = typeof item.baseAsset === "string" && item.baseAsset !== "" && typeof item.quoteAsset === "string" && item.quoteAsset !== "" ? `${item.baseAsset}/${item.quoteAsset}` : void 0;
+			const assetClass = binanceAssetClassOf(item.underlyingType, item.underlyingSubType);
+			const contract = binanceContractOf(item);
+			result.push({
+				symbol: `${item.symbol}${SWAP_SYMBOL_SUFFIX}`,
+				...name !== void 0 ? { name } : {},
+				form: "perp",
+				...assetClass !== void 0 ? { assetClass } : {},
+				...contract !== void 0 ? { contract } : {}
 			});
 		}
 		return result;
 	}
-	/** 盘口快照：GET /api/v3/depth（limit=20 档；bids 降序 / asks 升序，Binance 原生序）。 */
+	/**
+	* 盘口快照：GET /api/v3/depth（现货）或 /fapi/v1/depth（永续），limit=20 档；
+	* bids 降序 / asks 升序，Binance 原生序。永续不再回落现货 depth（合约盘口
+	* 落到现货端点等于把现货深度伪装成合约深度）。
+	*/
 	async getOrderbook(symbol) {
-		const sym = normalizeBinanceFuturesSymbol(symbol);
-		return parseDepthBody(await this.#request("/api/v3/depth", {
-			symbol: sym,
+		const { form, venueSymbol } = resolveBinanceInstrument(symbol);
+		const perp = form === "perp";
+		return parseDepthBody(await this.#request(perp ? "/fapi/v1/depth" : "/api/v3/depth", {
+			symbol: venueSymbol,
 			limit: "20"
-		}), sym);
+		}, perp ? this.#fapiBaseUrl : this.#baseUrl), perp ? `${venueSymbol}${SWAP_SYMBOL_SUFFIX}` : venueSymbol);
 	}
-	/** 最近逐笔成交：GET /api/v3/trades（时间升序；isBuyerMaker=true → 主动卖）。 */
+	/** 最近逐笔成交：GET /api/v3/trades（现货）或 /fapi/v1/trades（永续），时间升序。 */
 	async getRecentTrades(symbol, limit = 50) {
-		const sym = normalizeBinanceFuturesSymbol(symbol);
+		const { form, venueSymbol } = resolveBinanceInstrument(symbol);
+		const perp = form === "perp";
+		const outputSymbol = perp ? `${venueSymbol}${SWAP_SYMBOL_SUFFIX}` : venueSymbol;
 		const capped = Math.max(1, Math.min(Math.floor(limit) || 50, 100));
-		const body = await this.#request("/api/v3/trades", {
-			symbol: sym,
+		const body = await this.#request(perp ? "/fapi/v1/trades" : "/api/v3/trades", {
+			symbol: venueSymbol,
 			limit: String(capped)
-		});
-		if (!Array.isArray(body)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance trades for ${sym}: unexpected response shape`);
-		return body.map((row) => parseTradeRow(row, sym));
+		}, perp ? this.#fapiBaseUrl : this.#baseUrl);
+		if (!Array.isArray(body)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance trades for ${outputSymbol}: unexpected response shape`);
+		return body.map((row) => parseTradeRow(row, outputSymbol));
 	}
 	/** 未平仓合约量：GET /fapi/v1/openInterest（openInterest 以 base 币计，time=快照 ms）。 */
 	async getFuturesOpenInterest(symbol) {
@@ -363,4 +489,4 @@ var BinanceRestClient = class {
 	}
 };
 //#endregion
-export { BinanceRestClient, INTERVAL_VOCABULARY, TradingServiceError, normalizeBinanceFuturesSymbol };
+export { BinanceRestClient, INTERVAL_VOCABULARY, TradingServiceError, binanceAssetClassOf, binanceContractOf, normalizeBinanceFuturesSymbol, resolveBinanceInstrument };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/connector-binance",
   "description": "Binance market connector plugin for dsh-trading: public market data over REST+WS implementing the @dshtrading/api contracts",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -21,12 +21,13 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/api": "^0.4.1",
-    "@dshtrading/indicators": "^0.4.1"
+    "@dshtrading/authority": "^0.6.0",
+    "@dshtrading/indicators": "^0.6.0",
+    "@dshtrading/api": "^0.6.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0",
-    "@deepseek-ai/dsh-tools": ">=0.1.5-rc.1",
+    "@deepseek-ai/dsh-tools": ">=0.2.0-rc.2",
     "@deepseek-ai/schemastery": ">=3.18.0"
   },
   "devDependencies": {