触发订单 (Trigger Orders)

触发订单是一种条件订单，当市场价格达到设定的触发价格时，系统会自动创建并执行订单。主要用于止盈（Take Profit）、止损（Stop Loss）和追踪止损（Trailing Stop）。

概述

触发订单类型

类型	英文名称	说明	适用场景
止盈	Take Profit	价格达到目标时平仓获利	锁定利润
止损	Stop Loss	价格达到止损位时平仓止损	控制风险
追踪止损	Trailing Stop	价格回调一定幅度时平仓	保护浮盈

工作原理

1. 用户创建触发订单
   ↓
2. 系统监控市场价格
   ↓
3. 价格达到触发条件
   ↓
4. 自动创建并执行订单
   ↓
5. 触发订单状态更新为 "triggered"

创建触发订单

创建一个新的触发订单。可以设置止盈、止损或追踪止损。

接口信息

Method: POST
Path: /api/v1/trigger-orders
Authentication: 需要 JWT Token
Content-Type: application/json

请求参数

参数	类型	必须	描述
symbol	string	是	交易对（如 `BTCUSDT`）
side	string	是	方向：`buy` 或 `sell`
trigger_type	string	是	触发类型：`stop_loss`、`take_profit`、`trailing_stop`
trigger_price	string	是	触发价格（Decimal 字符串）
order_type	string	是	触发后订单类型：`limit` 或 `market`
order_price	string	否	触发后订单价格（限价单必填）
amount	string	是	数量（Decimal 字符串）
position_id	string	否	关联仓位 ID（可选）
callback_rate	string	否	追踪止损回调比例（如 `"0.01"` 表示 1%）
activate_price	string	否	追踪止损激活价格

认证说明

触发订单不需要 EIP-712 签名，只需要 JWT Token 认证即可。

请求示例

1. 止盈订单（Take Profit）

{
  "symbol": "BTCUSDT",
  "side": "sell",
  "trigger_type": "take_profit",
  "trigger_price": "70000",
  "order_type": "market",
  "amount": "0.1",
  "position_id": "550e8400-e29b-41d4-a716-446655440000"
}

说明：当 BTC 价格达到 70000 时，自动以市价卖出 0.1 BTC

2. 止损订单（Stop Loss）

{
  "symbol": "BTCUSDT",
  "side": "sell",
  "trigger_type": "stop_loss",
  "trigger_price": "60000",
  "order_type": "market",
  "amount": "0.1",
  "position_id": "550e8400-e29b-41d4-a716-446655440000"
}

说明：当 BTC 价格跌至 60000 时，自动以市价卖出 0.1 BTC

3. 追踪止损订单（Trailing Stop）

{
  "symbol": "BTCUSDT",
  "side": "sell",
  "trigger_type": "trailing_stop",
  "trigger_price": "0",
  "order_type": "market",
  "amount": "0.1",
  "callback_rate": "0.02",
  "activate_price": "68000",
  "position_id": "550e8400-e29b-41d4-a716-446655440000"
}

说明：

当价格达到 68000 时激活
然后跟踪最高价
当价格从最高点回落 2% 时触发卖出

响应示例

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "user_address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb",
    "symbol": "BTCUSDT",
    "side": "sell",
    "trigger_type": "take_profit",
    "trigger_price": "70000",
    "order_type": "market",
    "order_price": null,
    "amount": "0.1",
    "position_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "created_at": 1704067200000
  }
}

响应字段说明

字段	类型	描述
id	string	触发订单 UUID
user_address	string	用户地址
symbol	string	交易对
side	string	方向
trigger_type	string	触发类型
trigger_price	string	触发价格（Decimal 字符串）
order_type	string	订单类型
order_price	string \| null	订单价格
amount	string	数量
position_id	string \| null	关联仓位 ID
status	string	状态（见下表）
created_at	number	创建时间（毫秒级时间戳）

触发订单状态

状态	说明
pending	等待触发（正在监控价格）
triggered	已触发（订单已执行）
cancelled	已取消
expired	已过期

查询触发订单列表

查询当前用户的所有触发订单。

接口信息

Method: GET
Path: /api/v1/trigger-orders
Authentication: 需要 JWT Token

Query 参数

参数	类型	必须	描述
symbol	string	否	过滤特定交易对
status	string	否	过滤状态（`pending`、`triggered`、`cancelled`）

请求示例

GET /api/v1/trigger-orders?symbol=BTCUSDT&status=pending

响应示例

{
  "success": true,
  "data": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "symbol": "BTCUSDT",
      "side": "sell",
      "trigger_type": "take_profit",
      "trigger_price": "70000",
      "order_type": "market",
      "amount": "0.1",
      "status": "pending",
      "created_at": 1704067200000
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "symbol": "BTCUSDT",
      "side": "sell",
      "trigger_type": "stop_loss",
      "trigger_price": "60000",
      "order_type": "market",
      "amount": "0.1",
      "status": "pending",
      "created_at": 1704067200000
    }
  ]
}

查询单个触发订单

查询指定触发订单的详细信息。

接口信息

Method: GET
Path: /api/v1/trigger-orders/:order_id
Authentication: 需要 JWT Token

路径参数

参数	类型	必须	描述
order_id	string	是	触发订单 UUID

响应示例

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "user_address": "0x742d35cc6634c0532925a3b844bc9e7595f0beb",
    "symbol": "BTCUSDT",
    "side": "sell",
    "trigger_type": "take_profit",
    "trigger_price": "70000",
    "order_type": "market",
    "order_price": null,
    "amount": "0.1",
    "position_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "created_at": 1704067200000,
    "triggered_at": null
  }
}

取消触发订单

取消一个尚未触发的触发订单。

接口信息

Method: DELETE
Path: /api/v1/trigger-orders/:order_id
Authentication: 需要 JWT Token

路径参数

参数	类型	必须	描述
order_id	string	是	触发订单 UUID

响应示例

{
  "success": true,
  "data": {
    "id": "660e8400-e29b-41d4-a716-446655440000",
    "status": "cancelled"
  }
}

注意

只能取消状态为 pending 的触发订单。已触发或已取消的订单无法再次取消。

设置仓位止盈止损

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

接口信息

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
  }
}

响应字段说明

字段	类型	描述
position_id	string	仓位 UUID
take_profit_price	string \| null	止盈价格
stop_loss_price	string \| null	止损价格
tp_order_id	string \| null	止盈触发订单 ID
sl_order_id	string \| null	止损触发订单 ID
updated_at	number	更新时间（毫秒级时间戳）

价格验证规则

多仓（Long Position）

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

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

空仓（Short Position）

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

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

查询仓位止盈止损

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

接口信息

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

路径参数

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

响应示例

{
  "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
  }
}

查询执行历史

查询已触发的触发订单执行历史。

接口信息

Method: GET
Path: /api/v1/trigger-orders/executions
Authentication: 需要 JWT Token

Query 参数

参数	类型	必须	描述
limit	number	否	返回数量（默认 50）

响应示例

{
  "success": true,
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "trigger_order_id": "660e8400-e29b-41d4-a716-446655440000",
      "symbol": "BTCUSDT",
      "trigger_type": "take_profit",
      "trigger_price": "70000",
      "executed_price": "70050",
      "amount": "0.1",
      "executed_at": 1704070800000,
      "result_order_id": "880e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

查询市场配置

查询触发订单在特定市场的配置信息。

接口信息

Method: GET
Path: /api/v1/trigger-orders/:symbol/config
Authentication: 不需要（公开接口）

路径参数

参数	类型	必须	描述
symbol	string	是	交易对（如 `BTCUSDT`）

响应示例

{
  "success": true,
  "data": {
    "symbol": "BTCUSDT",
    "min_amount": "0.001",
    "max_trigger_orders_per_position": 10,
    "supported_types": ["stop_loss", "take_profit", "trailing_stop"],
    "price_precision": 2,
    "amount_precision": 8
  }
}

查询用户统计

查询用户在特定市场的触发订单统计信息。

接口信息

Method: GET
Path: /api/v1/trigger-orders/:symbol/stats
Authentication: 需要 JWT Token

路径参数

参数	类型	必须	描述
symbol	string	是	交易对

响应示例

{
  "success": true,
  "data": {
    "symbol": "BTCUSDT",
    "total_pending": 5,
    "total_triggered": 23,
    "total_cancelled": 3,
    "success_rate": "0.88",
    "total_pnl": "1250.50"
  }
}

追踪止损详解

追踪止损（Trailing Stop）是一种高级止损策略，可以在价格有利方向移动时自动调整止损价格。

工作原理

设置激活价格（Activate Price）和回调比例（Callback Rate）

价格达到激活价格时，开始跟踪

记录最高价（多仓）或最低价（空仓）

当价格从最高/最低点回落指定比例时，触发平仓

示例：做多 BTC

// 参数
activate_price: "68000"     // 激活价格
callback_rate: "0.02"       // 2% 回调

// 价格变化
65000 → 等待中
68000 → 激活！开始跟踪
70000 → 更新最高价
72000 → 更新最高价
70560 → 价格从 72000 回落 2%，触发！

计算：72000 × (1 - 0.02) = 70560

示例：做空 BTC

// 参数
activate_price: "62000"     // 激活价格
callback_rate: "0.02"       // 2% 回调

// 价格变化
65000 → 等待中
62000 → 激活！开始跟踪
60000 → 更新最低价
58000 → 更新最低价
59160 → 价格从 58000 反弹 2%，触发！

计算：58000 × (1 + 0.02) = 59160

前端示例

async function createTrailingStop(position) {
  const response = await fetch('/api/v1/trigger-orders', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${jwtToken}`
    },
    body: JSON.stringify({
      symbol: position.symbol,
      side: position.side === 'long' ? 'sell' : 'buy',
      trigger_type: 'trailing_stop',
      trigger_price: "0",  // 追踪止损不需要固定触发价
      order_type: 'market',
      amount: position.size,
      callback_rate: "0.02",  // 2% 回调
      activate_price: "68000",
      position_id: position.id
    })
  });
  
  return response.json();
}

最佳实践

1. 永远设置止损

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

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

2. 动态调整止损

// 盈利时，移动止损到保本位
if (position.unrealized_pnl > 0) {
  await updateStopLoss(position.id, position.entry_price);
}

3. 分批止盈

// 在不同价位设置多个止盈
await createTriggerOrder({
  trigger_price: "70000",
  amount: position.size * 0.5  // 50% 仓位
});

await createTriggerOrder({
  trigger_price: "75000",
  amount: position.size * 0.3  // 30% 仓位
});

await createTriggerOrder({
  trigger_price: "80000",
  amount: position.size * 0.2  // 20% 仓位
});

4. 使用追踪止损锁定利润

// 价格突破新高后，使用追踪止损保护利润
if (currentPrice > allTimeHigh) {
  await createTrailingStop({
    activate_price: currentPrice,
    callback_rate: "0.03"  // 3% 回调
  });
}

常见问题

Q: 触发订单为什么不需要签名？

A: 触发订单只是设置一个监控条件，真正的订单会在触发时由系统自动创建。为了用户体验，我们简化了流程，只需要 JWT Token 认证即可。

Q: 触发订单可以修改吗？

A: 不能直接修改。您需要先取消旧的触发订单，然后创建新的触发订单。

Q: 触发后的订单会立即成交吗？

A: 如果您设置的是市价单（order_type: "market"），通常会立即成交。如果是限价单，则需要等待匹配。

Q: 一个仓位可以设置多个触发订单吗？

A: 可以。您可以设置多个止盈和止损订单，但建议总数量不超过 10 个。

Q: 追踪止损的最小回调比例是多少？

A: 建议至少 1%（0.01），太小的回调可能导致过早触发。

触发订单 (Trigger Orders)

概述​

触发订单类型​

工作原理​

创建触发订单​

接口信息​

请求参数​

请求示例​

1. 止盈订单（Take Profit）​

2. 止损订单（Stop Loss）​

3. 追踪止损订单（Trailing Stop）​

响应示例​

响应字段说明​

触发订单状态​

查询触发订单列表​

接口信息​

Query 参数​

请求示例​

响应示例​

查询单个触发订单​

接口信息​

路径参数​

响应示例​

取消触发订单​

接口信息​

路径参数​

响应示例​

设置仓位止盈止损​

接口信息​

路径参数​

请求参数​

请求示例​

响应示例​

响应字段说明​

价格验证规则​

多仓（Long Position）​

空仓（Short Position）​

查询仓位止盈止损​

接口信息​

路径参数​

响应示例​

查询执行历史​

接口信息​

Query 参数​

响应示例​

查询市场配置​

接口信息​

路径参数​

响应示例​

查询用户统计​

接口信息​

路径参数​

响应示例​

追踪止损详解​

工作原理​

示例：做多 BTC​

示例：做空 BTC​

前端示例​

最佳实践​

1. 永远设置止损​

2. 动态调整止损​

3. 分批止盈​

4. 使用追踪止损锁定利润​

常见问题​

Q: 触发订单为什么不需要签名？​

Q: 触发订单可以修改吗？​

Q: 触发后的订单会立即成交吗？​

Q: 一个仓位可以设置多个触发订单吗？​

Q: 追踪止损的最小回调比例是多少？​

相关文档​

概述

触发订单类型

工作原理

创建触发订单

接口信息

请求参数

请求示例

1. 止盈订单（Take Profit）

2. 止损订单（Stop Loss）

3. 追踪止损订单（Trailing Stop）

响应示例

响应字段说明

触发订单状态

查询触发订单列表

接口信息

Query 参数

请求示例

响应示例

查询单个触发订单

接口信息

路径参数

响应示例

取消触发订单

接口信息

路径参数

响应示例

设置仓位止盈止损

接口信息

路径参数

请求参数

请求示例

响应示例

响应字段说明

价格验证规则

多仓（Long Position）

空仓（Short Position）

查询仓位止盈止损

接口信息

路径参数

响应示例

查询执行历史

接口信息

Query 参数

响应示例

查询市场配置

接口信息

路径参数

响应示例

查询用户统计

接口信息

路径参数

响应示例

追踪止损详解

工作原理

示例：做多 BTC

示例：做空 BTC

前端示例

最佳实践

1. 永远设置止损

2. 动态调整止损

3. 分批止盈

4. 使用追踪止损锁定利润

常见问题

Q: 触发订单为什么不需要签名？

Q: 触发订单可以修改吗？

Q: 触发后的订单会立即成交吗？

Q: 一个仓位可以设置多个触发订单吗？

Q: 追踪止损的最小回调比例是多少？

相关文档