交易操作

TypeScript SDK 通过 TradeClient 提供全部交易接口。自 v0.3.0 起查询接口均返回强类型数组；v0.4.0 将 8 个查询方法（getOrders / getActiveOrders / getInactiveOrders / getFilledOrders / getOrderTransactions / getPositions / getAssets / getPrimeAssets）改为 Request 对象签名（breaking，所有字段可选，account 留空自动填默认账户），并新增 13 个方法（账户管理 / 资产分析 / 资金调拨 / 外汇下单等）。请求参数在 TS 中使用 camelCase，SDK 会自动剥除服务端 {items: [...]} 外壳。

完整可运行示例：

import {
  createClientConfig,
  HttpClient,
  TradeClient,
  limitOrder,
} from '@tigeropenapi/tigeropen';

async function main() {
  const config = createClientConfig();
  const tc = new TradeClient(new HttpClient(config), config.account);

  // 查询持仓 (v0.4.0: 可传 Request 对象过滤)
  const positions = await tc.getPositions();
  console.log('持仓:', positions.length);

  // 构造限价买单
  const orderReq = limitOrder(config.account, 'AAPL', 'STK', 'BUY', 10, 150.0);
  orderReq.market = 'US';
  orderReq.currency = 'USD';
  orderReq.timeInForce = 'DAY';

  // 预览
  const preview = await tc.previewOrder(orderReq);
  console.log('预览结果:', preview?.isPass, preview?.commission);

  // 下单
  const placed = await tc.placeOrder(orderReq);
  console.log('订单 id:', placed?.id);
}

main().catch(console.error);

Order vs OrderRequest：查询接口返回的是 Order 响应类型（字段更全）；placeOrder / previewOrder / modifyOrder 接受的是 OrderRequest 请求类型。推荐使用 limitOrder / marketOrder / stopOrder / stopLimitOrder / trailOrder 等辅助函数构造请求。

OrderStatus 订单状态 (v0.4.0 对齐 Java)

v0.4.0 将 OrderStatus 枚举与 Java SDK 对齐，共 8 个值，同时实现了数字码到字符串的自动归一：

Breaking：从 Python 派生的 PendingNew / PartiallyFilled 已移除（服务端不返回），新增 PendingSubmit。

获取数字码使用 orderStatusCode(status)：

import { OrderStatus, orderStatusCode } from '@tigeropenapi/tigeropen';

console.log(orderStatusCode(OrderStatus.Filled));          // 6
console.log(orderStatusCode('PendingSubmit'));             // 8

Order.status 在反序列化时如服务端返回整数码会自动映射为上述字符串，因此 OrdersRequest.states 使用字符串数组过滤（如 ['Filled', 'Submitted']）。

合约查询

getContract 查询单个合约

tc.getContract(symbol: string, secType: string): Promise<Contract[]>

说明

查询单个合约的详细信息。

参数

返回

Promise<Contract[]>，每个元素含 symbol、secType、currency、exchange、primaryExchange、localSymbol、name、market、lotSize、contractId、isEtf、marginable、shortable、tickSizes。

示例

const contracts = await tc.getContract('AAPL', 'STK');
console.log(contracts[0]?.primaryExchange);

getContracts 批量查询合约

tc.getContracts(symbols: string[], secType: string): Promise<Contract[]>

说明

批量查询多个合约信息。

参数

返回

Promise<Contract[]>（同 getContract）。

示例

const contracts = await tc.getContracts(['AAPL', 'TSLA', 'MSFT'], 'STK');

getQuoteContract 查询衍生品合约

tc.getQuoteContract(symbol: string, secType: string, expiry: string): Promise<Contract[]>

说明

查询衍生品（期权 / 认股 / 牛熊）合约列表。仅支持 'OPT' / 'WAR' / 'IOPT'。

参数

返回

Promise<Contract[]>。

示例

const cs = await tc.getQuoteContract('AAPL', 'OPT', '20260619');
console.log(`options=${cs.length}`);

订单操作

OrderRequest 订单请求结构

下单 / 预览 / 改单接受的 OrderRequest 对象字段如下；推荐使用辅助函数（limitOrder / marketOrder 等）构造基础结构，再按需补字段：

便捷构造函数

import { marketOrder, limitOrder, stopOrder, stopLimitOrder, trailOrder } from '@tigeropenapi/tigeropen';

const o1 = marketOrder(account, symbol, secType, action, qty);
const o2 = limitOrder(account, symbol, secType, action, qty, price);
const o3 = stopOrder(account, symbol, secType, action, qty, auxPrice);
const o4 = stopLimitOrder(account, symbol, secType, action, qty, limit, aux);
const o5 = trailOrder(account, symbol, secType, action, qty, trailPct);

placeOrder 下单

tc.placeOrder(order: OrderRequest): Promise<PlaceOrderResult | undefined>

说明

提交订单到交易所。

返回

Promise<PlaceOrderResult | undefined>，含 id（全局订单 ID）、order_id（账户级订单 ID，服务端返回 snake_case）、subIds、orders: Order[]。

示例

const order = limitOrder(config.account, 'AAPL', 'STK', 'BUY', 10, 150.0);
order.market = 'US';
order.currency = 'USD';

const placed = await tc.placeOrder(order);
console.log('id:', placed?.id, 'orderId:', (placed as any)?.order_id);

previewOrder 预览订单

tc.previewOrder(order: OrderRequest): Promise<PreviewResult | undefined>

说明

在实际下单前预估费用与保证金影响，不会真正提交。

返回

Promise<PreviewResult | undefined>，含 isPass、commission、commissionCurrency、marginCurrency、initMargin / initMarginBefore、maintMargin / maintMarginBefore、equityWithLoan / equityWithLoanBefore、availableEE、excessLiquidity、overnightLiquidation、message。

示例

const preview = await tc.previewOrder(order);
console.log('可下单:', preview?.isPass, '手续费:', preview?.commission);

modifyOrder 修改订单

tc.modifyOrder(id: number, order: OrderRequest): Promise<OrderIdResult | undefined>

说明

修改已提交但未完全成交的订单。

参数

返回

Promise<OrderIdResult | undefined>（含 id）。

示例

const modReq = { ...order, limitPrice: 148.0 };
const mod = await tc.modifyOrder(12345, modReq);
console.log('改单 id:', mod?.id);

cancelOrder 取消订单

tc.cancelOrder(id: number): Promise<OrderIdResult | undefined>

说明

撤销指定订单。

参数

返回

Promise<OrderIdResult | undefined>。

示例

const canc = await tc.cancelOrder(12345);
console.log('撤单 id:', canc?.id);

订单查询

OrdersRequest 订单查询请求结构

OrdersRequest 是 getOrders / getActiveOrders / getInactiveOrders / getFilledOrders 共用的查询参数，所有字段均可选（account 留空自动填默认账户）。v0.4.0 新增。

getOrders 查询全部订单

tc.getOrders(req?: OrdersRequest): Promise<Order[]>

v0.4.0 Breaking：由无参方法改为接收可选 OrdersRequest。

说明

查询当前账户的全部历史订单。v0.4.0 起可按时间、状态、合约等字段过滤。

参数

见上方 OrdersRequest。

返回

Promise<Order[]>，每条 Order 包含 id、orderId、symbol、secType、action、orderType、status、totalQuantity、filledQuantity、limitPrice、avgFillPrice、timeInForce、outsideRth、openTime、updateTime、canModify、canCancel、isOpen 等。

示例

// 最简调用：查询全部订单
const orders = await tc.getOrders();

// 带过滤条件：近 100 条已成交的美股订单
const filtered = await tc.getOrders({
  market: 'US',
  secType: 'STK',
  states: ['Filled'],
  limit: 100,
  sortBy: 'LATEST_CREATED',
});
for (const o of filtered) {
  console.log(`${o.id} ${o.symbol} ${o.action} status=${o.status}`);
}

getOrder 按 ID 查询单个订单 (v0.4.0 新增)

tc.getOrder(req: GetOrderRequest): Promise<Order | undefined>

说明

根据订单 ID 查询单个订单详情。id（全局订单 ID）与 orderId（账户级订单号）至少传一个。wire 方法 orders（服务端返回单个对象，不是 {items:[]}）。

参数

返回

Promise<Order | undefined>（字段同 getOrders 返回项）。

示例

const o = await tc.getOrder({ id: 123456789 });
console.log(`${o?.id} ${o?.symbol} status=${o?.status} filled=${o?.filledQuantity}/${o?.totalQuantity}`);

getActiveOrders 查询待成交订单

tc.getActiveOrders(req?: OrdersRequest): Promise<Order[]>

v0.4.0 Breaking：由无参方法改为接收可选 OrdersRequest（新增 parentId 过滤附加订单）。

说明

查询当前挂单中（未完全成交）的订单列表。

参数

见 OrdersRequest。

返回

Promise<Order[]>。

示例

// 最简调用
const active = await tc.getActiveOrders();

// 查询某父订单下的子订单
const sub = await tc.getActiveOrders({ parentId: 12345678 });

getInactiveOrders 查询已撤销订单

tc.getInactiveOrders(req?: OrdersRequest): Promise<Order[]>

v0.4.0 Breaking：由无参方法改为接收可选 OrdersRequest。

说明

查询已撤销或已过期的订单列表。

参数

见 OrdersRequest。

返回

Promise<Order[]>。

示例

const inactive = await tc.getInactiveOrders();

const cancelled = await tc.getInactiveOrders({
  states: ['Cancelled'],
  limit: 50,
});

getFilledOrders 查询已成交订单

tc.getFilledOrders(req?: OrdersRequest): Promise<Order[]>

v0.4.0 Breaking：由 (startDateMs, endDateMs) 两个位置参数改为接收 OrdersRequest，时间范围通过 startDate / endDate 字段传入（毫秒时间戳）。

说明

查询已成交订单。

参数

见 OrdersRequest。startDate / endDate 均为毫秒时间戳。

返回

Promise<Order[]>。

示例

// 最简调用：不限时间（由服务端默认时间窗控制）
const filled = await tc.getFilledOrders();

// 带时间过滤：近 30 天已成交订单
const now = Date.now();
const recent = await tc.getFilledOrders({
  startDate: now - 30 * 24 * 3600 * 1000,
  endDate: now,
  limit: 200,
});

getOrderTransactions 查询成交明细

tc.getOrderTransactions(req: OrderTransactionsRequest): Promise<Transaction[]>

v0.4.0 Breaking：由 (orderId, symbol, secType) 三个位置参数改为接收 OrderTransactionsRequest；所有字段变为可选，既可按 orderId 查询指定订单，也可按时间窗 / 合约批量过滤。

说明

查询订单的逐笔成交明细。

参数

返回

Promise<Transaction[]>（含 id / orderId / account / symbol / secType / market / currency / action / price / quantity / amount / commission / transactedAt 等）。

示例

// 查询指定订单成交明细
const txs = await tc.getOrderTransactions({
  orderId: 123456789,
  symbol: 'AAPL',
  secType: 'STK',
});

// 按时间窗查询某合约的全部成交
const now = Date.now();
const batch = await tc.getOrderTransactions({
  symbol: 'AAPL',
  secType: 'STK',
  startDate: now - 7 * 24 * 3600 * 1000,
  endDate: now,
  limit: 100,
});

持仓与资产

getPositions 查询持仓

tc.getPositions(req?: PositionsRequest): Promise<Position[]>

v0.4.0 Breaking：由无参方法改为接收可选 PositionsRequest，支持按 symbol / secType / currency / market / subAccounts 等字段过滤。

说明

查询当前账户的所有持仓。

参数

返回

Promise<Position[]>，每条 Position 含 symbol / secType / market / currency / position / positionQty / salableQty / averageCost / marketValue / realizedPnl / unrealizedPnl / todayPnl / latestPrice / lastClosePrice / identifier / name / multiplier。

示例

// 最简调用
const ps = await tc.getPositions();

// 带过滤：仅查询美股持仓
const us = await tc.getPositions({ market: 'US', secType: 'STK' });
for (const p of us) {
  console.log(`${p.symbol} qty=${p.positionQty} avgCost=${p.averageCost} pnl=${p.unrealizedPnl}`);
}

getAssets 查询资产

tc.getAssets(req?: AssetsRequest): Promise<Asset[]>

v0.4.0 Breaking：由无参方法改为接收可选 AssetsRequest。

说明

查询账户资产概览（含各子账户分段数据）。

参数

返回

Promise<Asset[]>，每条 Asset 含 account / capability / currency / buyingPower / cashValue / netLiquidation / realizedPnL / unrealizedPnL，以及 segments: AssetSegment[]（每段含 category / title / netLiquidation / cashValue / availableFunds / equityWithLoan / excessLiquidity / initMarginReq / maintMarginReq / grossPositionValue / leverage）。

示例

// 最简调用
const assets = await tc.getAssets();

// 带过滤
const detailed = await tc.getAssets({ segment: true, marketValue: true });
for (const a of detailed) {
  console.log(`account=${a.account} buyingPower=${a.buyingPower} segments=${a.segments?.length}`);
}

getPrimeAssets 查询综合账户资产

tc.getPrimeAssets(req?: AssetsRequest): Promise<PrimeAsset | undefined>

v0.4.0 Breaking：由无参方法改为接收可选 AssetsRequest（与 getAssets 共用请求结构）。

说明

查询综合账户（Prime 账户）的详细资产信息。

参数

见 getAssets 的 AssetsRequest。

返回

Promise<PrimeAsset | undefined>，含 accountId / updateTimestamp，以及 segments: PrimeAssetSegment[]（每段含 capability / category / currency / cashBalance / cashAvailableForTrade / grossPositionValue / equityWithLoan / netLiquidation / initMargin / maintainMargin / overnightMargin / buyingPower / unrealizedPL / realizedPL / currencyAssets）。

示例

const pa = await tc.getPrimeAssets();
console.log(`account=${pa?.accountId} segments=${pa?.segments.length}`);
for (const s of pa?.segments ?? []) {
  console.log(`  [${s.category}] netLiq=${s.netLiquidation} buyingPower=${s.buyingPower}`);
}

账户管理 (v0.4.0 新增)

getManagedAccounts 查询机构子账户列表

tc.getManagedAccounts(req?: ManagedAccountsRequest): Promise<ManagedAccount[]>

说明

查询当前主账户下可管理的机构子账户列表。wire 方法 accounts。

参数

返回

Promise<ManagedAccount[]>（account / accountType / capability / status）。

示例

const subs = await tc.getManagedAccounts();
for (const s of subs) {
  console.log(`${s.account} type=${s.accountType} capability=${s.capability} status=${s.status}`);
}

getDerivativeContracts 查询衍生品合约

tc.getDerivativeContracts(req: DerivativeContractsRequest): Promise<Contract[]>

说明

按 symbols + 类型批量查询衍生品合约信息（期权 / 认股 / 牛熊）。wire 方法 quote_contract（与 getQuoteContract 共用，但接收结构化请求）。

参数

返回

Promise<Contract[]>（字段同 getContract）。

示例

const cs = await tc.getDerivativeContracts({
  symbols: ['AAPL', 'TSLA'],
  secType: 'OPT',
  expiry: '20260619',
});
console.log(`contracts=${cs.length}`);

资产分析 (v0.4.0 新增)

getAnalyticsAsset 按日资产分析

tc.getAnalyticsAsset(req: AnalyticsAssetRequest): Promise<AnalyticsAsset[]>

说明

按日返回账户持仓价值、现金余额、盈亏与净值指数。wire 方法 analytics_asset。

参数

返回

Promise<AnalyticsAsset[]>（date / holdingValue / cashBalance / pnl / pnlRate / netValueIndex / currency / segType）。

示例

const rows = await tc.getAnalyticsAsset({
  startDate: '2025-01-01',
  endDate: '2025-12-31',
});
for (const r of rows) {
  console.log(`${r.date} holding=${r.holdingValue} pnl=${r.pnl} nav=${r.netValueIndex}`);
}

getAggregateAssets 综合账户资产汇总

tc.getAggregateAssets(req?: AggregateAssetsRequest): Promise<AggregateAssets | undefined>

说明

在指定 baseCurrency 视角下汇总综合账户资产（含各币种明细）。wire 方法 aggregate_assets。

⚠️

仅支持综合账户（STANDARD），模拟账户（PAPER）不支持此接口。

参数

返回

Promise<AggregateAssets | undefined>（accountId / netLiquidation / grossPositionValue / cashBalance / baseCurrency / currencyAssets: CurrencyAsset[]）。

示例

const agg = await tc.getAggregateAssets({ baseCurrency: 'USD' });
console.log(`netLiq=${agg?.netLiquidation} gross=${agg?.grossPositionValue} currencies=${agg?.currencyAssets.length}`);

getEstimateTradableQuantity 可交易数量估算

tc.getEstimateTradableQuantity(req: EstimateTradableQuantityRequest): Promise<EstimateTradableQuantity | undefined>

说明

根据账户可用资金、保证金、现价估算可下单数量（含现金买入、融资买入、做空、可卖出等上限）。wire 方法 estimate_tradable_quantity。

参数

返回

Promise<EstimateTradableQuantity | undefined>（tradableQuantity / maxCashBuyQuantity / maxMarginBuyQuantity / maxShortSellQuantity / maxPositionSellQty / cashBuyingPower / currency）。

示例

const est = await tc.getEstimateTradableQuantity({
  symbol: 'AAPL',
  secType: 'STK',
  action: 'BUY',
  orderType: 'LMT',
  limitPrice: 150.0,
});
console.log(`tradable=${est?.tradableQuantity} cashBuy=${est?.maxCashBuyQuantity}`);

资金明细与调拨 (v0.4.0 新增)

getFundDetails 资金流水明细

tc.getFundDetails(req: FundDetailsRequest): Promise<FundDetails[]>

说明

按时间窗查询账户资金流水（入金 / 出金 / 费用 / 利息 / 分红等）。wire 方法 fund_details。

⚠️

仅支持综合账户（STANDARD），模拟账户（PAPER）不支持此接口。

参数

返回

Promise<FundDetails[]>（id / account / segType / fundType / currency / amount / balance / occurTime / remark / externalId）。

示例

const now = Date.now();
const rows = await tc.getFundDetails({
  startDate: now - 30 * 24 * 3600 * 1000,
  endDate: now,
  currency: 'USD',
  limit: 100,
});
for (const r of rows) {
  console.log(`${r.occurTime} ${r.fundType} amount=${r.amount} balance=${r.balance}`);
}

getFundingHistory 资金调拨记录

tc.getFundingHistory(req: FundingHistoryRequest): Promise<FundingHistoryItem[]>

说明

查询账户入金 / 出金的调拨记录。wire 方法 transfer_fund。

⚠️

仅支持综合账户（STANDARD），模拟账户（PAPER）不支持此接口。

参数

返回

返回

Promise<FundingHistoryItem[]>

示例

const rows = await tc.getFundingHistory({});
for (const r of rows) {
  console.log(`${r.id} ${r.currency} amount=${r.amount} type=${r.typeDesc} status=${r.status}`);
}

placeForexOrder 外汇下单

tc.placeForexOrder(req: ForexOrderRequest): Promise<ForexOrderResult | undefined>

说明

提交外汇兑换订单（货币之间转换）。wire 方法 place_forex_order。

⚠️

仅支持综合账户（STANDARD），模拟账户（PAPER）不支持此接口。

参数

返回

Promise<ForexOrderResult | undefined>（id / status / sourceCurrency / targetCurrency / sourceAmount / targetAmount / rate / submitTime）。

示例

const res = await tc.placeForexOrder({
  sourceCurrency: 'USD',
  sourceAmount: 10000,
  targetCurrency: 'HKD',
});
console.log(`id=${res?.id} rate=${res?.rate} target=${res?.targetAmount}`);

getSegmentFundAvailable 查询可调拨资金

tc.getSegmentFundAvailable(req: SegmentFundRequest): Promise<SegmentFund[]>

说明

查询子账户之间可调拨的资金上限。wire 方法 segment_fund_available。

⚠️

仅支持综合账户（STANDARD），模拟账户（PAPER）不支持此接口。

参数

返回

Promise<SegmentFund[]>（fromSegment / toSegment / currency / availableAmt）。

示例

const avail = await tc.getSegmentFundAvailable({
  fromSegment: 'S',
  toSegment: 'C',
  currency: 'USD',
});
for (const a of avail) {
  console.log(`${a.fromSegment}->${a.toSegment} ${a.currency} available=${a.availableAmt}`);
}

getSegmentFundHistory 子账户调拨历史

tc.getSegmentFundHistory(req: SegmentFundRequest): Promise<SegmentFundHistoryItem[]>

说明

查询子账户资金调拨的历史记录。wire 方法 segment_fund_history。

⚠️

仅支持综合账户（STANDARD），模拟账户（PAPER）不支持此接口。

参数

同 SegmentFundRequest（常用 limit 限定返回条数）。

返回

Promise<SegmentFundHistoryItem[]>（id / fromSegment / toSegment / currency / amount / status / submitTime / updateTime）。

示例

const history = await tc.getSegmentFundHistory({ limit: 50 });
for (const h of history) {
  console.log(`${h.id} ${h.fromSegment}->${h.toSegment} ${h.currency} amount=${h.amount} status=${h.status}`);
}

transferSegmentFund 子账户资金调拨

tc.transferSegmentFund(req: SegmentFundRequest): Promise<SegmentFund | undefined>

说明

在子账户（分段）之间提交资金调拨申请。wire 方法 transfer_segment_fund。

⚠️

仅支持综合账户（STANDARD），模拟账户（PAPER）不支持此接口。

参数

返回

Promise<SegmentFund | undefined>（含 id / status / submitTime）。

示例

const res = await tc.transferSegmentFund({
  fromSegment: 'S',
  toSegment: 'C',
  currency: 'USD',
  amount: 1000,
});
console.log(`transferId=${res?.id} status=${res?.status}`);

cancelSegmentFund 撤销调拨申请

tc.cancelSegmentFund(req: SegmentFundRequest): Promise<SegmentFund | undefined>

说明

撤销尚未执行的子账户调拨申请。wire 方法 cancel_segment_fund。

⚠️

仅支持综合账户（STANDARD），模拟账户（PAPER）不支持此接口。

参数

返回

Promise<SegmentFund | undefined>。

示例

const res = await tc.cancelSegmentFund({ id: 'TX123456' });
console.log(`cancelled id=${res?.id} status=${res?.status}`);

通用方法

当 SDK 尚未封装某个 API 时，可通过 HttpClient 直接调用底层接口：

import {
  createClientConfig,
  HttpClient,
  createApiRequest,
} from '@tigeropenapi/tigeropen';

const config = createClientConfig();
const httpClient = new HttpClient(config);

const request = createApiRequest('market_state', { market: 'US' });
const resp = await httpClient.executeRequest(request);
console.log('原始响应:', resp.data);