@dshtrading/connector-binance 0.1.0

package/LICENSE

@@ -0,0 +1,75 @@
+Copyright (c) 2026 zhu1090093659 (dsh-trading)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/lib/dataplane.d.ts

@@ -0,0 +1,7 @@
+import { Config } from "./index.js";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/dataplane.d.ts
+declare const inject: string[];
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { apply, inject };

package/lib/dataplane.js

@@ -0,0 +1,22 @@
+import { BinanceMarketDataService, ROUTER_PROVIDER, TRADING_CRYPTO_MARKET_DATA_KEY, routeAllows } from "./index.js";
+//#region src/dataplane.ts
+const inject = [];
+/** 解析注册表服务；老部署（base/router 未升级）返回 undefined → 调用方回退旧的直接 provide 路径。 */
+function resolveMarketDataRegistry(ctx) {
+	const candidate = ctx.get?.("tradingMarketDataRegistry", false);
+	return candidate !== void 0 ? candidate : void 0;
+}
+function apply(ctx, config) {
+	if (!config.enabled) return;
+	const registry = resolveMarketDataRegistry(ctx);
+	if (registry === void 0) {
+		if (!routeAllows(ctx, config, "crypto")) return;
+		new BinanceMarketDataService(ctx);
+		return;
+	}
+	const inner = ctx.isolate(TRADING_CRYPTO_MARKET_DATA_KEY);
+	const service = new BinanceMarketDataService(inner);
+	ctx.effect(() => registry.register("crypto", ROUTER_PROVIDER, service));
+}
+//#endregion
+export { apply, inject };

package/lib/index.d.ts

@@ -0,0 +1,135 @@
+import { BinanceRestClient, BinanceRestOptions, INTERVAL_VOCABULARY, TradingServiceError, normalizeBinanceFuturesSymbol } 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";
+//#region src/index.d.ts
+/**
+ * Cordis 插件名 = patch 行 id（TEMPLATES §8）：`dsh-trading-crypto-*` 市场命名空间，
+ * 全仓唯一，绝不使用 `base` 等官方保留 id（insert-only 铁律 #1）。
+ */
+declare const name = "dsh-trading-crypto-connector-binance";
+interface Config {
+  /** 互斥激活总开关（默认 true）：false 时本插件不注册任何服务/工具（okx 行启用时须关本开关；docs/okx-integration.md §8.2 方案 B）。 */
+  enabled: boolean;
+  /** 交易安全闸门（铁律 #3）：true 时下单类工具强制 dry-run。 */
+  dryRun: boolean;
+  /** 实盘总闸门：默认 false；false 时无论 dryRun 与否都拒绝实盘下单 [S4]。 */
+  liveTrading: boolean;
+}
+declare const Config: Schema<Config>;
+/** 需要宿主提供的 Cordis 服务。 */
+declare const inject: string[];
+/** ctx 服务键：与 @dshtrading/api 的 Context 模块增强一致（市场命名空间）。 */
+declare const TRADING_CRYPTO_MARKET_DATA_KEY = "tradingCryptoMarketData";
+interface SubscribeTickerOptions {
+  /** 轮询间隔（ms）。切片阶段 subscribeTicker 以 REST 轮询实现，WS 在后续任务。 */
+  readonly intervalMs?: number;
+}
+declare class BinanceMarketDataService extends Service implements MarketDataService {
+  private readonly client;
+  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;
+  }>>;
+  subscribeTicker(symbol: string, cb: (ticker: Ticker) => void, options?: SubscribeTickerOptions): Disposable;
+  /**
+   * 盘口快照（api 可选契约 getOrderbook，issue #39）：现货 depth 20 档透传，
+   * SWAP/原生输入归一到现货词汇（盘口跟图表标的走）。
+   */
+  getOrderbook(symbol: string): Promise<Orderbook>;
+  /** 最近逐笔成交（api 可选契约 getRecentTrades，issue #39），时间升序。 */
+  getRecentTrades(symbol: string, limit?: number): Promise<TradeTick[]>;
+  /**
+   * 衍生品指标快照（api 可选契约 getDerivatives，issue #38）：聚合 Binance USDT-M
+   * 合约公共端点（fapi openInterest / fundingRate / futures/data 多空比族）。
+   * 任一子查询失败只降级该字段（undefined，面板按缺格隐藏）；全部失败才抛
+   * 结构化错误（桥层转 ok:false，前端不弹横幅）。输出 symbol 为规范 SWAP 形。
+   */
+  getDerivatives(symbol: string): Promise<DerivativesData>;
+  /**
+   * 衍生品历史序列（api 可选契约 getDerivativesHistory，issue #54）：
+   * /fapi/v1/fundingRate + /futures/data/openInterestHist 双端点聚合并发拉取，
+   * 任一失败只降级该序列（字段缺省 → 对应趋势卡隐藏），全部失败才抛结构化错误。
+   */
+  getDerivativesHistory(symbol: string): Promise<DerivativesHistory>;
+}
+/** crypto_place_order 参数契约（本切片词汇：Binance 现货下单参数，dryRun 缺省 true）。 */
+interface PlaceOrderArgs {
+  /** 交易对符号，如 `BTCUSDT`（执行前归一化为大写）。 */
+  readonly symbol: string;
+  /** 方向（交易所词汇大写）。 */
+  readonly side: 'BUY' | 'SELL';
+  /** 订单类型（交易所词汇大写）。 */
+  readonly type: 'MARKET' | 'LIMIT';
+  /** base 资产数量，必须 > 0。 */
+  readonly quantity: number;
+  /** LIMIT 单必填（schema 无法条件必填，execute 内校验），必须 > 0。 */
+  readonly price?: number;
+  /** 缺省视为 true：仅模拟。显式 false 即实盘意图，进入闸门 ①/③。 */
+  readonly dryRun?: boolean;
+}
+/**
+ * 闸门判定结果（三条路径，顺序即铁律 #3 修订版的裁决顺序）：
+ *  - `reject`  —— ① 请求实盘（dryRun!==true）而 liveTrading=false：工具返回结构化
+ *                拒绝（不抛异常，模型可读到明确原因与出路）；
+ *  - `simulate` —— ② dryRun=true（显式、缺省，或被插件 config.dryRun 强制）：
+ *                返回 DRY-RUN 模拟成交回执；
+ *  - `live`    —— ③ dryRun=false 且 liveTrading=true：本切片无签名下单能力，
+ *                工具抛 TRADING_NOT_IMPLEMENTED 结构化错误。
+ *
+ * 优先级说明：config.dryRun=true 是「强制模拟」开关，只影响 ②/③ 的归类；
+ * 显式 dryRun=false 的实盘意图在 liveTrading=false 时仍走 ① 明确拒绝，
+ * 不做静默降级（拒绝语义优先于强制模拟，调用方必须知道实盘意图被拒）。
+ */
+type OrderGateVerdict = {
+  action: 'reject';
+  code: 'TRADING_LIVE_TRADING_DISABLED';
+  message: string;
+} | {
+  action: 'simulate';
+} | {
+  action: 'live';
+};
+declare function evaluateOrderGate(config: Config, args: PlaceOrderArgs): OrderGateVerdict;
+/** DRY-RUN 回执：模拟成交 + 当前市价参照（参照取不到不阻断模拟本身）。 */
+interface DryRunReference {
+  source: 'binance-public-ticker';
+  price?: number;
+  bid?: number;
+  ask?: number;
+  timestamp?: number;
+  unavailable?: string;
+}
+declare function buildDryRunReceipt(args: PlaceOrderArgs, marketData: Pick<MarketDataService, 'getTicker'>): Promise<string>;
+interface PlaceOrderToolDeps {
+  /** 行情服务（ dry-run 回执的市价参照），按接口取用，不直连 REST。 */
+  readonly marketData: Pick<MarketDataService, 'getTicker'>;
+  /** 插件配置（dryRun 强制模拟 / liveTrading 总闸门）。 */
+  readonly config: Config;
+}
+/**
+ * crypto_place_order 工具工厂（独立导出便于单测三条闸门路径）。
+ *
+ * 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的 gate 插件在
+ * `tools/pre-execute` waterfall 统一 ask（S4：headless 下 ask=deny，fail-closed）；
+ * 工具内不再重复调 ctx.approval。
+ */
+declare function createPlaceOrderTool(deps: PlaceOrderToolDeps): import("@deepseek-ai/dsh-tools").ToolDefinition;
+/** 本连接器的路由 provider slug（docs/exchange-routing.md §2.2：路由层词汇，非包名）。 */
+declare const ROUTER_PROVIDER = "binance";
+/** 市场路由服务的最小消费面（api 包 MarketRouterService 同构；不定死接口）。 */
+interface MarketRouterLike {
+  activeProvider(market: string): string | undefined;
+}
+/**
+ * 路由裁决（2026-08-29 设置驱动重构）：router 存在且给本市场选了别的 provider →
+ * 本连接器静默退出（设置是权威）；router 不存在（老部署）→ 回退 enabled 语义。
+ * 返回 true = 应继续 apply。
+ */
+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 };

package/lib/index.js

@@ -0,0 +1,359 @@
+import { BinanceRestClient, INTERVAL_VOCABULARY, TradingServiceError, normalizeBinanceFuturesSymbol } from "./rest.js";
+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";
+//#region src/index.ts
+/**
+* 互斥激活的注册面（与 connector-okx 的 registerTool 同款，2026-08-31 补齐）：
+* dsh-tools 对同名重复注册直接抛错，互斥纪律下冲突降级为「先到先得 + warn」。
+* 没有这层时，inject 回调就绪顺序不定会让同名工具（含 crypto_get_indicators）
+* 在两 connector 同树时随机炸挂载——activation.test 曾因此竞态翻车。
+*/
+function registerTool(ctx, tool, log) {
+	const tools = ctx.tools;
+	if (tools.get(tool.name) !== void 0) {
+		log.warn("[dsh-trading-crypto-connector-binance] tool %s already registered by another provider — skipped (mutual exclusion: at most one crypto connector/toolset may be active)", tool.name);
+		return;
+	}
+	tools.register(tool);
+}
+/**
+* Cordis 插件名 = patch 行 id（TEMPLATES §8）：`dsh-trading-crypto-*` 市场命名空间，
+* 全仓唯一，绝不使用 `base` 等官方保留 id（insert-only 铁律 #1）。
+*/
+const name = "dsh-trading-crypto-connector-binance";
+const Config = Schema.object({
+	enabled: Schema.boolean().default(true),
+	dryRun: Schema.boolean().default(true),
+	liveTrading: Schema.boolean().default(false)
+});
+/** 需要宿主提供的 Cordis 服务。 */
+const inject = ["tools"];
+/** ctx 服务键：与 @dshtrading/api 的 Context 模块增强一致（市场命名空间）。 */
+const TRADING_CRYPTO_MARKET_DATA_KEY = "tradingCryptoMarketData";
+const SUBSCRIBE_MIN_MS = 250;
+const SUBSCRIBE_DEFAULT_MS = 5e3;
+var BinanceMarketDataService = class extends Service {
+	client;
+	constructor(ctx, options = {}, name = TRADING_CRYPTO_MARKET_DATA_KEY) {
+		super(ctx, name);
+		this.client = new BinanceRestClient(options);
+	}
+	getTicker(symbol) {
+		return this.client.getTicker(symbol);
+	}
+	getKlines(symbol, interval, limit) {
+		return this.client.getKlines(symbol, interval, limit);
+	}
+	listInstruments() {
+		return this.client.listInstruments();
+	}
+	subscribeTicker(symbol, cb, options) {
+		const ms = Math.max(options?.intervalMs ?? SUBSCRIBE_DEFAULT_MS, SUBSCRIBE_MIN_MS);
+		const tick = () => {
+			this.client.getTicker(symbol).then(cb, () => {});
+		};
+		tick();
+		const timer = setInterval(tick, ms);
+		return { dispose: () => clearInterval(timer) };
+	}
+	/**
+	* 盘口快照（api 可选契约 getOrderbook，issue #39）：现货 depth 20 档透传，
+	* SWAP/原生输入归一到现货词汇（盘口跟图表标的走）。
+	*/
+	async getOrderbook(symbol) {
+		return this.client.getOrderbook(symbol);
+	}
+	/** 最近逐笔成交（api 可选契约 getRecentTrades，issue #39），时间升序。 */
+	async getRecentTrades(symbol, limit = 50) {
+		return this.client.getRecentTrades(symbol, limit);
+	}
+	/**
+	* 衍生品指标快照（api 可选契约 getDerivatives，issue #38）：聚合 Binance USDT-M
+	* 合约公共端点（fapi openInterest / fundingRate / futures/data 多空比族）。
+	* 任一子查询失败只降级该字段（undefined，面板按缺格隐藏）；全部失败才抛
+	* 结构化错误（桥层转 ok:false，前端不弹横幅）。输出 symbol 为规范 SWAP 形。
+	*/
+	async getDerivatives(symbol) {
+		const futuresSymbol = normalizeBinanceFuturesSymbol(symbol);
+		const unavailable = [];
+		const collect = (label, task) => task.catch((error) => {
+			unavailable.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+		});
+		const [interest, funding, globalRatio, topRatio, takerRatio, premium] = await Promise.all([
+			collect("open-interest", this.client.getFuturesOpenInterest(futuresSymbol)),
+			collect("funding", this.client.getFuturesFundingRate(futuresSymbol)),
+			collect("global-ls", this.client.getFuturesLongShortRatio("global", futuresSymbol)),
+			collect("top-ls", this.client.getFuturesLongShortRatio("top", futuresSymbol)),
+			collect("taker", this.client.getFuturesTakerRatio(futuresSymbol)),
+			collect("premium-index", this.client.getFuturesPremiumIndex(futuresSymbol))
+		]);
+		const openInterest = interest?.openInterest;
+		const fundingRate = funding?.fundingRate ?? premium?.lastFundingRate;
+		const longShortRatio = globalRatio;
+		const topTraderLongShortRatio = topRatio;
+		const takerBuySellRatio = takerRatio;
+		const markPrice = premium?.markPrice;
+		const indexPrice = premium?.indexPrice;
+		const nextFundingTime = premium?.nextFundingTime;
+		if (openInterest === void 0 && fundingRate === void 0 && longShortRatio === void 0 && topTraderLongShortRatio === void 0 && takerBuySellRatio === void 0 && markPrice === void 0 && indexPrice === void 0 && nextFundingTime === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance derivatives for ${futuresSymbol}: all sub-queries failed` + (unavailable.length > 0 ? ` (${unavailable.join("; ")})` : ""));
+		return {
+			symbol: `${futuresSymbol}-SWAP`,
+			source: "binance",
+			...openInterest !== void 0 ? { openInterest } : {},
+			...longShortRatio !== void 0 ? { longShortRatio } : {},
+			...topTraderLongShortRatio !== void 0 ? { topTraderLongShortRatio } : {},
+			...takerBuySellRatio !== void 0 ? { takerBuySellRatio } : {},
+			...fundingRate !== void 0 ? { fundingRate } : {},
+			...nextFundingTime !== void 0 ? { nextFundingTime } : {},
+			...markPrice !== void 0 ? { markPrice } : {},
+			...indexPrice !== void 0 ? { indexPrice } : {},
+			timestamp: interest?.time ?? funding?.fundingTime ?? Date.now()
+		};
+	}
+	/**
+	* 衍生品历史序列（api 可选契约 getDerivativesHistory，issue #54）：
+	* /fapi/v1/fundingRate + /futures/data/openInterestHist 双端点聚合并发拉取，
+	* 任一失败只降级该序列（字段缺省 → 对应趋势卡隐藏），全部失败才抛结构化错误。
+	*/
+	async getDerivativesHistory(symbol) {
+		const futuresSymbol = normalizeBinanceFuturesSymbol(symbol);
+		const unavailable = [];
+		const collect = (label, task) => task.catch((error) => {
+			unavailable.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+		});
+		const [fundingRates, openInterest] = await Promise.all([collect("funding-history", this.client.getFuturesFundingRateHistory(futuresSymbol, 30)), collect("oi-history", this.client.getFuturesOpenInterestHistory(futuresSymbol, 30))]);
+		if (fundingRates === void 0 && openInterest === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance derivatives history for ${futuresSymbol}: all sub-queries failed` + (unavailable.length > 0 ? ` (${unavailable.join("; ")})` : ""));
+		return {
+			symbol: `${futuresSymbol}-SWAP`,
+			source: "binance",
+			...fundingRates !== void 0 && fundingRates.length > 0 ? { fundingRates } : {},
+			...openInterest !== void 0 && openInterest.length > 0 ? { openInterest } : {}
+		};
+	}
+};
+function evaluateOrderGate(config, args) {
+	const requestedDryRun = args.dryRun ?? true;
+	if (!requestedDryRun && !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.`
+	};
+	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 (!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`);
+	if (typeof args.quantity !== "number" || !Number.isFinite(args.quantity) || args.quantity <= 0) throw new Error(`crypto_place_order: invalid quantity ${JSON.stringify(args.quantity)} — expected a positive number`);
+	if (args.type === "LIMIT" && (typeof args.price !== "number" || !Number.isFinite(args.price) || args.price <= 0)) throw new Error("crypto_place_order: LIMIT orders require a positive price");
+}
+function normalizePlaceOrderArgs(raw) {
+	const args = raw ?? {};
+	const symbol = typeof args.symbol === "string" ? args.symbol.trim().toUpperCase() : void 0;
+	return {
+		...args,
+		symbol
+	};
+}
+async function buildDryRunReceipt(args, marketData) {
+	let reference;
+	try {
+		const ticker = await marketData.getTicker(args.symbol);
+		reference = {
+			source: "binance-public-ticker",
+			price: ticker.price,
+			bid: ticker.bid,
+			ask: ticker.ask,
+			timestamp: ticker.timestamp
+		};
+	} catch (error) {
+		reference = {
+			source: "binance-public-ticker",
+			unavailable: error instanceof Error ? error.message : String(error)
+		};
+	}
+	return JSON.stringify({
+		status: "filled",
+		dryRun: true,
+		note: "DRY-RUN — simulated fill; no order was sent to any exchange. The reference price is market data only, not a fill price.",
+		id: `dry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+		symbol: args.symbol,
+		side: args.side.toLowerCase(),
+		type: args.type.toLowerCase(),
+		quantity: args.quantity,
+		...args.type === "LIMIT" ? { price: args.price } : {},
+		reference,
+		timestamp: Date.now()
+	});
+}
+/**
+* crypto_place_order 工具工厂（独立导出便于单测三条闸门路径）。
+*
+* 审批不在这里做：dryRun!==true 的调用由 @dshtrading/base 的 gate 插件在
+* `tools/pre-execute` waterfall 统一 ask（S4：headless 下 ask=deny，fail-closed）；
+* 工具内不再重复调 ctx.approval。
+*/
+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.",
+		parameters: {
+			symbol: {
+				type: "string",
+				required: true,
+				description: "Trading pair symbol, e.g. BTCUSDT"
+			},
+			side: {
+				type: "string",
+				enum: ["BUY", "SELL"],
+				required: true,
+				description: "Order side"
+			},
+			type: {
+				type: "string",
+				enum: ["MARKET", "LIMIT"],
+				required: true,
+				description: "Order type"
+			},
+			quantity: {
+				type: "number",
+				required: true,
+				description: "Base asset quantity, must be > 0"
+			},
+			price: {
+				type: "number",
+				description: "Limit price; required when type=LIMIT"
+			},
+			dryRun: {
+				type: "boolean",
+				description: "true (default) = simulate only and return a DRY-RUN receipt; false = request real execution (gated by liveTrading and user approval)",
+				default: true
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute(raw) {
+			const args = normalizePlaceOrderArgs(raw);
+			validatePlaceOrderArgs(args);
+			const verdict = evaluateOrderGate(deps.config, args);
+			if (verdict.action === "reject") return JSON.stringify({
+				status: "rejected",
+				code: verdict.code,
+				message: verdict.message
+			});
+			if (verdict.action === "simulate") return buildDryRunReceipt(args, deps.marketData);
+			throw new TradingServiceError("TRADING_NOT_IMPLEMENTED", "crypto_place_order: live order execution is not implemented in this slice — signed order placement (credentials + exchange endpoint) is a follow-up task. Keep dryRun=true for simulated fills.");
+		}
+	});
+}
+function logger(ctx) {
+	const service = ctx.logger;
+	return typeof service === "function" ? service(name) : console;
+}
+/** 本连接器的路由 provider slug（docs/exchange-routing.md §2.2：路由层词汇，非包名）。 */
+const ROUTER_PROVIDER = "binance";
+/**
+* 路由裁决（2026-08-29 设置驱动重构）：router 存在且给本市场选了别的 provider →
+* 本连接器静默退出（设置是权威）；router 不存在（老部署）→ 回退 enabled 语义。
+* 返回 true = 应继续 apply。
+*/
+function routeAllows(ctx, config, market) {
+	if (!config.enabled) return false;
+	const router = ctx.get?.("tradingMarketRouter", false);
+	if (router === void 0) return true;
+	return router.activeProvider(market) === ROUTER_PROVIDER;
+}
+function apply(ctx, config) {
+	const log = logger(ctx);
+	if (!config.enabled) {
+		log.info("[dsh-trading-crypto-connector-binance] not activated (enabled=false) — tradingCryptoMarketData and crypto_* tools stay unregistered; market data comes from the other active connector");
+		return;
+	}
+	const router = ctx.get?.("tradingMarketRouter", false);
+	const active = router?.activeProvider("crypto");
+	if (router !== void 0 && active !== "binance") {
+		log.info("[dsh-trading-crypto-connector-binance] market router selects %s for crypto — not activated; set dshtrading.markets.crypto.provider to binance to use this connector", String(active ?? "(unset)"));
+		return;
+	}
+	new BinanceMarketDataService(ctx);
+	ctx.inject(["tradingCryptoMarketData"], (ctx) => {
+		const marketData = ctx.tradingCryptoMarketData;
+		const register = (tool) => registerTool(ctx, tool, log);
+		register(createGetIndicatorsTool({
+			marketData,
+			providerLabel: "binance"
+		}));
+		register(defineTool({
+			name: "crypto_get_ticker",
+			description: "Get the latest public ticker (last price, bid/ask, 24h volume) for a crypto symbol via the Binance public REST API. No credentials required.",
+			parameters: { symbol: {
+				type: "string",
+				required: true,
+				description: "Trading pair symbol, e.g. BTCUSDT"
+			} },
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const ticker = await marketData.getTicker(args.symbol);
+				return JSON.stringify(ticker);
+			}
+		}));
+		register(defineTool({
+			name: "crypto_get_klines",
+			description: "Get recent public klines (candles: open/high/low/close/volume) for a crypto symbol via the Binance public REST API. No credentials required.",
+			parameters: {
+				symbol: {
+					type: "string",
+					required: true,
+					description: "Trading pair symbol, e.g. BTCUSDT"
+				},
+				interval: {
+					type: "string",
+					enum: INTERVAL_VOCABULARY,
+					description: "Kline interval (Binance vocabulary)",
+					default: "1h"
+				},
+				limit: {
+					type: "integer",
+					description: "Number of candles to return (1-1000)",
+					default: 100
+				}
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_args, value) => [{
+					type: "text",
+					text: value
+				}]
+			},
+			async execute(args) {
+				const interval = args.interval ?? "1h";
+				const limit = args.limit ?? 100;
+				const klines = await marketData.getKlines(args.symbol, interval, limit);
+				return JSON.stringify(klines);
+			}
+		}));
+		register(createPlaceOrderTool({
+			marketData,
+			config
+		}));
+	});
+}
+//#endregion
+export { BinanceMarketDataService, BinanceRestClient, Config, INTERVAL_VOCABULARY, ROUTER_PROVIDER, TRADING_CRYPTO_MARKET_DATA_KEY, TradingServiceError, apply, buildDryRunReceipt, createPlaceOrderTool, evaluateOrderGate, inject, name, normalizeBinanceFuturesSymbol, routeAllows };

package/lib/rest.d.ts

@@ -0,0 +1,80 @@
+import { DerivativesPoint, Interval, Kline, Orderbook, Ticker, TradeTick, TradingErrorCode } from "@dshtrading/api";
+//#region src/rest.d.ts
+/** api 包 TradingError 契约的运行时 Error 实现。 */
+declare class TradingServiceError extends Error {
+  readonly code: TradingErrorCode;
+  constructor(code: TradingErrorCode, message: string, cause?: unknown);
+}
+interface BinanceRestOptions {
+  /** 覆盖 API base（测试/反代用），末尾不带斜杠。 */
+  readonly baseUrl?: string;
+  /** 覆盖 USDT-M 合约（fapi）base（测试/反代用），末尾不带斜杠。 */
+  readonly fapiBaseUrl?: string;
+  /** 单请求超时（ms），默认 10s。 */
+  readonly timeoutMs?: number;
+  /** 注入 fetch 实现；缺省用全局 fetch（Node 22+ 内置）。 */
+  readonly fetchImpl?: typeof fetch;
+}
+/** 全量 interval 词汇，供工具 parameters 的 enum 使用。 */
+declare const INTERVAL_VOCABULARY: readonly string[];
+/**
+ * 衍生品输入归一（issue #38，与 kit-crypto/derivatives 同词汇）：规范现货、规范 SWAP、
+ * OKX 原生 SWAP 形一律归一到 fapi 词汇——BTCUSDT / BTCUSDT-SWAP / BTC-USDT-SWAP → BTCUSDT。
+ */
+declare function normalizeBinanceFuturesSymbol(raw: string): string;
+declare class BinanceRestClient {
+  #private;
+  constructor(options?: BinanceRestOptions);
+  /**
+   * 最新行情：/api/v3/ticker/24hr 提供最新价与 24h 量，/api/v3/ticker/bookTicker 补充 bid/ask。
+   */
+  getTicker(symbol: string): Promise<Ticker>;
+  getKlines(symbol: string, interval: Interval, limit?: number): Promise<Kline[]>;
+  /**
+   * 全部可交易现货标的名册（GET /api/v3/exchangeInfo，status=TRADING 过滤，Issue #15）。
+   * 输出 symbol 为规范形（BTCUSDT），name 为 baseAsset/quoteAsset（如 BTC/USDT）。
+   */
+  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 → 主动卖）。 */
+  getRecentTrades(symbol: string, limit?: number): Promise<TradeTick[]>;
+  /** 未平仓合约量：GET /fapi/v1/openInterest（openInterest 以 base 币计，time=快照 ms）。 */
+  getFuturesOpenInterest(symbol: string): Promise<{
+    openInterest: number;
+    time: number;
+  }>;
+  /** 最新资金费率：GET /fapi/v1/fundingRate?limit=1（[{ fundingRate, fundingTime }]，费率为小数）。 */
+  getFuturesFundingRate(symbol: string): Promise<{
+    fundingRate: number;
+    fundingTime: number;
+  }>;
+  /** 多空持仓人数比族：GET /futures/data/{globalLongShortAccountRatio|topLongShortPositionRatio}（period=1h，limit=1）。 */
+  getFuturesLongShortRatio(kind: 'global' | 'top', symbol: string): Promise<number>;
+  /** 主动买卖量比：GET /futures/data/takerlongshortRatio（period=1h，limit=1，buySellRatio=买/卖）。 */
+  getFuturesTakerRatio(symbol: string): Promise<number>;
+  /**
+   * 标记/指数价格与下期结算：GET /fapi/v1/premiumIndex —— 单端点同时携带
+   * markPrice / indexPrice / lastFundingRate / nextFundingTime
+   * （2026-09-03 真实网络实证，spikes/impl-crypto-derivatives）。
+   */
+  getFuturesPremiumIndex(symbol: string): Promise<{
+    markPrice?: number;
+    indexPrice?: number;
+    lastFundingRate?: number;
+    nextFundingTime?: number;
+    time: number;
+  }>;
+  /** 资金费率历史：GET /fapi/v1/fundingRate（时间升序；value 为小数费率）。 */
+  getFuturesFundingRateHistory(symbol: string, limit?: number): Promise<DerivativesPoint[]>;
+  /**
+   * OI 历史：GET /futures/data/openInterestHist（period=1d；sumOpenInterest 为 base 币数，
+   * 与快照 openInterest 同语义。2026-09-03 真实网络实证）。响应时间升序。
+   */
+  getFuturesOpenInterestHistory(symbol: string, limit?: number): Promise<DerivativesPoint[]>;
+}
+//#endregion
+export { BinanceRestClient, BinanceRestOptions, INTERVAL_VOCABULARY, TradingServiceError, normalizeBinanceFuturesSymbol };

package/lib/rest.js

@@ -0,0 +1,366 @@
+//#region src/rest.ts
+/** api 包 TradingError 契约的运行时 Error 实现。 */
+var TradingServiceError = class extends Error {
+	code;
+	constructor(code, message, cause) {
+		super(message);
+		this.name = "TradingServiceError";
+		this.code = code;
+		if (cause !== void 0) this.cause = cause;
+	}
+};
+const DEFAULT_BASE_URL = "https://api.binance.com";
+const DEFAULT_FAPI_BASE_URL = "https://fapi.binance.com";
+const DEFAULT_TIMEOUT_MS = 1e4;
+/** Binance klines 支持的 interval 词汇（与 api 包 Interval 对齐）。 */
+const INTERVALS = [
+	"1m",
+	"3m",
+	"5m",
+	"15m",
+	"30m",
+	"1h",
+	"2h",
+	"4h",
+	"6h",
+	"8h",
+	"12h",
+	"1d",
+	"3d",
+	"1w",
+	"1M"
+];
+/** 全量 interval 词汇，供工具 parameters 的 enum 使用。 */
+const INTERVAL_VOCABULARY = INTERVALS;
+function isInterval(value) {
+	return typeof value === "string" && INTERVALS.includes(value);
+}
+/** 校验并规范化 symbol（Binance 现货符号为大写无分隔，如 BTCUSDT）。 */
+function requireSymbol(symbol) {
+	if (typeof symbol !== "string" || !symbol.trim()) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", "Symbol must be a non-empty string, e.g. BTCUSDT");
+	return symbol.trim().toUpperCase();
+}
+/**
+* 衍生品输入归一（issue #38，与 kit-crypto/derivatives 同词汇）：规范现货、规范 SWAP、
+* OKX 原生 SWAP 形一律归一到 fapi 词汇——BTCUSDT / BTCUSDT-SWAP / BTC-USDT-SWAP → BTCUSDT。
+*/
+function normalizeBinanceFuturesSymbol(raw) {
+	const clean = requireSymbol(raw).replace(/[-_]/g, "");
+	return clean.endsWith("SWAP") ? clean.slice(0, -4) : clean;
+}
+/** Binance 返回数值均为字符串，宽松转 number（非有限值返回 undefined）。 */
+function num(value) {
+	if (value === "") return void 0;
+	const n = typeof value === "string" ? Number(value) : typeof value === "number" ? value : NaN;
+	return Number.isFinite(n) ? n : void 0;
+}
+/** Binance 错误码 → api 词汇的已知映射（-1121 Invalid symbol / -1120 Invalid period）。 */
+const BINANCE_CODE_MAP = /* @__PURE__ */ new Map([[-1121, "TRADING_UNSUPPORTED_SYMBOL"], [-1120, "TRADING_UNSUPPORTED_INTERVAL"]]);
+async function httpToTradingError(res, path) {
+	let body;
+	try {
+		body = await res.json();
+	} catch {
+		body = void 0;
+	}
+	const err = body ?? {};
+	const binanceCode = typeof err.code === "number" ? err.code : void 0;
+	const binanceMsg = typeof err.msg === "string" ? err.msg : "";
+	let code;
+	if (res.status === 429 || res.status === 418) code = "TRADING_RATE_LIMITED";
+	else if (res.status === 401 || res.status === 403) code = "TRADING_AUTH_FAILED";
+	else if (binanceCode !== void 0 && BINANCE_CODE_MAP.has(binanceCode)) code = BINANCE_CODE_MAP.get(binanceCode);
+	else code = "TRADING_EXCHANGE_ERROR";
+	const detail = [
+		res.status,
+		binanceCode !== void 0 ? `code=${binanceCode}` : void 0,
+		binanceMsg || res.statusText
+	].filter((part) => part !== void 0 && part !== "").join(" ");
+	return new TradingServiceError(code, `Binance ${path}: ${detail}`);
+}
+/** K 线响应行：[openTime, open, high, low, close, volume, closeTime, ...]。 */
+function parseKlineRow(row, symbol) {
+	if (!Array.isArray(row) || row.length < 7) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance klines: malformed row for ${symbol}`);
+	const openTime = num(row[0]);
+	const open = num(row[1]);
+	const high = num(row[2]);
+	const low = num(row[3]);
+	const close = num(row[4]);
+	const volume = num(row[5]);
+	const closeTime = num(row[6]);
+	if (openTime === void 0 || open === void 0 || high === void 0 || low === void 0 || close === void 0 || volume === void 0 || closeTime === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance klines: malformed row values for ${symbol}`);
+	return {
+		openTime,
+		open,
+		high,
+		low,
+		close,
+		volume,
+		closeTime
+	};
+}
+/** depth 档位行 [price, quantity] → OrderbookLevel（字符串数值，宽容解析）。 */
+function parseDepthLevel(row) {
+	if (!Array.isArray(row) || row.length < 2) return void 0;
+	const price = num(row[0]);
+	const amount = num(row[1]);
+	if (price === void 0 || amount === void 0 || price <= 0 || amount <= 0) return void 0;
+	return {
+		price,
+		amount
+	};
+}
+/** depth 响应（bids 降序 / asks 升序，Binance 原生序）→ Orderbook。 */
+function parseDepthBody(body, symbol) {
+	const d = body;
+	if (!Array.isArray(d?.bids) || !Array.isArray(d?.asks)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance depth for ${symbol}: unexpected response shape`);
+	return {
+		symbol,
+		bids: d.bids.map(parseDepthLevel).filter((l) => l !== void 0),
+		asks: d.asks.map(parseDepthLevel).filter((l) => l !== void 0),
+		timestamp: Date.now()
+	};
+}
+/** 逐笔成交行（/api/v3/trades）→ TradeTick（isBuyerMaker=true → taker 是卖方）。 */
+function parseTradeRow(row, symbol) {
+	const d = row;
+	const price = num(d.price);
+	const amount = num(d.qty);
+	if (price === void 0 || amount === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance trades for ${symbol}: malformed trade row`);
+	return {
+		id: String(d.id ?? ""),
+		symbol,
+		price,
+		amount,
+		side: d.isBuyerMaker === true ? "sell" : d.isBuyerMaker === false ? "buy" : "unknown",
+		timestamp: num(d.time) ?? Date.now()
+	};
+}
+var BinanceRestClient = class {
+	#baseUrl;
+	#fapiBaseUrl;
+	#timeoutMs;
+	#fetchImpl;
+	constructor(options = {}) {
+		this.#baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+		this.#fapiBaseUrl = options.fapiBaseUrl ?? DEFAULT_FAPI_BASE_URL;
+		this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+		this.#fetchImpl = options.fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
+	}
+	async #request(path, params, base = this.#baseUrl) {
+		const query = new URLSearchParams(params).toString();
+		const target = query ? `${base}${path}?${query}` : `${base}${path}`;
+		const controller = new AbortController();
+		const timer = setTimeout(() => controller.abort(new DOMException(`request timed out after ${this.#timeoutMs}ms`, "TimeoutError")), this.#timeoutMs);
+		let res;
+		try {
+			res = await this.#fetchImpl(target, { signal: controller.signal });
+		} catch (cause) {
+			const timedOut = controller.signal.aborted;
+			throw new TradingServiceError("TRADING_NETWORK", timedOut ? `Binance ${path}: request timed out after ${this.#timeoutMs}ms` : `Binance ${path}: network error`, cause);
+		} finally {
+			clearTimeout(timer);
+		}
+		if (!res.ok) throw await httpToTradingError(res, path);
+		try {
+			return await res.json();
+		} catch (cause) {
+			throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance ${path}: invalid JSON response`, cause);
+		}
+	}
+	/**
+	* 最新行情：/api/v3/ticker/24hr 提供最新价与 24h 量，/api/v3/ticker/bookTicker 补充 bid/ask。
+	*/
+	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 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`);
+		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);
+		return {
+			symbol: typeof d.symbol === "string" && d.symbol ? d.symbol : sym,
+			price,
+			timestamp: Date.now(),
+			...bid !== void 0 ? { bid } : {},
+			...ask !== void 0 ? { ask } : {},
+			...volume !== void 0 ? { volume } : {},
+			...prevClose !== void 0 ? { prevClose } : {},
+			...changePercent !== void 0 ? { changePercent } : {}
+		};
+	}
+	async getKlines(symbol, interval, limit = 100) {
+		const sym = requireSymbol(symbol);
+		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,
+			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));
+	}
+	/**
+	* 全部可交易现货标的名册（GET /api/v3/exchangeInfo，status=TRADING 过滤，Issue #15）。
+	* 输出 symbol 为规范形（BTCUSDT），name 为 baseAsset/quoteAsset（如 BTC/USDT）。
+	*/
+	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 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;
+			result.push({
+				symbol: item.symbol,
+				...name ? { name } : {}
+			});
+		}
+		return result;
+	}
+	/** 盘口快照：GET /api/v3/depth（limit=20 档；bids 降序 / asks 升序，Binance 原生序）。 */
+	async getOrderbook(symbol) {
+		const sym = normalizeBinanceFuturesSymbol(symbol);
+		return parseDepthBody(await this.#request("/api/v3/depth", {
+			symbol: sym,
+			limit: "20"
+		}), sym);
+	}
+	/** 最近逐笔成交：GET /api/v3/trades（时间升序；isBuyerMaker=true → 主动卖）。 */
+	async getRecentTrades(symbol, limit = 50) {
+		const sym = normalizeBinanceFuturesSymbol(symbol);
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 50, 100));
+		const body = await this.#request("/api/v3/trades", {
+			symbol: sym,
+			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));
+	}
+	/** 未平仓合约量：GET /fapi/v1/openInterest（openInterest 以 base 币计，time=快照 ms）。 */
+	async getFuturesOpenInterest(symbol) {
+		const sym = normalizeBinanceFuturesSymbol(symbol);
+		const body = await this.#request("/fapi/v1/openInterest", { symbol: sym }, this.#fapiBaseUrl);
+		const openInterest = num(body.openInterest);
+		if (openInterest === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance futures openInterest for ${sym}: missing/invalid openInterest`);
+		return {
+			openInterest,
+			time: num(body.time) ?? Date.now()
+		};
+	}
+	/** 最新资金费率：GET /fapi/v1/fundingRate?limit=1（[{ fundingRate, fundingTime }]，费率为小数）。 */
+	async getFuturesFundingRate(symbol) {
+		const sym = normalizeBinanceFuturesSymbol(symbol);
+		const body = await this.#request("/fapi/v1/fundingRate", {
+			symbol: sym,
+			limit: "1"
+		}, this.#fapiBaseUrl);
+		const row = Array.isArray(body) ? body[0] : void 0;
+		const fundingRate = num(row?.fundingRate);
+		if (fundingRate === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance futures fundingRate for ${sym}: missing/invalid fundingRate`);
+		return {
+			fundingRate,
+			fundingTime: num(row?.fundingTime) ?? Date.now()
+		};
+	}
+	/** 多空持仓人数比族：GET /futures/data/{globalLongShortAccountRatio|topLongShortPositionRatio}（period=1h，limit=1）。 */
+	async getFuturesLongShortRatio(kind, symbol) {
+		const sym = normalizeBinanceFuturesSymbol(symbol);
+		const path = kind === "global" ? "/futures/data/globalLongShortAccountRatio" : "/futures/data/topLongShortPositionRatio";
+		const body = await this.#request(path, {
+			symbol: sym,
+			period: "1h",
+			limit: "1"
+		}, this.#fapiBaseUrl);
+		const ratio = num((Array.isArray(body) ? body[0] : void 0)?.longShortRatio);
+		if (ratio === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance futures ${kind} long/short ratio for ${sym}: missing/invalid longShortRatio`);
+		return ratio;
+	}
+	/** 主动买卖量比：GET /futures/data/takerlongshortRatio（period=1h，limit=1，buySellRatio=买/卖）。 */
+	async getFuturesTakerRatio(symbol) {
+		const sym = normalizeBinanceFuturesSymbol(symbol);
+		const body = await this.#request("/futures/data/takerlongshortRatio", {
+			symbol: sym,
+			period: "1h",
+			limit: "1"
+		}, this.#fapiBaseUrl);
+		const ratio = num((Array.isArray(body) ? body[0] : void 0)?.buySellRatio);
+		if (ratio === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance futures taker ratio for ${sym}: missing/invalid buySellRatio`);
+		return ratio;
+	}
+	/**
+	* 标记/指数价格与下期结算：GET /fapi/v1/premiumIndex —— 单端点同时携带
+	* markPrice / indexPrice / lastFundingRate / nextFundingTime
+	* （2026-09-03 真实网络实证，spikes/impl-crypto-derivatives）。
+	*/
+	async getFuturesPremiumIndex(symbol) {
+		const sym = normalizeBinanceFuturesSymbol(symbol);
+		const body = await this.#request("/fapi/v1/premiumIndex", { symbol: sym }, this.#fapiBaseUrl);
+		const time = num(body.time);
+		if (time === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance premiumIndex for ${sym}: missing/invalid time`);
+		const markPrice = num(body.markPrice);
+		const indexPrice = num(body.indexPrice);
+		const lastFundingRate = num(body.lastFundingRate);
+		const nextFundingTime = num(body.nextFundingTime);
+		return {
+			...markPrice !== void 0 ? { markPrice } : {},
+			...indexPrice !== void 0 ? { indexPrice } : {},
+			...lastFundingRate !== void 0 ? { lastFundingRate } : {},
+			...nextFundingTime !== void 0 ? { nextFundingTime } : {},
+			time
+		};
+	}
+	/** 资金费率历史：GET /fapi/v1/fundingRate（时间升序；value 为小数费率）。 */
+	async getFuturesFundingRateHistory(symbol, limit = 30) {
+		const sym = normalizeBinanceFuturesSymbol(symbol);
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 30, 100));
+		const body = await this.#request("/fapi/v1/fundingRate", {
+			symbol: sym,
+			limit: String(capped)
+		}, this.#fapiBaseUrl);
+		if (!Array.isArray(body)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance funding history for ${sym}: unexpected response shape`);
+		const points = [];
+		for (const row of body) {
+			const d = row;
+			const time = num(d.fundingTime);
+			const value = num(d.fundingRate);
+			if (time !== void 0 && value !== void 0) points.push({
+				time,
+				value
+			});
+		}
+		return points;
+	}
+	/**
+	* OI 历史：GET /futures/data/openInterestHist（period=1d；sumOpenInterest 为 base 币数，
+	* 与快照 openInterest 同语义。2026-09-03 真实网络实证）。响应时间升序。
+	*/
+	async getFuturesOpenInterestHistory(symbol, limit = 30) {
+		const sym = normalizeBinanceFuturesSymbol(symbol);
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 30, 30));
+		const body = await this.#request("/futures/data/openInterestHist", {
+			symbol: sym,
+			period: "1d",
+			limit: String(capped)
+		}, this.#fapiBaseUrl);
+		if (!Array.isArray(body)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Binance OI history for ${sym}: unexpected response shape`);
+		const points = [];
+		for (const row of body) {
+			const d = row;
+			const time = num(d.timestamp);
+			const value = num(d.sumOpenInterest);
+			if (time !== void 0 && value !== void 0) points.push({
+				time,
+				value
+			});
+		}
+		return points;
+	}
+};
+//#endregion
+export { BinanceRestClient, INTERVAL_VOCABULARY, TradingServiceError, normalizeBinanceFuturesSymbol };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "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.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json",
+    "./dataplane": {
+      "types": "./lib/dataplane.d.ts",
+      "default": "./lib/dataplane.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@dshtrading/api": "^0.1.0",
+    "@dshtrading/indicators": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-alpha.1",
+    "@deepseek-ai/schemastery": ">=3.18.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.22.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}