@dshtrading/connector-bybit 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/README.md

@@ -0,0 +1,34 @@
+# @dshtrading/connector-template
+
+**本包是脚手架源，不是可安装的连接器**：不入任何 bundle 依赖，仅在 `pnpm -r build/test`
+基线内保证可编译、冒烟测试绿。真实接入用生成器：
+
+```sh
+node scripts/new-connector.mjs --slug bybit --title Bybit --market crypto
+```
+
+生成后按 [docs/connector-playbook.md](../../docs/connector-playbook.md) 的填写顺序
+（src/rest.ts 头部清单 7 项）实现 TODO。每个 TODO 的参照段都在 connector-okx
+（packages/connector-okx/），它是本仓第一个真实 TradeService 连接器。
+
+## 结构
+
+- `src/rest.ts` —— 错误载体（TradingServiceError）+ 通用请求管线（超时/错误映射/
+  模拟盘头/注入 fetch）直接可用；签名与端点 TODO。
+- `src/index.ts` —— Config（enabled/env/dryRun/liveTrading + 三 ref 凭证组）、
+  闸门三态判定、凭证解析（BYOK + 环境变量回落）、MarketDataService/TradeService 骨架、
+  7 个市场前缀工具注册（duplicate-safe）、apply（enabled=false 静默退出）。
+- `test/template.test.ts` —— 结构冒烟 7 用例。
+
+## Token
+
+`bybit`（slug）/ `Bybit`（title）/ `BYBIT`（ref 前缀）/
+`crypto`（工具前缀）/ `Crypto`（服务键 infix）。token 未展开也可编译；
+生成器保证全部替换。
+
+## 注意（勿改的坑）
+
+- 服务类用 TS 编译期 `private`（禁 ECMAScript `#`，realm 代理会炸）。
+- 工具名 = 市场前缀 + 语义词（不带交易所名）——base 闸门正则只认市场前缀。
+- 行 id = `dsh-trading-<market>-connector-<slug>`，全仓唯一（insert-only 铁律 #1）。
+- 凭证只进 ref，绝不内置/落日志（铁律 #3/#5）。

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,44 @@
+import { BybitMarketDataService, BybitTradeService, TRADING_CRYPTO_MARKET_DATA_KEY, TRADING_CRYPTO_TRADE_KEY } from "./index.js";
+//#region src/dataplane.ts
+const inject = [];
+function resolveMarketDataRegistry(ctx) {
+	const candidate = ctx.get?.("tradingMarketDataRegistry", false);
+	return candidate !== void 0 ? candidate : void 0;
+}
+function resolveTradeRegistry(ctx) {
+	const candidate = ctx.get?.("tradingTradeRegistry", false);
+	return candidate !== void 0 ? candidate : void 0;
+}
+const ROUTER_PROVIDER = "bybit";
+const MARKET = "crypto";
+function apply(ctx, config) {
+	if (!config.enabled) return;
+	const apiKey = process.env[config.apiKeyRef];
+	const apiSecret = process.env[config.secretRef];
+	const registry = resolveMarketDataRegistry(ctx);
+	if (registry === void 0) {
+		new BybitMarketDataService(ctx, {
+			apiKey,
+			apiSecret
+		});
+		return;
+	}
+	const inner = ctx.isolate(TRADING_CRYPTO_MARKET_DATA_KEY);
+	const service = new BybitMarketDataService(inner, {
+		apiKey,
+		apiSecret
+	});
+	ctx.effect(() => registry.register(MARKET, ROUTER_PROVIDER, service));
+	const tradeRegistry = resolveTradeRegistry(ctx);
+	if (tradeRegistry !== void 0) {
+		const tradeInner = ctx.isolate(TRADING_CRYPTO_TRADE_KEY);
+		const trade = new BybitTradeService(tradeInner, {
+			apiKey,
+			apiSecret,
+			config
+		});
+		ctx.effect(() => tradeRegistry.register(MARKET, ROUTER_PROVIDER, trade));
+	}
+}
+//#endregion
+export { apply, inject };

package/lib/index.d.ts

@@ -0,0 +1,64 @@
+import { AccountBalance, BybitRestClient, BybitRestOptions, INTERVAL_VOCABULARY, Interval, Kline, Order, Position, Ticker, TradingServiceError, normalizeCryptoSymbol, parseIntervalMs, toBybitInterval } from "./rest.js";
+import { Context, Service } from "@deepseek-ai/cordis";
+import Schema from "@deepseek-ai/schemastery";
+import { AccountBalance as AccountBalance$1, DerivativesData, DerivativesHistory, Disposable, Interval as Interval$1, Kline as Kline$1, MarketDataService, Order as Order$1, OrderRequest, Orderbook, Position as Position$1, Ticker as Ticker$1, TradeFill, TradeService, TradeTick } from "@dshtrading/api";
+//#region src/index.d.ts
+declare const name = "dsh-trading-crypto-connector-bybit";
+interface Config {
+  enabled: boolean;
+  env: 'demo' | 'live';
+  dryRun: boolean;
+  liveTrading: boolean;
+  apiKeyRef: string;
+  secretRef: string;
+}
+declare const Config: Schema<Config>;
+declare const TRADING_CRYPTO_MARKET_DATA_KEY = "tradingCryptoMarketData";
+declare const TRADING_CRYPTO_TRADE_KEY = "tradingCryptoTrade";
+declare class BybitMarketDataService extends Service implements MarketDataService {
+  private readonly client;
+  constructor(ctx: Context, options?: BybitRestOptions, serviceName?: string);
+  getTicker(symbol: string): Promise<Ticker$1>;
+  getKlines(symbol: string, interval?: Interval$1, limit?: number): Promise<Kline$1[]>;
+  subscribeTicker(symbol: string, cb: (ticker: Ticker$1) => void, options?: {
+    intervalMs?: number;
+  }): Disposable;
+  /** 盘口快照（api 可选契约 getOrderbook，issue #39）：spot orderbook 25 档透传。 */
+  getOrderbook(symbol: string): Promise<Orderbook>;
+  /** 最近逐笔成交（api 可选契约 getRecentTrades，issue #39），时间升序。 */
+  getRecentTrades(symbol: string, limit?: number): Promise<TradeTick[]>;
+  /**
+   * 衍生品指标快照（api 可选契约 getDerivatives，issue #38）：聚合 Bybit v5 线性合约
+   * 公共端点（tickers?category=linear 的 fundingRate/OI + account-ratio 多空比）。
+   * 任一子查询失败只降级该字段（undefined，面板按缺格隐藏）；全部失败才抛结构化错误
+   * （桥层转 ok:false，前端不弹横幅）。输出 symbol 为规范 SWAP 形（BTCUSDT-SWAP）。
+   */
+  getDerivatives(symbol: string): Promise<DerivativesData>;
+  /**
+   * 衍生品历史序列（api 可选契约 getDerivativesHistory，issue #54）：
+   * funding/history + open-interest 双端点聚合并发拉取，任一失败只降级该序列
+   * （字段缺省 → 对应趋势卡隐藏），全部失败才抛结构化错误。
+   */
+  getDerivativesHistory(symbol: string): Promise<DerivativesHistory>;
+}
+declare class BybitTradeService extends Service implements TradeService {
+  private readonly client;
+  /** 插件配置（服务缝闸门 P0：dryRun 强制模拟 / liveTrading 总闸门）。 */
+  private readonly config;
+  constructor(ctx: Context, options: BybitRestOptions & {
+    config: Config;
+  }, serviceName?: string);
+  getBalance(): Promise<AccountBalance$1>;
+  getBalances(): Promise<AccountBalance$1[]>;
+  placeOrder(order: OrderRequest): Promise<Order$1>;
+  cancelOrder(orderId: string, _symbol?: string): Promise<void>;
+  getOrder(symbol: string, id: string): Promise<Order$1>;
+  getPositions(): Promise<Position$1[]>;
+  listOpenOrders(_symbol?: string): Promise<Order$1[]>;
+  listTradeFills(_symbol?: string, _limit?: number): Promise<TradeFill[]>;
+}
+declare const ROUTER_PROVIDER = "bybit";
+declare function routeAllows(ctx: Context, config: Config, market: string): boolean;
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { type AccountBalance, BybitMarketDataService, BybitRestClient, BybitRestOptions, BybitTradeService, Config, INTERVAL_VOCABULARY, type Interval, type Kline, type Order, type Position, ROUTER_PROVIDER, TRADING_CRYPTO_MARKET_DATA_KEY, TRADING_CRYPTO_TRADE_KEY, type Ticker, TradingServiceError, apply, name, normalizeCryptoSymbol, parseIntervalMs, routeAllows, toBybitInterval };

package/lib/index.js

@@ -0,0 +1,240 @@
+import { BybitRestClient, INTERVAL_VOCABULARY, TradingServiceError, normalizeCryptoSymbol, parseIntervalMs, toBybitInterval } from "./rest.js";
+import { Service } from "@deepseek-ai/cordis";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import Schema from "@deepseek-ai/schemastery";
+//#region src/index.ts
+const name = "dsh-trading-crypto-connector-bybit";
+const Config = Schema.object({
+	enabled: Schema.boolean().default(true).description("是否激活 Bybit 连接器"),
+	env: Schema.union(["demo", "live"]).default("demo").description("运行环境"),
+	dryRun: Schema.boolean().default(true).description("默认模拟下单"),
+	liveTrading: Schema.boolean().default(false).description("是否允许实盘交易"),
+	apiKeyRef: Schema.string().default("BYBIT_API_KEY").description("Bybit API Key 环境变量名 (BYOK)"),
+	secretRef: Schema.string().default("BYBIT_SECRET_KEY").description("Bybit Secret Key 环境变量名")
+});
+const TRADING_CRYPTO_MARKET_DATA_KEY = "tradingCryptoMarketData";
+const TRADING_CRYPTO_TRADE_KEY = "tradingCryptoTrade";
+var BybitMarketDataService = class extends Service {
+	client;
+	constructor(ctx, options = {}, serviceName = TRADING_CRYPTO_MARKET_DATA_KEY) {
+		super(ctx, serviceName);
+		this.client = new BybitRestClient(options);
+	}
+	async getTicker(symbol) {
+		return this.client.getTicker(symbol);
+	}
+	async getKlines(symbol, interval = "1d", limit = 100) {
+		return this.client.getKlines(symbol, interval, limit);
+	}
+	subscribeTicker(symbol, cb, options) {
+		const ms = Math.max(options?.intervalMs ?? 5e3, 1e3);
+		const tick = () => {
+			this.getTicker(symbol).then(cb, () => {});
+		};
+		tick();
+		const timer = setInterval(tick, ms);
+		return { dispose: () => clearInterval(timer) };
+	}
+	/** 盘口快照（api 可选契约 getOrderbook，issue #39）：spot orderbook 25 档透传。 */
+	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）：聚合 Bybit v5 线性合约
+	* 公共端点（tickers?category=linear 的 fundingRate/OI + account-ratio 多空比）。
+	* 任一子查询失败只降级该字段（undefined，面板按缺格隐藏）；全部失败才抛结构化错误
+	* （桥层转 ok:false，前端不弹横幅）。输出 symbol 为规范 SWAP 形（BTCUSDT-SWAP）。
+	*/
+	async getDerivatives(symbol) {
+		const sym = normalizeCryptoSymbol(symbol);
+		const unavailable = [];
+		const collect = (label, task) => task.catch((error) => {
+			unavailable.push(`${label}: ${error instanceof Error ? error.message : String(error)}`);
+		});
+		const [ticker, ratio] = await Promise.all([collect("linear-tickers", this.client.getLinearTickerSnapshot(sym)), collect("account-ratio", this.client.getLinearAccountRatio(sym))]);
+		const fundingRate = ticker?.fundingRate;
+		const openInterest = ticker?.openInterest;
+		const openInterestValue = ticker?.openInterestValue;
+		const longShortRatio = ratio !== void 0 && ratio.sellRatio > 0 ? ratio.buyRatio / ratio.sellRatio : void 0;
+		if (fundingRate === void 0 && openInterest === void 0 && openInterestValue === void 0 && longShortRatio === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Bybit derivatives for ${sym}: all sub-queries failed` + (unavailable.length > 0 ? ` (${unavailable.join("; ")})` : ""));
+		return {
+			symbol: `${sym}-SWAP`,
+			source: "bybit",
+			...openInterest !== void 0 ? { openInterest } : {},
+			...openInterestValue !== void 0 ? { openInterestValue } : {},
+			...longShortRatio !== void 0 ? { longShortRatio } : {},
+			...fundingRate !== void 0 ? { fundingRate } : {},
+			...ticker?.nextFundingTime !== void 0 ? { nextFundingTime: ticker.nextFundingTime } : {},
+			...ticker?.markPrice !== void 0 ? { markPrice: ticker.markPrice } : {},
+			...ticker?.indexPrice !== void 0 ? { indexPrice: ticker.indexPrice } : {},
+			timestamp: Date.now()
+		};
+	}
+	/**
+	* 衍生品历史序列（api 可选契约 getDerivativesHistory，issue #54）：
+	* funding/history + open-interest 双端点聚合并发拉取，任一失败只降级该序列
+	* （字段缺省 → 对应趋势卡隐藏），全部失败才抛结构化错误。
+	*/
+	async getDerivativesHistory(symbol) {
+		const sym = normalizeCryptoSymbol(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.getLinearFundingHistory(sym, 30)), collect("oi-history", this.client.getLinearOpenInterestHistory(sym, 30))]);
+		if (fundingRates === void 0 && openInterest === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Bybit derivatives history for ${sym}: all sub-queries failed` + (unavailable.length > 0 ? ` (${unavailable.join("; ")})` : ""));
+		return {
+			symbol: `${sym}-SWAP`,
+			source: "bybit",
+			...fundingRates !== void 0 && fundingRates.length > 0 ? { fundingRates } : {},
+			...openInterest !== void 0 && openInterest.length > 0 ? { openInterest } : {}
+		};
+	}
+};
+var BybitTradeService = class extends Service {
+	client;
+	/** 插件配置（服务缝闸门 P0：dryRun 强制模拟 / liveTrading 总闸门）。 */
+	config;
+	constructor(ctx, options, serviceName = TRADING_CRYPTO_TRADE_KEY) {
+		super(ctx, serviceName);
+		this.client = new BybitRestClient(options);
+		this.config = options.config;
+	}
+	async getBalance() {
+		return this.client.getBalance();
+	}
+	async getBalances() {
+		try {
+			return [await this.client.getBalance()];
+		} catch {
+			return [];
+		}
+	}
+	async placeOrder(order) {
+		const requestedDryRun = order.dryRun ?? true;
+		if (!requestedDryRun && !this.config.liveTrading) throw new TradingServiceError("TRADING_LIVE_TRADING_DISABLED", `Bybit TradeService.placeOrder rejected: the request asks for real execution (dryRun=${String(order.dryRun)}) but liveTrading=false — enable liveTrading explicitly or keep dryRun=true for a simulated fill.`);
+		if (requestedDryRun || this.config.dryRun) return {
+			id: `dry-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+			symbol: order.symbol,
+			side: order.side,
+			type: order.type,
+			status: "filled",
+			...order.price !== void 0 ? { price: order.price } : {},
+			quantity: order.quantity,
+			dryRun: true,
+			timestamp: Date.now()
+		};
+		return this.client.placeOrder(void 0, order);
+	}
+	async cancelOrder(orderId, _symbol) {
+		if (!this.config.liveTrading || this.config.dryRun) throw new TradingServiceError("TRADING_LIVE_TRADING_DISABLED", "Bybit TradeService.cancelOrder rejected at the service seam: cancel is a live action and requires liveTrading=true with dryRun=false.");
+		return this.client.cancelOrder(void 0, orderId);
+	}
+	async getOrder(symbol, id) {
+		return {
+			id,
+			symbol,
+			side: "buy",
+			type: "limit",
+			status: "new",
+			quantity: 0,
+			dryRun: false,
+			timestamp: Date.now()
+		};
+	}
+	async getPositions() {
+		return [];
+	}
+	async listOpenOrders(_symbol) {
+		return [];
+	}
+	async listTradeFills(_symbol, _limit) {
+		return [];
+	}
+};
+const ROUTER_PROVIDER = "bybit";
+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) {
+	if (!config.enabled) return;
+	if (!routeAllows(ctx, config, "crypto")) return;
+	const apiKey = process.env[config.apiKeyRef];
+	const apiSecret = process.env[config.secretRef];
+	const marketData = new BybitMarketDataService(ctx, {
+		apiKey,
+		apiSecret
+	});
+	new BybitTradeService(ctx, {
+		apiKey,
+		apiSecret,
+		config
+	});
+	ctx.inject(["tools"], (ctx) => {
+		const tools = ctx.tools;
+		const register = (t) => {
+			if (tools.get(t.name) === void 0) tools.register(t);
+		};
+		register(defineTool({
+			name: "crypto_get_ticker",
+			description: "Get the latest trade price and quote for a crypto pair via Bybit API.",
+			parameters: { symbol: {
+				type: "string",
+				required: true,
+				description: "Crypto pair symbol, e.g. BTCUSDT"
+			} },
+			output: {
+				schema: { type: "string" },
+				render: (_a, v) => [{
+					type: "text",
+					text: v
+				}]
+			},
+			async execute(args) {
+				return JSON.stringify(await marketData.getTicker(args.symbol));
+			}
+		}));
+		register(defineTool({
+			name: "crypto_get_klines",
+			description: "Get recent public klines for a crypto pair via Bybit API. Supports 1m/5m/15m/30m/1h/4h/1d/1w/1M.",
+			parameters: {
+				symbol: {
+					type: "string",
+					required: true,
+					description: "Crypto pair symbol, e.g. BTCUSDT"
+				},
+				interval: {
+					type: "string",
+					enum: INTERVAL_VOCABULARY,
+					default: "1d",
+					description: "Interval"
+				},
+				limit: {
+					type: "integer",
+					default: 100,
+					description: "Limit"
+				}
+			},
+			output: {
+				schema: { type: "string" },
+				render: (_a, v) => [{
+					type: "text",
+					text: v
+				}]
+			},
+			async execute(args) {
+				const klines = await marketData.getKlines(args.symbol, args.interval ?? "1d", args.limit);
+				return JSON.stringify(klines);
+			}
+		}));
+	});
+}
+//#endregion
+export { BybitMarketDataService, BybitRestClient, BybitTradeService, Config, INTERVAL_VOCABULARY, ROUTER_PROVIDER, TRADING_CRYPTO_MARKET_DATA_KEY, TRADING_CRYPTO_TRADE_KEY, TradingServiceError, apply, name, normalizeCryptoSymbol, parseIntervalMs, routeAllows, toBybitInterval };

package/lib/rest.d.ts

@@ -0,0 +1,70 @@
+import { AccountBalance as AccountBalance$1, DerivativesPoint, Interval as Interval$1, Kline as Kline$1, Order as Order$1, OrderRequest, Orderbook, Position as Position$1, Ticker as Ticker$1, TradeTick, TradingErrorCode } from "@dshtrading/api";
+//#region src/rest.d.ts
+declare class TradingServiceError extends Error {
+  readonly code: TradingErrorCode;
+  constructor(code: TradingErrorCode, message: string, cause?: unknown);
+}
+declare const INTERVAL_VOCABULARY: readonly ["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w", "1M"];
+declare function toBybitInterval(interval: Interval$1): string;
+declare function parseIntervalMs(interval: Interval$1): number;
+declare function normalizeCryptoSymbol(raw: string): string;
+interface BybitRestOptions {
+  baseUrl?: string;
+  apiKey?: string;
+  apiSecret?: string;
+  fetchImpl?: typeof fetch;
+}
+declare class BybitRestClient {
+  #private;
+  readonly baseUrl: string;
+  private readonly apiKey?;
+  private readonly apiSecret?;
+  private readonly fetchImpl;
+  constructor(options?: BybitRestOptions);
+  private requestJson;
+  getTicker(symbol: string): Promise<Ticker$1>;
+  getKlines(symbol: string, interval?: Interval$1, limit?: number): Promise<Kline$1[]>;
+  /**
+   * 线性合约行情行：GET /v5/market/tickers?category=linear —— 单端点同时携带
+   * fundingRate（当前资金费率，小数）、openInterest（base 币计持仓量）、
+   * openInterestValue（USD 计价值）。
+   */
+  getLinearTickerSnapshot(symbol: string): Promise<{
+    symbol: string;
+    fundingRate?: number;
+    openInterest?: number;
+    openInterestValue?: number;
+    nextFundingTime?: number;
+    markPrice?: number;
+    indexPrice?: number;
+  }>;
+  /** 多空账户人数比：GET /v5/market/account-ratio?category=linear（period=1h，limit=1，buyRatio/sellRatio 为账户占比）。 */
+  getLinearAccountRatio(symbol: string): Promise<{
+    buyRatio: number;
+    sellRatio: number;
+  }>;
+  /** 资金费率历史：GET /v5/market/funding/history?category=linear（响应新→旧 → 反转升序）。 */
+  getLinearFundingHistory(symbol: string, limit?: number): Promise<DerivativesPoint[]>;
+  /**
+   * OI 历史：GET /v5/market/open-interest?category=linear&intervalTime=1d
+   * （openInterest 为 base 币数，与快照同语义；响应新→旧 → 反转升序。
+   * 2026-09-03 真实网络实证，spikes/impl-crypto-derivatives）。
+   */
+  getLinearOpenInterestHistory(symbol: string, limit?: number): Promise<DerivativesPoint[]>;
+  /**
+   * 盘口快照：GET /v5/market/orderbook?category=spot（limit=25）。
+   * v5 盘口字段是缩写 `result.b`（bids 降序）/ `result.a`（asks 升序）——不是
+   * bids/asks 全称（2026-09-02 真实响应实证，spikes/impl-orderbook-ticks/bybit-orderbook-raw.json）。
+   */
+  getOrderbook(symbol: string): Promise<Orderbook>;
+  /** 最近逐笔成交：GET /v5/market/recent-trade?category=spot（响应新→旧 → 反转升序）。 */
+  getRecentTrades(symbol: string, limit?: number): Promise<TradeTick[]>;
+  getBalance(): Promise<AccountBalance$1>;
+  placeOrder(_creds: unknown, req: OrderRequest): Promise<Order$1>;
+  cancelOrder(_creds: unknown, orderId: string): Promise<{
+    orderId: string;
+    status: 'canceled';
+  }>;
+}
+//#endregion
+export { type AccountBalance$1 as AccountBalance, BybitRestClient, BybitRestOptions, INTERVAL_VOCABULARY, type Interval$1 as Interval, type Kline$1 as Kline, type Order$1 as Order, type Position$1 as Position, type Ticker$1 as Ticker, TradingServiceError, normalizeCryptoSymbol, parseIntervalMs, toBybitInterval };

package/lib/rest.js

@@ -0,0 +1,278 @@
+//#region src/rest.ts
+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 INTERVAL_VOCABULARY = [
+	"1m",
+	"5m",
+	"15m",
+	"30m",
+	"1h",
+	"4h",
+	"1d",
+	"1w",
+	"1M"
+];
+function toBybitInterval(interval) {
+	switch (interval) {
+		case "1m": return "1";
+		case "5m": return "5";
+		case "15m": return "15";
+		case "30m": return "30";
+		case "1h": return "60";
+		case "4h": return "240";
+		case "1d": return "D";
+		case "1w": return "W";
+		case "1M": return "M";
+	}
+}
+function parseIntervalMs(interval) {
+	switch (interval) {
+		case "1m": return 6e4;
+		case "5m": return 3e5;
+		case "15m": return 9e5;
+		case "30m": return 18e5;
+		case "1h": return 36e5;
+		case "4h": return 144e5;
+		case "1d": return 864e5;
+		case "1w": return 6048e5;
+		case "1M": return 2592e6;
+	}
+}
+function normalizeCryptoSymbol(raw) {
+	const clean = raw.trim().toUpperCase().replace(/-SWAP$/, "").replace(/[-_/]/g, "");
+	if (!clean) throw new TradingServiceError("TRADING_INVALID_ARGUMENT", "Symbol cannot be empty");
+	return clean;
+}
+/** 宽松转 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;
+}
+var BybitRestClient = class {
+	baseUrl;
+	apiKey;
+	apiSecret;
+	fetchImpl;
+	constructor(options = {}) {
+		this.baseUrl = options.baseUrl ?? "https://api.bybit.com";
+		this.apiKey = options.apiKey;
+		this.apiSecret = options.apiSecret;
+		this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+	}
+	async requestJson(path) {
+		const url = `${this.baseUrl}${path}`;
+		try {
+			const res = await this.fetchImpl(url, { headers: { "Accept": "application/json" } });
+			if (!res.ok) throw new TradingServiceError("TRADING_UPSTREAM_ERROR", `Bybit HTTP ${res.status}: ${res.statusText}`);
+			return await res.json();
+		} catch (err) {
+			if (err instanceof TradingServiceError) throw err;
+			throw new TradingServiceError("TRADING_NETWORK", `Bybit network error: ${err instanceof Error ? err.message : String(err)}`, err);
+		}
+	}
+	async getTicker(symbol) {
+		const sym = normalizeCryptoSymbol(symbol);
+		const data = await this.requestJson(`/v5/market/tickers?category=spot&symbol=${sym}`);
+		if (data.retCode !== 0 || !data.result?.list || data.result.list.length === 0) throw new TradingServiceError("TRADING_SYMBOL_NOT_FOUND", `Bybit ticker not found for ${sym}`);
+		const row = data.result.list[0];
+		const price = parseFloat(row.lastPrice);
+		const volume = parseFloat(row.volume24h);
+		const timestamp = row.time ? row.time : Date.now();
+		const prevClose = row.prevPrice24h ? parseFloat(row.prevPrice24h) : void 0;
+		const changePercent = row.price24hPcnt ? parseFloat(row.price24hPcnt) * 100 : void 0;
+		return {
+			symbol: sym,
+			price,
+			volume,
+			timestamp,
+			...prevClose !== void 0 && Number.isFinite(prevClose) ? { prevClose } : {},
+			...changePercent !== void 0 && Number.isFinite(changePercent) ? { changePercent } : {}
+		};
+	}
+	async getKlines(symbol, interval = "1d", limit = 100) {
+		const sym = normalizeCryptoSymbol(symbol);
+		const bybitInt = toBybitInterval(interval);
+		const stepMs = parseIntervalMs(interval);
+		const data = await this.requestJson(`/v5/market/kline?category=spot&symbol=${sym}&interval=${bybitInt}&limit=${limit}`);
+		if (data.retCode !== 0 || !data.result?.list) return [];
+		return [...data.result.list].reverse().map((r) => {
+			const openTime = parseInt(r[0], 10);
+			return {
+				openTime,
+				open: parseFloat(r[1]),
+				high: parseFloat(r[2]),
+				low: parseFloat(r[3]),
+				close: parseFloat(r[4]),
+				volume: parseFloat(r[5]),
+				closeTime: openTime + stepMs - 1
+			};
+		});
+	}
+	/**
+	* 线性合约行情行：GET /v5/market/tickers?category=linear —— 单端点同时携带
+	* fundingRate（当前资金费率，小数）、openInterest（base 币计持仓量）、
+	* openInterestValue（USD 计价值）。
+	*/
+	async getLinearTickerSnapshot(symbol) {
+		const sym = normalizeCryptoSymbol(symbol);
+		const data = await this.requestJson(`/v5/market/tickers?category=linear&symbol=${sym}`);
+		if (data.retCode !== 0 || !data.result?.list || data.result.list.length === 0) throw new TradingServiceError("TRADING_UNSUPPORTED_SYMBOL", `Bybit linear tickers not found for ${sym}`);
+		const row = data.result.list[0];
+		const fundingRate = num(row.fundingRate);
+		const openInterest = num(row.openInterest);
+		const openInterestValue = num(row.openInterestValue);
+		const nextFundingTime = num(row.nextFundingTime);
+		const markPrice = num(row.markPrice);
+		const indexPrice = num(row.indexPrice);
+		return {
+			symbol: typeof row.symbol === "string" && row.symbol ? row.symbol : sym,
+			...fundingRate !== void 0 ? { fundingRate } : {},
+			...openInterest !== void 0 ? { openInterest } : {},
+			...openInterestValue !== void 0 ? { openInterestValue } : {},
+			...nextFundingTime !== void 0 ? { nextFundingTime } : {},
+			...markPrice !== void 0 ? { markPrice } : {},
+			...indexPrice !== void 0 ? { indexPrice } : {}
+		};
+	}
+	/** 多空账户人数比：GET /v5/market/account-ratio?category=linear（period=1h，limit=1，buyRatio/sellRatio 为账户占比）。 */
+	async getLinearAccountRatio(symbol) {
+		const sym = normalizeCryptoSymbol(symbol);
+		const data = await this.requestJson(`/v5/market/account-ratio?category=linear&symbol=${sym}&period=1h&limit=1`);
+		if (data.retCode !== 0 || !data.result?.list || data.result.list.length === 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Bybit account ratio not found for ${sym}`);
+		const row = data.result.list[0];
+		const buyRatio = num(row.buyRatio);
+		const sellRatio = num(row.sellRatio);
+		if (buyRatio === void 0 || sellRatio === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Bybit account ratio for ${sym}: missing/invalid buyRatio/sellRatio`);
+		return {
+			buyRatio,
+			sellRatio
+		};
+	}
+	/** 资金费率历史：GET /v5/market/funding/history?category=linear（响应新→旧 → 反转升序）。 */
+	async getLinearFundingHistory(symbol, limit = 30) {
+		const sym = normalizeCryptoSymbol(symbol);
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 30, 100));
+		const data = await this.requestJson(`/v5/market/funding/history?category=linear&symbol=${sym}&limit=${capped}`);
+		if (data.retCode !== 0 || !Array.isArray(data.result?.list)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Bybit funding history for ${sym}: ${data.retMsg}`);
+		const points = [];
+		for (const row of data.result.list) {
+			const time = num(row.fundingRateTimestamp);
+			const value = num(row.fundingRate);
+			if (time !== void 0 && value !== void 0) points.push({
+				time,
+				value
+			});
+		}
+		return points.reverse();
+	}
+	/**
+	* OI 历史：GET /v5/market/open-interest?category=linear&intervalTime=1d
+	* （openInterest 为 base 币数，与快照同语义；响应新→旧 → 反转升序。
+	* 2026-09-03 真实网络实证，spikes/impl-crypto-derivatives）。
+	*/
+	async getLinearOpenInterestHistory(symbol, limit = 30) {
+		const sym = normalizeCryptoSymbol(symbol);
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 30, 50));
+		const data = await this.requestJson(`/v5/market/open-interest?category=linear&symbol=${sym}&intervalTime=1d&limit=${capped}`);
+		if (data.retCode !== 0 || !Array.isArray(data.result?.list)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Bybit OI history for ${sym}: ${data.retMsg}`);
+		const points = [];
+		for (const row of data.result.list) {
+			const time = num(row.timestamp);
+			const value = num(row.openInterest);
+			if (time !== void 0 && value !== void 0) points.push({
+				time,
+				value
+			});
+		}
+		return points.reverse();
+	}
+	/** orderbook 档位行 [price, size] → OrderbookLevel。 */
+	#parseBookRow(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
+		};
+	}
+	/**
+	* 盘口快照：GET /v5/market/orderbook?category=spot（limit=25）。
+	* v5 盘口字段是缩写 `result.b`（bids 降序）/ `result.a`（asks 升序）——不是
+	* bids/asks 全称（2026-09-02 真实响应实证，spikes/impl-orderbook-ticks/bybit-orderbook-raw.json）。
+	*/
+	async getOrderbook(symbol) {
+		const sym = normalizeCryptoSymbol(symbol);
+		const data = await this.requestJson(`/v5/market/orderbook?category=spot&symbol=${sym}&limit=25`);
+		if (data.retCode !== 0 || !Array.isArray(data.result?.b) || !Array.isArray(data.result?.a)) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Bybit orderbook for ${sym}: unexpected response shape`);
+		return {
+			symbol: sym,
+			bids: data.result.b.map((row) => this.#parseBookRow(row)).filter((l) => l !== void 0),
+			asks: data.result.a.map((row) => this.#parseBookRow(row)).filter((l) => l !== void 0),
+			timestamp: num(data.result.ts) ?? Date.now()
+		};
+	}
+	/** recent-trade 行 → TradeTick（side 即 taker 方向，Bybit 大写词汇；响应新→旧 → 反转升序）。 */
+	#parseTradeRow(row, symbol) {
+		const price = num(row.price);
+		const amount = num(row.size);
+		if (price === void 0 || amount === void 0) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Bybit trades for ${symbol}: malformed trade row`);
+		const rawSide = typeof row.side === "string" ? row.side.toLowerCase() : "";
+		const side = rawSide === "buy" || rawSide === "sell" ? rawSide : "unknown";
+		return {
+			id: String(row.execId ?? ""),
+			symbol,
+			price,
+			amount,
+			side,
+			timestamp: num(row.time) ?? Date.now()
+		};
+	}
+	/** 最近逐笔成交：GET /v5/market/recent-trade?category=spot（响应新→旧 → 反转升序）。 */
+	async getRecentTrades(symbol, limit = 50) {
+		const sym = normalizeCryptoSymbol(symbol);
+		const capped = Math.max(1, Math.min(Math.floor(limit) || 50, 60));
+		const data = await this.requestJson(`/v5/market/recent-trade?category=spot&symbol=${sym}&limit=${capped}`);
+		if (data.retCode !== 0 || !data.result?.list) throw new TradingServiceError("TRADING_EXCHANGE_ERROR", `Bybit trades for ${sym}: unexpected response shape`);
+		const symbolOut = sym;
+		return data.result.list.map((row) => this.#parseTradeRow(row, symbolOut)).reverse();
+	}
+	async getBalance() {
+		return {
+			currency: "USDT",
+			available: 1e5,
+			total: 1e5
+		};
+	}
+	async placeOrder(_creds, req) {
+		const sym = normalizeCryptoSymbol(req.symbol);
+		return {
+			id: `sim-bybit-${Date.now()}`,
+			symbol: sym,
+			side: req.side,
+			type: req.type,
+			status: "filled",
+			quantity: req.quantity,
+			price: req.price ?? 0,
+			dryRun: true,
+			timestamp: Date.now()
+		};
+	}
+	async cancelOrder(_creds, orderId) {
+		return {
+			orderId,
+			status: "canceled"
+		};
+	}
+};
+//#endregion
+export { BybitRestClient, INTERVAL_VOCABULARY, TradingServiceError, normalizeCryptoSymbol, parseIntervalMs, toBybitInterval };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dshtrading/connector-bybit",
+  "description": "【模板】交易所连接器插件脚手架：Bybit（bybit）v2 插件骨架 —— 市场数据服务 + 交易服务 + 三态闸门 + BYOK 凭证 ref。生成器：node scripts/new-connector.mjs --slug <exchange>",
+  "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"
+    },
+    "./dataplane": {
+      "types": "./lib/dataplane.d.ts",
+      "default": "./lib/dataplane.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@dshtrading/api": "^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"
+  }
+}