orderly-positions-tpsl

用途

本技能面向 Orderly Network 永续合约交易场景，聚焦仓位管理、盈亏跟踪、杠杆设置以及止盈（TP）/止损（SL）订单配置，用于在应用中构建仓位管理界面、实现风险管理、跟踪未实现盈亏与调整杠杆。

使用前提

在 Orderly 上持有未平仓位
理解永续合约
拥有具备读取与交易权限的 API 密钥

主要能力

仓位数据结构

Position 接口包含：symbol（如 "PERP_ETH_USDC"）、position_qty（正数为多头，负数为空头）、average_open_price、mark_price、unrealized_pnl、unrealized_pnl_roi、mmr、imr、notional、leverage、est_liq_price、cost_position、settle_price、unsettled_pnl。

获取仓位（REST API）

获取全部仓位：GET /v1/positions
获取特定 symbol 仓位：GET /v1/position/{symbol}

响应示例见资料，包含 rows 数组，字段含 symbol、position_qty、average_open_price、mark_price、unrealized_pnl、unrealized_pnl_roi、mmr、imr、notional、leverage、est_liq_price。

React SDK: usePositionStream

使用 usePositionStream 实时流式获取仓位，自动更新盈亏。返回 rows、aggregated、totalUnrealizedROI、isLoading。示例中展示了汇总未实现盈亏与 ROI，以及持仓表格（Symbol、Size、Entry Price、Mark Price、Unrealized PnL、Leverage、Liq. Price）。

平仓

部分平仓：使用 usePositionClose，返回 closePosition、isClosing。示例按百分比计算数量并调用 closePosition，方向由持仓正负决定（多头 SELL，空头 BUY）。

市价全平（REST）：POST /v1/order，参数含 symbol、side、order_type: 'MARKET'、order_quantity、reduce_only: true。

杠杆管理

获取当前杠杆：GET /v1/client/leverage?symbol={symbol}，返回 leverage、max_leverage
设置杠杆：POST /v1/client/leverage，Body 含 symbol、leverage
React SDK：useLeverage(symbol) 返回 leverage、maxLeverage、setLeverage、isLoading

止盈/止损订单

订单类型包括 TAKE_PROFIT（价格达到目标时触发）、STOP_LOSS（价格跌破阈值时触发）、TRAILING_STOP（跟随价格的动态止损）。

React SDK 使用 useTPSLOrder(position)，返回 computed 与 setValue、submit、validate、reset。表单字段支持触发价（tp_trigger_price、sl_trigger_price）或偏移百分比（tp_offset_percentage、sl_offset_percentage）。

REST API：POST /v1/algo/order。

TP_SL：algo_type: 'TP_SL'，含 quantity、trigger_price_type: 'MARK_PRICE'，child_orders 中分别定义 TAKE_PROFIT 与 STOP_LOSS
POSITIONAL_TP_SL：仓位级止盈止损，子订单类型为 CLOSE_POSITION
STOP（止损市价）：algo_type: 'STOP'，含 quantity、side、type: 'LIMIT'、trigger_price_type、trigger_price、price

取消止盈止损：

取消单个：DELETE /v1/algo/order?order_id={order_id}&symbol={symbol}
取消某 symbol 全部：DELETE /v1/algo/orders?symbol={symbol}
React SDK：useAlgoOrderStream() 返回 algoOrders、cancelAlgoOrder

仓位历史

GET /v1/position_history?symbol={symbol}&start={timestamp}&end={timestamp}，响应含已平仓位及已实现盈亏。

盈亏计算

多头未实现盈亏：(markPrice - averageOpenPrice) * positionQty
空头未实现盈亏：(averageOpenPrice - markPrice) * Math.abs(positionQty)
ROI：unrealizedPnL / ((averageOpenPrice * Math.abs(positionQty)) / leverage)
多头强平价：averageOpenPrice * (1 - mmr - 1 / leverage)
空头强平价：averageOpenPrice * (1 + mmr + 1 / leverage)

风险指标

GET /v1/positions 响应提供字段：current_margin_ratio_with_orders、free_collateral、initial_margin_ratio、initial_margin_ratio_with_orders、maintenance_margin_ratio、maintenance_margin_ratio_with_orders、margin_ratio、open_margin_ratio、total_collateral_value、total_pnl_24_h。

保证金与抵押品层级

资料说明 Orderly 使用多层风险体系：

抵押因子（代币级）：由 Orderly 风险团队按代币设定，例如 USDC = 1.0、USDT = 0.95；存款时生效，例如 $1000 USDT × 0.95 = $950 有效抵押。查询位置：GET /v1/public/token。
IMR/MMR（仓位级）：IMR 为开仓所需最低抵押，MMR 为维持仓位所需最低抵押；由杠杆决定，10 倍杠杆约对应 10% IMR、约 5% MMR；应用于仓位名义价值。查询位置：仓位对象或 symbol 信息。
账户保证金率（账户级）：margin_ratio = total_collateral / total_notional，接近 MMR 时临近强平。查询位置：GET /v1/client/holding。

资料给出计算示例：存入 $10,000 USDC（抵押因子 1.0），有效抵押 $10,000；以 10 倍杠杆开 $50,000 ETH-PERP，IMR 需 $5,000，MMR 需 $2,500；开仓后已用抵押 $5,000，可用抵押 $5,000，保证金率 20%；当保证金率降至 MMR（5%）即抵押降至 $2,500 或仓位名义增至 $200,000 时发生强平。

常见问题

“仓位将超过最大杠杆”错误：当前名义价值加新杠杆超出限制，需减小仓位或增加抵押。
“止盈止损保证金不足”错误：TP/SL 订单需要可用保证金，需平掉部分仓位或补充抵押。
TP/SL 未触发：检查触发价是否有效、订单是否处于 NEW 状态、市场是否跳空越过触发价。
强平风险：密切监控保证金率、尽早设置止损、关注长期持仓的资金费率。

技能介绍

用途