@tigeropenapi/tigeropen 0.5.4 → 0.5.5

package/README.md

@@ -486,8 +486,61 @@ const chain = await qc.optionChain('AAPL', '2024-01-19');
 
 // 期货交易所
 const exchanges = await qc.futureExchange();
+
+// 逐笔成交
+const ticks = await qc.getTradeTick({ symbols: ['AAPL'] });
+// ticks[0].items[i].partCode  — 交易所短名，如 "NYSE"、"NSDQ"
+// ticks[0].items[i].partName  — 交易所全名，如 "New York Stock Exchange, LLC (NYSE)"
+// ticks[0].items[i].cond      — 已转换的成交条件，如 "US_REGULAR_SALE"，参见下方说明
 ```
 
+### 逐笔成交 `cond` 字段说明
+
+`trade_tick` 接口和 push 层返回的 `cond` 字段已由 SDK 转换为可读字符串，含义如下：
+
+**美股（US）**
+
+| 字符 | 含义 |
+|------|------|
+| ` `（空格）| 常规交易（Regular Sale） |
+| `B` | 批量交易（Bunched Trade） |
+| `C` | 现金交易（Cash Trade） |
+| `F` | 跨市场交易（Intermarket Sweep） |
+| `G` | 批量卖出（Bunched Sold Trade） |
+| `H` | 离价交易（Price Variation Trade） |
+| `I` | 碎股交易（Odd Lot Trade） |
+| `K` | 纽交所第 127/155 条交易 |
+| `L` | 延迟交易（Sold Last） |
+| `M` | 中央收市价（Market Center Close Price） |
+| `N` | 隔日交易（Next Day Trade） |
+| `O` | 中央开盘价交易（Market Center Opening Trade） |
+| `P` | 前参考价（Prior Reference Price） |
+| `Q` | 中央开盘价（Market Center Open Price） |
+| `R` | 卖方（Seller） |
+| `T` | 盘前盘后交易（Form T） |
+| `U` | 延长交易时段（Extended Trading Hours） |
+| `V` | 合单交易（Contingent Trade） |
+| `W` | 均价交易（Average Price Trade） |
+| `X` | 跨市场交易（Cross Trade） |
+| `Z` | 场外售出（Sold Out of Sequence） |
+| `4` | 衍生工具定价（Derivatively Priced） |
+| `7` | 合单交易（Qualified Contingent Trade） |
+
+**港股（HK）**
+
+| 字符 | 含义 |
+|------|------|
+| ` `（空格）| 自动对盘（Automatch Normal） |
+| `D` | 碎股交易（Odd Lot Trade） |
+| `U` | 竞价交易（Auction Trade） |
+| `*` | 场外交易（Overseas Trade） |
+| `P` | 开市前成交（Late Trade Off Exchange） |
+| `M` | 非自动对盘（Non-Direct Off Exchange Trade） |
+| `X` | 同券商自动对盘（Direct Off Exchange Trade） |
+| `Y` | 同券商非自动对盘（Automatic Internalized） |
+
+如上表所示，`cond` 值因市场（美股/港股）不同而有所区别。
+
 ## 交易
 
 ```typescript

package/dist/cjs/push/index.js

@@ -22,6 +22,7 @@ var push_message_1 = require("./push-message");
 Object.defineProperty(exports, "SubjectType", { enumerable: true, get: function () { return push_message_1.SubjectType; } });
 __exportStar(require("./callbacks"), exports);
 __exportStar(require("./varint"), exports);
+__exportStar(require("./tick-util"), exports);
 __exportStar(require("./proto-message"), exports);
 var push_client_1 = require("./push-client");
 Object.defineProperty(exports, "PushClient", { enumerable: true, get: function () { return push_client_1.PushClient; } });

package/dist/cjs/push/push-client.js

@@ -47,6 +47,7 @@ exports.PushClient = exports.ConnectionState = void 0;
 const tls = __importStar(require("tls"));
 const signer_1 = require("../signer/signer");
 const push_message_1 = require("./push-message");
+const tick_util_1 = require("./tick-util");
 const Request_1 = require("./pb/Request");
 const Response_1 = require("./pb/Response");
 const SocketCommon_1 = require("./pb/SocketCommon");
@@ -378,8 +379,10 @@ class PushClient {
                     cb.onDepth?.(pushData.quoteDepthData);
                 break;
             case SocketCommon_1.SocketCommon_DataType.TradeTick:
+                if (pushData.tickData)
+                    cb.onFullTick?.(pushData.tickData);
                 if (pushData.tradeTickData)
-                    cb.onTick?.(pushData.tradeTickData);
+                    cb.onTick?.((0, tick_util_1.convertTradeTick)(pushData.tradeTickData));
                 break;
             case SocketCommon_1.SocketCommon_DataType.Asset:
                 if (pushData.assetData)
@@ -415,8 +418,7 @@ class PushClient {
                     cb.onQuote?.(pushData.quoteData);
                 break;
             default:
-                // FullTick and QuoteBBO use TradeTick/Quote dataType
-                // TickData (fullTick) via tickData field
+                // QuoteBBO and some full-tick payloads reuse an existing dataType.
                 if (pushData.tickData)
                     cb.onFullTick?.(pushData.tickData);
                 break;

package/dist/cjs/push/tick-util.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPartNameByCode = getPartNameByCode;
+exports.getPartShortNameByCode = getPartShortNameByCode;
+exports.getTradeCondByCode = getTradeCondByCode;
+exports.isUsStockSymbol = isUsStockSymbol;
+exports.convertTradeTick = convertTradeTick;
+const PART_CODE_NAME_MAP = {
+    a: 'NYSE American, LLC (NYSE American)',
+    b: 'NASDAQ OMX BX, Inc. (NASDAQ OMX BX)',
+    c: 'NYSE National, Inc. (NYSE National)',
+    d: 'FINRA Alternative Display Facility (ADF)',
+    h: 'MIAX Pearl Exchange, LLC (MIAX)',
+    i: 'International Securities Exchange, LLC (ISE)',
+    j: 'Cboe EDGA Exchange, Inc. (Cboe EDGA)',
+    k: 'Cboe EDGX Exchange, Inc. (Cboe EDGX)',
+    l: 'Long-Term Stock Exchange, Inc. (LTSE)',
+    m: 'NYSE Chicago, Inc. (NYSE Chicago)',
+    n: 'New York Stock Exchange, LLC (NYSE)',
+    p: 'NYSE Arca, Inc. (NYSE Arca)',
+    s: 'Consolidated Tape System (CTS)',
+    t: 'NASDAQ Stock Market, LLC (NASDAQ)',
+    u: 'Members Exchange, LLC (MEMX)',
+    v: "Investors' Exchange, LLC. (IEX)",
+    w: 'CBOE Stock Exchange, Inc. (CBSX)',
+    x: 'NASDAQ OMX PSX, Inc. (NASDAQ OMX PSX)',
+    y: 'Cboe BYX Exchange, Inc. (Cboe BYX)',
+    z: 'Cboe BZX Exchange, Inc. (Cboe BZX)',
+};
+const PART_CODE_SHORT_NAME_MAP = {
+    a: 'AMEX',
+    b: 'BX',
+    c: 'NSX',
+    d: 'ADF',
+    h: 'MIAX',
+    i: 'ISE',
+    j: 'EDGA',
+    k: 'EDGX',
+    l: 'LTSE',
+    m: 'CHO',
+    n: 'NYSE',
+    p: 'ARCA',
+    s: 'CTS',
+    t: 'NSDQ',
+    u: 'MEMX',
+    v: 'IEX',
+    w: 'CBSX',
+    x: 'PSX',
+    y: 'BYX',
+    z: 'BZX',
+};
+const US_TRADE_COND = {
+    ' ': 'US_REGULAR_SALE',
+    B: 'US_BUNCHED_TRADE',
+    C: 'US_CASH_TRADE',
+    F: 'US_INTERMARKET_SWEEP',
+    G: 'US_BUNCHED_SOLD_TRADE',
+    H: 'US_PRICE_VARIATION_TRADE',
+    I: 'US_ODD_LOT_TRADE',
+    K: 'US_RULE_127_OR_155_TRADE',
+    L: 'US_SOLD_LAST',
+    M: 'US_MARKET_CENTER_CLOSE_PRICE',
+    N: 'US_NEXT_DAY_TRADE',
+    O: 'US_MARKET_CENTER_OPENING_TRADE',
+    P: 'US_PRIOR_REFERENCE_PRICE',
+    Q: 'US_MARKET_CENTER_OPEN_PRICE',
+    R: 'US_SELLER',
+    T: 'US_FORM_T',
+    U: 'US_EXTENDED_TRADING_HOURS',
+    V: 'US_CONTINGENT_TRADE',
+    W: 'US_AVERAGE_PRICE_TRADE',
+    X: 'US_CROSS_TRADE',
+    Z: 'US_SOLD_OUT_OF_SEQUENCE',
+    '0': 'US_ODD_LOST_CROSS_TRADE',
+    '4': 'US_DERIVATIVELY_PRICED',
+    '5': 'US_MARKET_CENTER_RE_OPENING_TRADE',
+    '6': 'US_MARKET_CENTER_CLOSING_TRADE',
+    '7': 'US_QUALIFIED_CONTINGENT_TRADE',
+    '9': 'US_CONSOLIDATED_LAST_PRICE_PER_LISTING_PACKET',
+};
+const HK_TRADE_COND = {
+    ' ': 'HK_AUTOMATCH_NORMAL',
+    D: 'HK_ODD_LOT_TRADE',
+    U: 'HK_AUCTION_TRADE',
+    '*': 'HK_OVERSEAS_TRADE',
+    P: 'HK_LATE_TRADE_OFF_EXCHG',
+    M: 'HK_NON_DIRECT_OFF_EXCHG_TRADE',
+    X: 'HK_DIRECT_OFF_EXCHG_TRADE',
+    Y: 'HK_AUTOMATIC_INTERNALIZED',
+};
+/** Returns the full exchange name for a partCode letter, or the raw code if unknown. */
+function getPartNameByCode(code) {
+    if (!code)
+        return code;
+    return PART_CODE_NAME_MAP[code] ?? code;
+}
+/** Returns the short exchange name for a partCode letter, or the raw code if unknown. */
+function getPartShortNameByCode(code) {
+    if (!code)
+        return code;
+    return PART_CODE_SHORT_NAME_MAP[code] ?? code;
+}
+/** Resolves a raw cond character to a readable string. */
+function getTradeCondByCode(isUs, ch) {
+    const map = isUs ? US_TRADE_COND : HK_TRADE_COND;
+    return map[ch] ?? ch;
+}
+const US_SYMBOL_RE = /^[A-Z]+(\.[A-Z0-9]+)?$/;
+/** Reports whether symbol is a US stock (uppercase letters, optional dot suffix). */
+function isUsStockSymbol(symbol) {
+    return US_SYMBOL_RE.test(symbol);
+}
+function isUsSymbol(symbol) {
+    return US_SYMBOL_RE.test(symbol);
+}
+function getTradeCond(isUs, ch) {
+    const map = isUs ? US_TRADE_COND : HK_TRADE_COND;
+    return map[ch] ?? ch;
+}
+/** Decodes a TradeTickData pb message into a PushTradeTick with resolved partCode/partName. */
+function convertTradeTick(src) {
+    if (src.secType === 'FUT')
+        return convertFutureTick(src);
+    return convertStockTick(src);
+}
+function convertStockTick(src) {
+    const isUs = isUsSymbol(src.symbol);
+    const denominator = Math.pow(10, src.priceOffset);
+    const ticks = [];
+    let currentTime = 0;
+    for (let i = 0; i < src.time.length; i++) {
+        currentTime += src.time[i];
+        const condCh = src.cond.length > i ? src.cond[i] : ' ';
+        const rawCode = i < src.partCode.length ? src.partCode[i] : '';
+        ticks.push({
+            sn: src.sn + i,
+            time: currentTime,
+            price: (src.priceBase + src.price[i]) / denominator,
+            volume: src.volume[i],
+            tickType: src.type.length > i ? src.type[i] : '',
+            cond: getTradeCond(isUs, condCh),
+            partCode: getPartShortNameByCode(rawCode),
+            partName: getPartNameByCode(rawCode),
+        });
+    }
+    return { symbol: src.symbol, secType: src.secType, quoteLevel: src.quoteLevel, timestamp: src.timestamp, ticks };
+}
+function convertFutureTick(src) {
+    const denominator = Math.pow(10, src.priceOffset);
+    const ticks = [];
+    let currentTime = 0;
+    let startSn = src.sn;
+    for (let i = 0; i < src.time.length; i++) {
+        currentTime += src.time[i];
+        const curPrice = (src.priceBase + src.price[i]) / denominator;
+        const mv = src.mergedVols[i];
+        for (let j = 0; j < mv.vol.length; j++) {
+            ticks.push({
+                sn: startSn * 10 + j,
+                time: currentTime,
+                price: curPrice,
+                volume: mv.vol[j],
+                tickType: '',
+                cond: '',
+                partCode: '',
+                partName: '',
+            });
+        }
+        startSn++;
+    }
+    return { symbol: src.symbol, secType: src.secType, quoteLevel: '', timestamp: src.timestamp, ticks };
+}

package/dist/cjs/quote/quote-client.js

@@ -46,6 +46,7 @@ const http_client_1 = require("../client/http-client");
 const api_request_1 = require("../client/api-request");
 const api_response_1 = require("../client/api-response");
 const tokenMethods = __importStar(require("../client/token-methods"));
+const tick_util_1 = require("../push/tick-util");
 /**
  * resolveOptionTimezone returns the timezone string to use for expiry conversion.
  * Explicit tz takes precedence; otherwise infer from symbol (.HK suffix → Asia/Hong_Kong, else America/New_York).
@@ -185,12 +186,22 @@ class QuoteClient {
     async getKline(req) {
         return this.callInto('kline', req);
     }
-    async getTimeline(symbols) {
-        return this.callInto('timeline', { symbols });
+    async getTimeline(symbolsOrRequest) {
+        const req = Array.isArray(symbolsOrRequest) ? { symbols: symbolsOrRequest } : symbolsOrRequest;
+        return this.callInto('timeline', req, req.secType === 'CC' ? '3.0' : undefined);
     }
     /** Tick-by-tick trades. wire: trade_tick */
     async getTradeTick(req) {
-        return this.callInto('trade_tick', req);
+        const out = await this.callInto('trade_tick', req);
+        for (const tick of out) {
+            const isUs = (0, tick_util_1.isUsStockSymbol)(tick.symbol);
+            for (const item of tick.items) {
+                if (item.cond && item.cond.length > 0) {
+                    item.cond = (0, tick_util_1.getTradeCondByCode)(isUs, item.cond[0]);
+                }
+            }
+        }
+        return out;
     }
     /** Depth snapshot. wire: quote_depth */
     async getQuoteDepth(req) {
@@ -356,6 +367,7 @@ class QuoteClient {
         while (acc.length < totalSize) {
             const sub = {
                 symbols: req.symbol ? [req.symbol] : undefined,
+                secType: req.secType,
                 period: req.period,
                 right: req.right,
                 beginTime,
@@ -406,7 +418,7 @@ class QuoteClient {
     async getStockIndustry(req) {
         return this.callInto('stock_industry', req);
     }
-    /** Quote permission detail. wire: get_quote_permission */
+    /** Market data permission entries. wire: get_quote_permission */
     async getQuotePermission(req) {
         return this.callInto('get_quote_permission', req);
     }
@@ -417,9 +429,16 @@ class QuoteClient {
     // ==========================================================================
     // Batch 4: option / future extensions
     // ==========================================================================
-    /** Option tick trades. wire: option_trade_tick */
+    /** Option tick trades. wire: option_trade_tick
+     *
+     * Server expects `biz_content` as a top-level JSON array (matches Java's
+     * `BatchApiModel` and Python's `MultipleContractParams.to_openapi_dict`).
+     * We unwrap the request here so the array is emitted directly instead of
+     * `{"contracts": [...]}`. Sending it as an object triggers
+     * `biz param error(failed to parse parameters in 'biz_content')`.
+     */
     async getOptionTradeTicks(req) {
-        return this.callInto('option_trade_tick', req);
+        return this.callInto('option_trade_tick', req.contracts ?? []);
     }
     /** Option intraday timeline. wire: option_timeline */
     async getOptionTimeline(req) {
@@ -458,10 +477,16 @@ class QuoteClient {
         return this.callInto('future_main_contract', req);
     }
     /** Futures K-line. wire: future_kline
-     * beginTime / endTime default to -1 when unset (server requires them present). */
+     * beginTime / endTime default to -1 when unset (server requires them present).
+     * Server expects `contract_codes` (plural) — normalize singular `contractCode`
+     * to the plural form so callers can pass either shape. */
     async getFutureKline(req) {
+        const contractCodes = req.contractCodes
+            ?? (req.contractCode ? [req.contractCode] : undefined);
+        const { contractCode: _drop, ...rest } = req;
         const body = {
-            ...req,
+            ...rest,
+            ...(contractCodes ? { contractCodes } : {}),
             beginTime: req.beginTime ?? -1,
             endTime: req.endTime ?? -1,
         };
@@ -479,8 +504,9 @@ class QuoteClient {
             endTime = -1;
         const acc = [];
         while (acc.length < totalSize) {
+            // Server rejects singular `contract_code` — send the plural form.
             const sub = {
-                contractCode: req.contractCode,
+                contractCodes: req.contractCode ? [req.contractCode] : undefined,
                 period: req.period,
                 beginTime,
                 endTime,
@@ -559,9 +585,30 @@ class QuoteClient {
     async getWarrantFilter(req) {
         return this.callInto('warrant_filter', req);
     }
-    /** Industry list. wire: industry_list */
-    async getIndustryList(req) {
-        return this.callInto('industry_list', req);
+    /** Industry list. wire: industry_list
+     *
+     * `industryLevel` is required by the server — omitting it returns
+     * `industry level error, all supported is: [GSECTOR, GGROUP, GIND, GSUBIND]`.
+     * Defaults to `GGROUP` when unset, matching Python SDK's
+     * `IndustryLevel.GGROUP` default.
+     *
+     * Wire fields differ from other endpoints (see `IndustryItem`): server sends
+     * `nameCN` / `nameEN` / `industryLevel`. This method hydrates the
+     * backwards-compat `name` (from `nameEN || nameCN`) and mirrors
+     * `industryLevel` to `level` so existing callers keep working.
+     */
+    async getIndustryList(req = {}) {
+        const payload = { industryLevel: 'GGROUP', ...req };
+        const items = await this.callInto('industry_list', payload);
+        if (!Array.isArray(items))
+            return [];
+        for (const it of items) {
+            if (it.name === undefined)
+                it.name = it.nameEN || it.nameCN;
+            if (it.level === undefined)
+                it.level = it.industryLevel;
+        }
+        return items;
     }
     /** Stocks inside an industry. wire: industry_stock_list */
     async getIndustryStocks(req) {

package/dist/cjs/trade/trade-client.js

@@ -145,14 +145,54 @@ class TradeClient {
         });
     }
     // === Order operations ===
+    /**
+     * Prepare an order request for the wire.
+     *
+     * The gateway expects `algo_params` as a `[{tag, value}, ...]` array
+     * (matching the Python SDK's AlgoParams.to_dict serialization), not the
+     * plain object shape that reads naturally in TypeScript. This helper
+     * normalizes the object form into the array form on outbound payloads
+     * so callers can pass the natural object and TWAP/VWAP orders work end
+     * to end without wire-format workarounds.
+     *
+     * Fields with undefined/null values are dropped; empty algoParams
+     * becomes an empty array rather than being stripped, matching the
+     * Python SDK behavior when the user passes an empty AlgoParams().
+     */
+    marshalOrderForWire(order) {
+        const { algoParams, ...rest } = order;
+        const withAccount = { ...rest, account: this.account };
+        if (algoParams === undefined)
+            return withAccount;
+        // Already a tag/value array (advanced callers who want raw control)
+        if (Array.isArray(algoParams)) {
+            withAccount.algoParams = algoParams;
+            return withAccount;
+        }
+        // Object shape → tag/value array.
+        // Keys are converted to snake_case explicitly here (e.g. `startTime` →
+        // `start_time`) so they land correctly in the `tag` string that the
+        // gateway reads. `keysToSnakeCase` only rewrites object *keys*, not
+        // string *values*, so `tag` would be left camelCase if we didn't do
+        // this conversion ourselves.
+        const tagValues = [];
+        for (const [key, value] of Object.entries(algoParams)) {
+            if (value === undefined || value === null)
+                continue;
+            const snakeKey = key.replace(/[A-Z]/g, (c) => '_' + c.toLowerCase());
+            tagValues.push({ tag: snakeKey, value });
+        }
+        withAccount.algoParams = tagValues;
+        return withAccount;
+    }
     async placeOrder(order) {
-        return this.callInto('place_order', { ...order, account: this.account });
+        return this.callInto('place_order', this.marshalOrderForWire(order));
     }
     async previewOrder(order) {
-        return this.callInto('preview_order', { ...order, account: this.account });
+        return this.callInto('preview_order', this.marshalOrderForWire(order));
     }
     async modifyOrder(id, order) {
-        return this.callInto('modify_order', { ...order, account: this.account, id });
+        return this.callInto('modify_order', { ...this.marshalOrderForWire(order), id });
     }
     async cancelOrder(id, secretKey) {
         const params = { account: this.account, id };

package/dist/esm/push/index.js

@@ -4,5 +4,6 @@
 export { SubjectType } from './push-message.js';
 export * from './callbacks.js';
 export * from './varint.js';
+export * from './tick-util.js';
 export * from './proto-message.js';
 export { PushClient, ConnectionState } from './push-client.js';

package/dist/esm/push/push-client.js

@@ -11,6 +11,7 @@
 import * as tls from 'tls';
 import { signWithRSA } from '../signer/signer.js';
 import { SubjectType } from './push-message.js';
+import { convertTradeTick } from './tick-util.js';
 import { Request } from './pb/Request.js';
 import { Response } from './pb/Response.js';
 import { SocketCommon_Command, SocketCommon_DataType } from './pb/SocketCommon.js';
@@ -342,8 +343,10 @@ export class PushClient {
                     cb.onDepth?.(pushData.quoteDepthData);
                 break;
             case SocketCommon_DataType.TradeTick:
+                if (pushData.tickData)
+                    cb.onFullTick?.(pushData.tickData);
                 if (pushData.tradeTickData)
-                    cb.onTick?.(pushData.tradeTickData);
+                    cb.onTick?.(convertTradeTick(pushData.tradeTickData));
                 break;
             case SocketCommon_DataType.Asset:
                 if (pushData.assetData)
@@ -379,8 +382,7 @@ export class PushClient {
                     cb.onQuote?.(pushData.quoteData);
                 break;
             default:
-                // FullTick and QuoteBBO use TradeTick/Quote dataType
-                // TickData (fullTick) via tickData field
+                // QuoteBBO and some full-tick payloads reuse an existing dataType.
                 if (pushData.tickData)
                     cb.onFullTick?.(pushData.tickData);
                 break;

package/dist/esm/push/tick-util.js

@@ -0,0 +1,165 @@
+const PART_CODE_NAME_MAP = {
+    a: 'NYSE American, LLC (NYSE American)',
+    b: 'NASDAQ OMX BX, Inc. (NASDAQ OMX BX)',
+    c: 'NYSE National, Inc. (NYSE National)',
+    d: 'FINRA Alternative Display Facility (ADF)',
+    h: 'MIAX Pearl Exchange, LLC (MIAX)',
+    i: 'International Securities Exchange, LLC (ISE)',
+    j: 'Cboe EDGA Exchange, Inc. (Cboe EDGA)',
+    k: 'Cboe EDGX Exchange, Inc. (Cboe EDGX)',
+    l: 'Long-Term Stock Exchange, Inc. (LTSE)',
+    m: 'NYSE Chicago, Inc. (NYSE Chicago)',
+    n: 'New York Stock Exchange, LLC (NYSE)',
+    p: 'NYSE Arca, Inc. (NYSE Arca)',
+    s: 'Consolidated Tape System (CTS)',
+    t: 'NASDAQ Stock Market, LLC (NASDAQ)',
+    u: 'Members Exchange, LLC (MEMX)',
+    v: "Investors' Exchange, LLC. (IEX)",
+    w: 'CBOE Stock Exchange, Inc. (CBSX)',
+    x: 'NASDAQ OMX PSX, Inc. (NASDAQ OMX PSX)',
+    y: 'Cboe BYX Exchange, Inc. (Cboe BYX)',
+    z: 'Cboe BZX Exchange, Inc. (Cboe BZX)',
+};
+const PART_CODE_SHORT_NAME_MAP = {
+    a: 'AMEX',
+    b: 'BX',
+    c: 'NSX',
+    d: 'ADF',
+    h: 'MIAX',
+    i: 'ISE',
+    j: 'EDGA',
+    k: 'EDGX',
+    l: 'LTSE',
+    m: 'CHO',
+    n: 'NYSE',
+    p: 'ARCA',
+    s: 'CTS',
+    t: 'NSDQ',
+    u: 'MEMX',
+    v: 'IEX',
+    w: 'CBSX',
+    x: 'PSX',
+    y: 'BYX',
+    z: 'BZX',
+};
+const US_TRADE_COND = {
+    ' ': 'US_REGULAR_SALE',
+    B: 'US_BUNCHED_TRADE',
+    C: 'US_CASH_TRADE',
+    F: 'US_INTERMARKET_SWEEP',
+    G: 'US_BUNCHED_SOLD_TRADE',
+    H: 'US_PRICE_VARIATION_TRADE',
+    I: 'US_ODD_LOT_TRADE',
+    K: 'US_RULE_127_OR_155_TRADE',
+    L: 'US_SOLD_LAST',
+    M: 'US_MARKET_CENTER_CLOSE_PRICE',
+    N: 'US_NEXT_DAY_TRADE',
+    O: 'US_MARKET_CENTER_OPENING_TRADE',
+    P: 'US_PRIOR_REFERENCE_PRICE',
+    Q: 'US_MARKET_CENTER_OPEN_PRICE',
+    R: 'US_SELLER',
+    T: 'US_FORM_T',
+    U: 'US_EXTENDED_TRADING_HOURS',
+    V: 'US_CONTINGENT_TRADE',
+    W: 'US_AVERAGE_PRICE_TRADE',
+    X: 'US_CROSS_TRADE',
+    Z: 'US_SOLD_OUT_OF_SEQUENCE',
+    '0': 'US_ODD_LOST_CROSS_TRADE',
+    '4': 'US_DERIVATIVELY_PRICED',
+    '5': 'US_MARKET_CENTER_RE_OPENING_TRADE',
+    '6': 'US_MARKET_CENTER_CLOSING_TRADE',
+    '7': 'US_QUALIFIED_CONTINGENT_TRADE',
+    '9': 'US_CONSOLIDATED_LAST_PRICE_PER_LISTING_PACKET',
+};
+const HK_TRADE_COND = {
+    ' ': 'HK_AUTOMATCH_NORMAL',
+    D: 'HK_ODD_LOT_TRADE',
+    U: 'HK_AUCTION_TRADE',
+    '*': 'HK_OVERSEAS_TRADE',
+    P: 'HK_LATE_TRADE_OFF_EXCHG',
+    M: 'HK_NON_DIRECT_OFF_EXCHG_TRADE',
+    X: 'HK_DIRECT_OFF_EXCHG_TRADE',
+    Y: 'HK_AUTOMATIC_INTERNALIZED',
+};
+/** Returns the full exchange name for a partCode letter, or the raw code if unknown. */
+export function getPartNameByCode(code) {
+    if (!code)
+        return code;
+    return PART_CODE_NAME_MAP[code] ?? code;
+}
+/** Returns the short exchange name for a partCode letter, or the raw code if unknown. */
+export function getPartShortNameByCode(code) {
+    if (!code)
+        return code;
+    return PART_CODE_SHORT_NAME_MAP[code] ?? code;
+}
+/** Resolves a raw cond character to a readable string. */
+export function getTradeCondByCode(isUs, ch) {
+    const map = isUs ? US_TRADE_COND : HK_TRADE_COND;
+    return map[ch] ?? ch;
+}
+const US_SYMBOL_RE = /^[A-Z]+(\.[A-Z0-9]+)?$/;
+/** Reports whether symbol is a US stock (uppercase letters, optional dot suffix). */
+export function isUsStockSymbol(symbol) {
+    return US_SYMBOL_RE.test(symbol);
+}
+function isUsSymbol(symbol) {
+    return US_SYMBOL_RE.test(symbol);
+}
+function getTradeCond(isUs, ch) {
+    const map = isUs ? US_TRADE_COND : HK_TRADE_COND;
+    return map[ch] ?? ch;
+}
+/** Decodes a TradeTickData pb message into a PushTradeTick with resolved partCode/partName. */
+export function convertTradeTick(src) {
+    if (src.secType === 'FUT')
+        return convertFutureTick(src);
+    return convertStockTick(src);
+}
+function convertStockTick(src) {
+    const isUs = isUsSymbol(src.symbol);
+    const denominator = Math.pow(10, src.priceOffset);
+    const ticks = [];
+    let currentTime = 0;
+    for (let i = 0; i < src.time.length; i++) {
+        currentTime += src.time[i];
+        const condCh = src.cond.length > i ? src.cond[i] : ' ';
+        const rawCode = i < src.partCode.length ? src.partCode[i] : '';
+        ticks.push({
+            sn: src.sn + i,
+            time: currentTime,
+            price: (src.priceBase + src.price[i]) / denominator,
+            volume: src.volume[i],
+            tickType: src.type.length > i ? src.type[i] : '',
+            cond: getTradeCond(isUs, condCh),
+            partCode: getPartShortNameByCode(rawCode),
+            partName: getPartNameByCode(rawCode),
+        });
+    }
+    return { symbol: src.symbol, secType: src.secType, quoteLevel: src.quoteLevel, timestamp: src.timestamp, ticks };
+}
+function convertFutureTick(src) {
+    const denominator = Math.pow(10, src.priceOffset);
+    const ticks = [];
+    let currentTime = 0;
+    let startSn = src.sn;
+    for (let i = 0; i < src.time.length; i++) {
+        currentTime += src.time[i];
+        const curPrice = (src.priceBase + src.price[i]) / denominator;
+        const mv = src.mergedVols[i];
+        for (let j = 0; j < mv.vol.length; j++) {
+            ticks.push({
+                sn: startSn * 10 + j,
+                time: currentTime,
+                price: curPrice,
+                volume: mv.vol[j],
+                tickType: '',
+                cond: '',
+                partCode: '',
+                partName: '',
+            });
+        }
+        startSn++;
+    }
+    return { symbol: src.symbol, secType: src.secType, quoteLevel: '', timestamp: src.timestamp, ticks };
+}