仓位管理 (Positions)

管理交易仓位，包括查询、开仓、平仓、保证金调整和止盈止损设置。

概述

仓位类型

方向	说明	盈利条件
long（多仓）	买入做多	价格上涨
short（空仓）	卖出做空	价格下跌

仓位状态

状态	说明
open	活跃仓位
closed	已平仓
liquidated	已清算

获取仓位列表

获取当前用户的所有持仓信息。

接口信息

Method: GET
Path: /api/v1/positions
Authentication: 需要 JWT Token

响应示例

{
  "positions": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb",
      "symbol": "BTCUSDT",
      "side": "long",
      "size_in_tokens": "0.1",
      "size_in_usd": "6500.00",
      "entry_price": "65000.00",
      "mark_price": "65500.00",
      "collateral": "650.00",
      "leverage": 10,
      "unrealized_pnl": "50.00",
      "liquidation_price": "60000.00",
      "margin_rate": "0.10",
      "status": "open",
      "created_at": 1704067200000,
      "updated_at": 1704070800000
    }
  ]
}

响应字段说明

字段	类型	描述
id	string	仓位 UUID
user_address	string	用户地址
symbol	string	交易对
side	string	持仓方向（`long`/`short`）
size_in_tokens	string	仓位大小（代币数量，Decimal 字符串）
size_in_usd	string	仓位价值（USD，Decimal 字符串）
entry_price	string	开仓均价（Decimal 字符串）
mark_price	string	当前标记价格（Decimal 字符串）
collateral	string	保证金数量（Decimal 字符串）
leverage	number	杠杆倍数
unrealized_pnl	string	未实现盈亏（Decimal 字符串）
liquidation_price	string	清算价格（Decimal 字符串）
margin_rate	string	保证金率（Decimal 字符串）
status	string	仓位状态
created_at	number	创建时间（毫秒级时间戳）
updated_at	number	更新时间（毫秒级时间戳）

获取单个仓位

查询指定仓位的详细信息。

接口信息

Method: GET
Path: /api/v1/positions/:position_id
Authentication: 需要 JWT Token

路径参数

参数	类型	必须	描述
position_id	string	是	仓位 UUID

响应示例

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb",
  "symbol": "BTCUSDT",
  "side": "long",
  "size_in_tokens": "0.1",
  "size_in_usd": "6500.00",
  "entry_price": "65000.00",
  "mark_price": "65500.00",
  "collateral": "650.00",
  "leverage": 10,
  "unrealized_pnl": "50.00",
  "liquidation_price": "60000.00",
  "margin_rate": "0.10",
  "status": "open",
  "created_at": 1704067200000,
  "updated_at": 1704070800000
}

开仓/增加仓位

通过创建订单来开仓或增加仓位。实际上是创建一个市价或限价订单。

提示

开仓操作通过订单管理 API 实现。创建订单成交后系统会自动创建或增加仓位。

示例：开多仓

// 买入做多
const order = await createOrder({
  symbol: "BTCUSDT",
  side: "buy",
  order_type: "market",
  amount: "0.1",
  leverage: 10,
  signature: signature,
  timestamp: timestamp
});

// 订单成交后会自动创建多仓

示例：开空仓

// 卖出做空
const order = await createOrder({
  symbol: "BTCUSDT",
  side: "sell",
  order_type: "market",
  amount: "0.1",
  leverage: 10,
  signature: signature,
  timestamp: timestamp
});

// 订单成交后会自动创建空仓

平仓/减少仓位

平仓也是通过创建反向订单实现。

示例：平多仓

// 卖出平多
const order = await createOrder({
  symbol: "BTCUSDT",
  side: "sell",  // 反向操作
  order_type: "market",
  amount: "0.1",  // 平仓数量
  leverage: 10,
  signature: signature,
  timestamp: timestamp
});

示例：平空仓

// 买入平空
const order = await createOrder({
  symbol: "BTCUSDT",
  side: "buy",  // 反向操作
  order_type: "market",
  amount: "0.1",
  leverage: 10,
  signature: signature,
  timestamp: timestamp
});

智能保证金

平仓订单享有智能保证金优化，只需支付手续费，无需额外保证金！详见订单管理。

增加保证金

增加仓位的保证金可以降低清算风险。增加保证金后，清算价格会更有利。

接口信息

Method: POST
Path: /api/v1/positions/:position_id/collateral/add
Authentication: 需要 JWT Token
Content-Type: application/json

路径参数

参数	类型	必须	描述
position_id	string	是	仓位 UUID

请求参数

参数	类型	必须	描述
amount	string	是	增加的保证金数量（Decimal 字符串）

请求示例

{
  "amount": "100.00"
}

响应示例

{
  "success": true,
  "message": "保证金已增加",
  "position": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "collateral": "750.00",
    "liquidation_price": "58000.00",
    "margin_rate": "0.12"
  }
}

效果说明

增加保证金后：

✅ 清算价格更远（多仓降低，空仓升高）
✅ 保证金率提高
✅ 降低清算风险

示例：

原保证金: 650 USDT
增加: 100 USDT
新保证金: 750 USDT
清算价格: 60000 → 58000（多仓更安全）

错误响应

HTTP 状态码	错误码	描述
400	INSUFFICIENT_BALANCE	可用余额不足
404	POSITION_NOT_FOUND	仓位不存在
403	POSITION_NOT_OWNED	无权操作此仓位

减少保证金

从仓位中取回部分保证金，提高资金利用率。但要注意清算风险！

接口信息

Method: POST
Path: /api/v1/positions/:position_id/collateral/remove
Authentication: 需要 JWT Token
Content-Type: application/json

路径参数

参数	类型	必须	描述
position_id	string	是	仓位 UUID

请求参数

参数	类型	必须	描述
amount	string	是	减少的保证金数量（Decimal 字符串）

请求示例

{
  "amount": "50.00"
}

响应示例

{
  "success": true,
  "message": "保证金已减少",
  "position": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "collateral": "600.00",
    "liquidation_price": "61000.00",
    "margin_rate": "0.09"
  }
}

风险警告

减少保证金后：

⚠️ 清算价格更近（多仓升高，空仓降低）
⚠️ 保证金率降低
⚠️ 清算风险增加

示例：

原保证金: 650 USDT
减少: 50 USDT
新保证金: 600 USDT
清算价格: 60000 → 61000（多仓更危险！）

清算风险

减少保证金可能导致仓位更容易被清算！系统会验证减少后的保证金是否足够，不足时会拒绝操作。

错误响应

HTTP 状态码	错误码	描述
400	INSUFFICIENT_COLLATERAL	减少后保证金不足
400	LIQUIDATION_RISK	减少后接近清算价格
404	POSITION_NOT_FOUND	仓位不存在
403	POSITION_NOT_OWNED	无权操作此仓位

检查清算状态

查询仓位是否处于清算风险中。

接口信息

Method: GET
Path: /api/v1/positions/:position_id/liquidation
Authentication: 需要 JWT Token

路径参数

参数	类型	必须	描述
position_id	string	是	仓位 UUID

响应示例

{
  "position_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_liquidatable": false,
  "liquidation_price": "60000.00",
  "mark_price": "65500.00",
  "distance_to_liquidation": "5500.00",
  "distance_to_liquidation_percent": "8.40",
  "maintenance_margin": "32.50",
  "margin_ratio": "0.10",
  "health_factor": "2.0"
}

响应字段说明

字段	类型	描述
position_id	string	仓位 UUID
is_liquidatable	boolean	是否可被清算
liquidation_price	string	清算价格（Decimal 字符串）
mark_price	string	当前标记价格
distance_to_liquidation	string	距离清算价格的距离
distance_to_liquidation_percent	string	距离清算价格的百分比
maintenance_margin	string	维持保证金要求
margin_ratio	string	当前保证金率
health_factor	string	健康系数（>1 安全，<1 危险）

健康系数说明

健康系数 = 保证金 / 维持保证金

> 2.0: 非常安全 ✅
1.5 - 2.0: 安全 ✅
1.2 - 1.5: 注意 ⚠️
1.0 - 1.2: 危险 ⚠️
< 1.0: 将被清算 🔴

设置止盈止损

为仓位快速设置止盈和止损价格。这是创建触发订单的便捷方式。

接口信息

Method: POST
Path: /api/v1/positions/:position_id/tp-sl
Authentication: 需要 JWT Token
Content-Type: application/json

路径参数

参数	类型	必须	描述
position_id	string	是	仓位 UUID

请求参数

参数	类型	必须	描述
take_profit_price	string	否	止盈价格（Decimal 字符串）
stop_loss_price	string	否	止损价格（Decimal 字符串）

至少一个参数

take_profit_price 和 stop_loss_price 至少需要提供一个。

请求示例

{
  "take_profit_price": "70000",
  "stop_loss_price": "60000"
}

响应示例

{
  "success": true,
  "data": {
    "position_id": "550e8400-e29b-41d4-a716-446655440000",
    "take_profit_price": "70000",
    "stop_loss_price": "60000",
    "tp_order_id": "660e8400-e29b-41d4-a716-446655440000",
    "sl_order_id": "660e8400-e29b-41d4-a716-446655440001",
    "updated_at": 1704067200000
  }
}

价格验证规则

多仓（Long）

止盈价格 必须 > 当前市场价格
止损价格 必须 < 当前市场价格

止盈 (TP): 70000 ✅
当前价格: 65000
止损 (SL): 60000 ✅

空仓（Short）

止盈价格 必须 < 当前市场价格
止损价格 必须 > 当前市场价格

止损 (SL): 70000 ✅
当前价格: 65000
止盈 (TP): 60000 ✅

查询仓位止盈止损

查询仓位当前设置的止盈止损价格。

接口信息

Method: GET
Path: /api/v1/positions/:position_id/tp-sl
Authentication: 需要 JWT Token

响应示例

{
  "success": true,
  "data": {
    "position_id": "550e8400-e29b-41d4-a716-446655440000",
    "take_profit_price": "70000",
    "stop_loss_price": "60000",
    "tp_order_id": "660e8400-e29b-41d4-a716-446655440000",
    "sl_order_id": "660e8400-e29b-41d4-a716-446655440001",
    "updated_at": 1704067200000
  }
}

盈亏计算

未实现盈亏（浮盈浮亏）

未平仓时的账面盈亏。

多仓

未实现盈亏 = 仓位数量 × (当前价格 - 开仓价格)

示例：

开仓：买入 0.1 BTC @ 65000
当前价格：65500
未实现盈亏 = 0.1 × (65500 - 65000) = +50 USDT

空仓

未实现盈亏 = 仓位数量 × (开仓价格 - 当前价格)

示例：

开仓：卖出 0.1 BTC @ 65000
当前价格：64500
未实现盈亏 = 0.1 × (65000 - 64500) = +50 USDT

清算价格计算

多仓清算价格

清算价格 = 开仓价格 × (1 - 1/杠杆 + 维持保证金率)

示例：

开仓价格：65000
杠杆：10x
维持保证金率：0.5%
清算价格 = 65000 × (1 - 0.1 + 0.005) = 58825

空仓清算价格

清算价格 = 开仓价格 × (1 + 1/杠杆 - 维持保证金率)

示例：

开仓价格：65000
杠杆：10x
维持保证金率：0.5%
清算价格 = 65000 × (1 + 0.1 - 0.005) = 71175

最佳实践

1. 永远设置止损

// ✅ 推荐：开仓后立即设置止损
const position = await getPositions();

if (position.length > 0 && !position[0].stop_loss_price) {
  await fetch(`/api/v1/positions/${position[0].id}/tp-sl`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${token}` },
    body: JSON.stringify({
      stop_loss_price: calculateStopLoss(position[0]),
      take_profit_price: calculateTakeProfit(position[0])
    })
  });
}

2. 监控清算风险

// 定期检查清算状态
setInterval(async () => {
  const positions = await getPositions();
  
  for (const position of positions) {
    const liquidation = await getLiquidationStatus(position.id);
    
    if (liquidation.health_factor < 1.2) {
      // 健康系数低于1.2，增加保证金
      await addCollateral(position.id, "100");
      alert('已自动增加保证金，避免清算风险');
    }
  }
}, 60000);  // 每分钟检查一次

3. 动态调整杠杆

// 盈利时降低杠杆，锁定利润
if (position.unrealized_pnl > 0) {
  // 通过增加保证金来降低有效杠杆
  const additionalCollateral = position.collateral * 0.5;
  await addCollateral(position.id, additionalCollateral);
}

4. 分批平仓

// 在不同价位分批平仓
const position = await getPosition(positionId);
const totalSize = parseFloat(position.size_in_tokens);

// 50% @ 目标价1
await createOrder({
  side: position.side === 'long' ? 'sell' : 'buy',
  amount: (totalSize * 0.5).toString(),
  ...
});

// 30% @ 目标价2
await createOrder({
  side: position.side === 'long' ? 'sell' : 'buy',
  amount: (totalSize * 0.3).toString(),
  ...
});

// 20% @ 目标价3 (剩余)

常见问题

Q: 为什么开仓/平仓要通过订单API？

A: ZTDX 采用订单驱动的仓位管理机制。所有开仓和平仓操作都通过创建订单实现，订单成交后自动更新仓位。这样设计更加灵活，用户可以使用限价单、市价单等多种方式。

Q: 增加保证金会影响盈亏吗？

A: 不会。增加保证金只是降低清算风险，不会改变仓位大小和盈亏计算。但会改变清算价格和保证金率。

Q: 减少保证金有最小限制吗？

A: 是的。系统会确保减少后的保证金仍然满足：

维持保证金要求（通常是仓位价值的 0.5%）
健康系数 > 1.0
距离清算价格足够远

Q: 可以同时持有多个相同交易对的仓位吗？

A: 不可以。相同交易对只能有一个方向的仓位（多仓或空仓）。如果已有多仓，再买入会增加仓位；卖出会减少仓位。

Q: 仓位会自动合并吗？

A: 是的。相同方向的订单成交后会自动合并到现有仓位，使用加权平均价格计算新的开仓均价。

仓位管理 (Positions)

概述​

仓位类型​

仓位状态​

获取仓位列表​

接口信息​

响应示例​

响应字段说明​

获取单个仓位​

接口信息​

路径参数​

响应示例​

开仓/增加仓位​

示例：开多仓​

示例：开空仓​

平仓/减少仓位​

示例：平多仓​

示例：平空仓​

增加保证金​

接口信息​

路径参数​

请求参数​

请求示例​

响应示例​

效果说明​

错误响应​

减少保证金​

接口信息​

路径参数​

请求参数​

请求示例​

响应示例​

风险警告​

错误响应​

检查清算状态​

接口信息​

路径参数​

响应示例​

响应字段说明​

健康系数说明​

设置止盈止损​

接口信息​

路径参数​

请求参数​

请求示例​

响应示例​

价格验证规则​

多仓（Long）​

空仓（Short）​

查询仓位止盈止损​

接口信息​

响应示例​

盈亏计算​

未实现盈亏（浮盈浮亏）​

多仓​

空仓​

清算价格计算​

多仓清算价格​

空仓清算价格​

最佳实践​

1. 永远设置止损​

2. 监控清算风险​

3. 动态调整杠杆​

4. 分批平仓​

常见问题​

Q: 为什么开仓/平仓要通过订单API？​

Q: 增加保证金会影响盈亏吗？​

Q: 减少保证金有最小限制吗？​

Q: 可以同时持有多个相同交易对的仓位吗？​

Q: 仓位会自动合并吗？​

相关文档​

概述

仓位类型

仓位状态

获取仓位列表

接口信息

响应示例

响应字段说明

获取单个仓位

接口信息

路径参数

响应示例

开仓/增加仓位

示例：开多仓

示例：开空仓

平仓/减少仓位

示例：平多仓

示例：平空仓

增加保证金

接口信息

路径参数

请求参数

请求示例

响应示例

效果说明

错误响应

减少保证金

接口信息

路径参数

请求参数

请求示例

响应示例

风险警告

错误响应

检查清算状态

接口信息

路径参数

响应示例

响应字段说明

健康系数说明

设置止盈止损

接口信息

路径参数

请求参数

请求示例

响应示例

价格验证规则

多仓（Long）

空仓（Short）

查询仓位止盈止损

接口信息

响应示例

盈亏计算

未实现盈亏（浮盈浮亏）

多仓

空仓

清算价格计算

多仓清算价格

空仓清算价格

最佳实践

1. 永远设置止损

2. 监控清算风险

3. 动态调整杠杆

4. 分批平仓

常见问题

Q: 为什么开仓/平仓要通过订单API？

Q: 增加保证金会影响盈亏吗？

Q: 减少保证金有最小限制吗？

Q: 可以同时持有多个相同交易对的仓位吗？

Q: 仓位会自动合并吗？

相关文档