止盈止损 API (TP/SL & Trigger Orders)

Version: v1.2 Last Updated: 2026-01-20 Status: Production Ready ✅

本文档详细说明了管理持仓止盈 (TP)、止损 (SL)、追踪止损 (TS) 以及条件单的完整 API 接口。

快速参考

Position TP/SL API (仓位止盈止损)

功能	方法	路径	认证
设置止盈止损	`POST`	`/api/v1/positions/:position_id/tp-sl`	✅
查询止盈止损	`GET`	`/api/v1/positions/:position_id/tp-sl`	✅
更新止盈止损	`PUT`	`/api/v1/positions/:position_id/tp-sl`	✅
删除止盈止损	`DELETE`	`/api/v1/positions/:position_id/tp-sl`	✅

Trigger Orders API (条件单/触发单)

功能	方法	路径	认证
创建条件单	`POST`	`/api/v1/trigger-orders`	✅
查询条件单列表	`GET`	`/api/v1/trigger-orders`	✅
查询单个条件单	`GET`	`/api/v1/trigger-orders/:order_id`	✅
取消条件单	`DELETE`	`/api/v1/trigger-orders/:order_id`	✅
查询执行历史	`GET`	`/api/v1/trigger-orders/executions`	✅
查询市场配置	`GET`	`/api/v1/trigger-orders/:symbol/config`	❌
查询用户统计	`GET`	`/api/v1/trigger-orders/:symbol/stats`	✅

⚠️ 重要提示：条件单与普通订单分离

前端必读

条件单（止盈止损/触发单）与普通订单是两套完全独立的系统！

条件单 存储在 trigger_orders 表，通过 /api/v1/trigger-orders 查询
普通订单 存储在 orders 表，通过 /api/v1/orders 或 /api/v1/account/orders 查询

条件单不会出现在普通订单列表中！ 前端必须分别调用两个接口才能展示用户的所有订单。

前端必须同时查询两个接口

// ❌ 错误做法：只查询普通订单，用户看不到止盈止损单
const orders = await fetch('/api/v1/account/orders');

// ✅ 正确做法：同时查询普通订单和条件单
async function getAllUserOrders(token) {
  // 并行请求两个接口
  const [ordersRes, triggerOrdersRes] = await Promise.all([
    fetch('/api/v1/account/orders', {
      headers: { 'Authorization': `Bearer ${token}` }
    }),
    fetch('/api/v1/trigger-orders?status=active', {
      headers: { 'Authorization': `Bearer ${token}` }
    })
  ]);

  const orders = await ordersRes.json();
  const triggerOrders = await triggerOrdersRes.json();

  return {
    regularOrders: orders.data,      // 限价单、市价单
    triggerOrders: triggerOrders.data // 止盈、止损、追踪止损单
  };
}

订单系统对比

特性	普通订单	条件单/触发单
API 路径	`/api/v1/orders`	`/api/v1/trigger-orders`
数据库表	`orders`	`trigger_orders`
订单类型	limit, market	take_profit, stop_loss, trailing_stop
触发机制	立即进入撮合引擎	价格达到条件后触发
查询方式	通过订单 API	必须通过触发单 API

基础信息

环境地址

环境	Base URL
测试网	`https://api.8a27.xyz/api/v1`
生产环境	`https://api.axblade.io/api/v1`

请求头

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

Part 1: Position TP/SL API (仓位止盈止损)

1.1 设置止盈止损

为指定持仓创建或覆盖止盈止损配置。

请求

POST /api/v1/positions/:position_id/tp-sl

路径参数

参数	类型	描述
`position_id`	UUID	持仓 ID

请求体

字段	类型	必填	描述
`take_profit_price`	string	否	止盈触发价格
`take_profit_size`	string	否	止盈平仓数量，`null` 或 `"0"` 表示全额平仓
`stop_loss_price`	string	否	止损触发价格
`stop_loss_size`	string	否	止损平仓数量，`null` 或 `"0"` 表示全额平仓
`trailing_stop_delta`	string	否	追踪止损偏移量
`trailing_stop_delta_type`	string	否	`"absolute"` (绝对值) 或 `"percentage"` (百分比)
`trailing_stop_size`	string	否	追踪止损平仓数量

请求示例

{
  "take_profit_price": "95000.0",
  "take_profit_size": "0.5",
  "stop_loss_price": "88000.0",
  "stop_loss_size": null
}

响应示例

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "position_id": "660e8400-e29b-41d4-a716-446655440001",
    "user_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
    "market_symbol": "BTCUSDT",
    "take_profit_price": "95000.00",
    "take_profit_size": "0.50",
    "take_profit_trigger_order_id": "770e8400-e29b-41d4-a716-446655440002",
    "stop_loss_price": "88000.00",
    "stop_loss_size": null,
    "stop_loss_trigger_order_id": "880e8400-e29b-41d4-a716-446655440003",
    "trailing_stop_delta": null,
    "trailing_stop_delta_type": null,
    "trailing_stop_size": null,
    "trailing_stop_trigger_order_id": null,
    "created_at": "2026-01-20T10:30:00.000Z",
    "updated_at": "2026-01-20T10:30:00.000Z"
  },
  "error": null
}

1.2 查询止盈止损

获取持仓的止盈止损设置。

请求

GET /api/v1/positions/:position_id/tp-sl

响应示例

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "position_id": "660e8400-e29b-41d4-a716-446655440001",
    "user_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
    "market_symbol": "BTCUSDT",
    "take_profit_price": "95000.00",
    "take_profit_size": "0.50",
    "take_profit_trigger_order_id": "770e8400-e29b-41d4-a716-446655440002",
    "stop_loss_price": "88000.00",
    "stop_loss_size": null,
    "stop_loss_trigger_order_id": "880e8400-e29b-41d4-a716-446655440003",
    "trailing_stop_delta": null,
    "trailing_stop_delta_type": null,
    "trailing_stop_size": null,
    "trailing_stop_trigger_order_id": null,
    "created_at": "2026-01-20T10:30:00.000Z",
    "updated_at": "2026-01-20T10:30:00.000Z"
  },
  "error": null
}

无设置时响应

{
  "success": true,
  "data": null,
  "error": null
}

1.3 更新止盈止损

更新现有的止盈止损配置（Upsert 逻辑，与 POST 相同）。

请求

PUT /api/v1/positions/:position_id/tp-sl

请求体: 同 POST

1.4 删除止盈止损

删除持仓的止盈止损配置，并自动取消所有关联的活跃触发单。

请求

DELETE /api/v1/positions/:position_id/tp-sl

响应示例

{
  "success": true,
  "data": "TP/SL deleted successfully",
  "error": null
}

Part 2: Trigger Orders API (条件单/触发单)

2.1 查询条件单列表 ⭐

获取用户的所有条件单，支持按市场和状态筛选。

请求

GET /api/v1/trigger-orders

查询参数

参数	类型	必填	默认值	描述
`market_symbol`	string	否	-	筛选市场 (如 `BTCUSDT`)
`status`	string	否	-	筛选状态
`limit`	integer	否	100	返回条数 (1-500)

状态类型 (status)

值	描述
`active`	活跃中，等待触发
`triggered`	已触发，正在执行
`executed`	已执行完成
`cancelled`	已取消
`expired`	已过期
`failed`	执行失败

请求示例

# 获取所有活跃条件单
curl "https://api.8a27.xyz/api/v1/trigger-orders?status=active" \
  -H "Authorization: Bearer <TOKEN>"

# 获取 BTCUSDT 的所有条件单
curl "https://api.8a27.xyz/api/v1/trigger-orders?market_symbol=BTCUSDT" \
  -H "Authorization: Bearer <TOKEN>"

# 获取所有条件单（包括历史）
curl "https://api.8a27.xyz/api/v1/trigger-orders?limit=50" \
  -H "Authorization: Bearer <TOKEN>"

响应示例

{
  "success": true,
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440002",
      "user_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
      "market_symbol": "BTCUSDT",
      "position_id": "660e8400-e29b-41d4-a716-446655440001",
      "order_type": "take_profit",
      "side": "sell",
      "trigger_price": "95000.00",
      "trigger_condition": "gte",
      "size": "0.50",
      "status": "active",
      "created_at": "2026-01-20T10:30:00.000Z",
      "updated_at": "2026-01-20T10:30:00.000Z",
      "triggered_at": null,
      "executed_at": null,
      "cancelled_at": null,
      "expire_at": null
    },
    {
      "id": "880e8400-e29b-41d4-a716-446655440003",
      "user_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
      "market_symbol": "BTCUSDT",
      "position_id": "660e8400-e29b-41d4-a716-446655440001",
      "order_type": "stop_loss",
      "side": "sell",
      "trigger_price": "88000.00",
      "trigger_condition": "lte",
      "size": null,
      "status": "active",
      "created_at": "2026-01-20T10:30:00.000Z",
      "updated_at": "2026-01-20T10:30:00.000Z",
      "triggered_at": null,
      "executed_at": null,
      "cancelled_at": null,
      "expire_at": null
    }
  ],
  "error": null
}

响应字段说明

字段	类型	描述
`id`	UUID	条件单 ID
`user_address`	string	用户地址
`market_symbol`	string	交易对
`position_id`	UUID\|null	关联的持仓 ID
`order_type`	string	订单类型: `take_profit`, `stop_loss`, `trailing_stop`
`side`	string	方向: `buy`, `sell`
`trigger_price`	string	触发价格
`trigger_condition`	string	触发条件: `gte` (`>=`), `lte` (`<=`)
`size`	string\|null	平仓数量，null 表示全仓
`status`	string	状态
`created_at`	string	创建时间
`updated_at`	string	更新时间
`triggered_at`	string\|null	触发时间
`executed_at`	string\|null	执行时间
`cancelled_at`	string\|null	取消时间
`expire_at`	string\|null	过期时间

2.2 查询单个条件单

获取指定条件单的详细信息。

请求

GET /api/v1/trigger-orders/:order_id

路径参数

参数	类型	描述
`order_id`	UUID	条件单 ID

响应示例

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "user_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
    "market_symbol": "BTCUSDT",
    "position_id": "660e8400-e29b-41d4-a716-446655440001",
    "order_type": "take_profit",
    "side": "sell",
    "trigger_price": "95000.00",
    "trigger_condition": "gte",
    "size": "0.50",
    "status": "active",
    "created_at": "2026-01-20T10:30:00.000Z",
    "updated_at": "2026-01-20T10:30:00.000Z",
    "triggered_at": null,
    "executed_at": null,
    "cancelled_at": null,
    "expire_at": null
  },
  "error": null
}

2.3 取消条件单 ⭐

取消指定的条件单。只能取消 active 状态的订单。

请求

DELETE /api/v1/trigger-orders/:order_id

路径参数

参数	类型	描述
`order_id`	UUID	要取消的条件单 ID

请求示例

curl -X DELETE "https://api.8a27.xyz/api/v1/trigger-orders/770e8400-e29b-41d4-a716-446655440002" \
  -H "Authorization: Bearer <TOKEN>"

响应示例

{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440002",
    "user_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
    "market_symbol": "BTCUSDT",
    "position_id": "660e8400-e29b-41d4-a716-446655440001",
    "order_type": "take_profit",
    "side": "sell",
    "trigger_price": "95000.00",
    "trigger_condition": "gte",
    "size": "0.50",
    "status": "cancelled",
    "created_at": "2026-01-20T10:30:00.000Z",
    "updated_at": "2026-01-20T10:35:00.000Z",
    "triggered_at": null,
    "executed_at": null,
    "cancelled_at": "2026-01-20T10:35:00.000Z",
    "expire_at": null
  },
  "error": null
}

错误响应

{
  "success": false,
  "data": null,
  "error": "Cannot cancel order with status: executed"
}

2.4 创建条件单

创建新的条件单（通常通过 Position TP/SL API 间接创建）。

请求

POST /api/v1/trigger-orders

请求体

字段	类型	必填	描述
`market_symbol`	string	✅	交易对
`position_id`	UUID	否	关联的持仓 ID
`order_type`	string	✅	`take_profit`, `stop_loss`, `trailing_stop`
`side`	string	✅	`buy`, `sell`
`trigger_price`	string	✅	触发价格
`trigger_condition`	string	✅	`gte`, `lte`
`size`	string	否	平仓数量
`expire_at`	string	否	过期时间 (ISO 8601)

2.5 查询执行历史

获取用户的条件单执行历史。

请求

GET /api/v1/trigger-orders/executions

查询参数

参数	类型	必填	默认值	描述
`limit`	integer	否	100	返回条数

响应示例

{
  "success": true,
  "data": [
    {
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "trigger_order_id": "770e8400-e29b-41d4-a716-446655440002",
      "user_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
      "market_symbol": "BTCUSDT",
      "order_type": "take_profit",
      "trigger_price": "95000.00",
      "execution_price": "95010.50",
      "size": "0.50",
      "pnl": "1500.25",
      "status": "success",
      "executed_at": "2026-01-20T12:00:00.000Z"
    }
  ],
  "error": null
}

2.6 查询市场配置

获取指定市场的条件单配置参数。

请求

GET /api/v1/trigger-orders/:symbol/config

响应示例

{
  "success": true,
  "data": {
    "market_symbol": "BTCUSDT",
    "min_trigger_distance_percent": "0.1",
    "max_trigger_orders_per_position": 10,
    "trailing_stop_min_delta_percent": "0.5",
    "enabled": true
  },
  "error": null
}

2.7 查询用户统计

获取用户在指定市场的条件单统计。

请求

GET /api/v1/trigger-orders/:symbol/stats

响应示例

{
  "success": true,
  "data": {
    "user_address": "0x29f721b203a9fc9c5dde35a739d8b8e0e4605489",
    "market_symbol": "BTCUSDT",
    "active_orders": 2,
    "total_orders": 15,
    "executed_orders": 10,
    "cancelled_orders": 3,
    "total_pnl": "5230.50"
  },
  "error": null
}

错误码

错误码	HTTP 状态	描述
`UNAUTHORIZED`	401	未认证或 Token 无效
`FORBIDDEN`	403	无权操作该资源
`NOT_FOUND`	404	持仓或条件单不存在
`BAD_REQUEST`	400	请求参数无效
`INTERNAL_ERROR`	500	服务器内部错误

错误响应格式

{
  "success": false,
  "data": null,
  "error": "Position not found"
}

前端集成示例

获取所有活跃条件单

async function getActiveTriggerOrders(token) {
  const response = await fetch('/api/v1/trigger-orders?status=active', {
    headers: { 'Authorization': `Bearer ${token}` }
  });

  const { success, data, error } = await response.json();

  if (!success) {
    throw new Error(error);
  }

  return data.map(order => ({
    id: order.id,
    type: order.order_type,
    symbol: order.market_symbol,
    positionId: order.position_id,
    triggerPrice: parseFloat(order.trigger_price),
    size: order.size ? parseFloat(order.size) : null,
    status: order.status,
    createdAt: new Date(order.created_at)
  }));
}

取消条件单

async function cancelTriggerOrder(token, orderId) {
  const response = await fetch(`/api/v1/trigger-orders/${orderId}`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${token}` }
  });

  const { success, data, error } = await response.json();

  if (!success) {
    throw new Error(error);
  }

  return {
    orderId: data.id,
    status: data.status,
    cancelledAt: data.cancelled_at
  };
}

设置持仓止盈止损

async function setPositionTpSl(token, positionId, tpPrice, slPrice) {
  const response = await fetch(`/api/v1/positions/${positionId}/tp-sl`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      take_profit_price: tpPrice?.toString() || null,
      stop_loss_price: slPrice?.toString() || null,
      take_profit_size: null,  // 全仓
      stop_loss_size: null     // 全仓
    })
  });

  const { success, data, error } = await response.json();

  if (!success) {
    throw new Error(error);
  }

  return data;
}

删除持仓止盈止损

async function deletePositionTpSl(token, positionId) {
  const response = await fetch(`/api/v1/positions/${positionId}/tp-sl`, {
    method: 'DELETE',
    headers: { 'Authorization': `Bearer ${token}` }
  });

  const { success, error } = await response.json();

  if (!success) {
    throw new Error(error);
  }

  return true;
}

技术说明

部分平仓 (Partial TP/SL)

接口支持自定义平仓数量
如果 size 为空或为 0，触发时将平掉全部持仓
如果设置了具体数值（例如持仓 1.0 BTC，止盈 size 设置为 0.5），则触发时只会平掉 0.5 BTC

触发单同步

调用 Position TP/SL 设置接口时，系统会自动在 trigger_orders 表中同步创建/更新条件单
调用 Position TP/SL 删除接口时，系统会自动将所有相关的 active 状态触发单标记为 cancelled

唯一性

每个 position 只会对应一个 TP/SL 配置对象
多次设置将自动覆盖旧配置

地址格式

接口在进行权限检查时对地址大小写不敏感

更新日志

版本	日期	变更
v1.2	2026-01-20	重要添加条件单与普通订单分离说明，添加前端同时查询两个接口的示例
v1.1	2026-01-20	添加条件单查询和取消接口文档，添加前端集成示例
v1.0	2026-01-13	初始版本

快速参考​

Position TP/SL API (仓位止盈止损)​

Trigger Orders API (条件单/触发单)​

⚠️ 重要提示：条件单与普通订单分离​

前端必须同时查询两个接口​

订单系统对比​

基础信息​

环境地址​

请求头​

Part 1: Position TP/SL API (仓位止盈止损)​

1.1 设置止盈止损​

1.2 查询止盈止损​

1.3 更新止盈止损​

1.4 删除止盈止损​

Part 2: Trigger Orders API (条件单/触发单)​

2.1 查询条件单列表 ⭐​

2.2 查询单个条件单​

2.3 取消条件单 ⭐​

2.4 创建条件单​

2.5 查询执行历史​

2.6 查询市场配置​

2.7 查询用户统计​

错误码​

前端集成示例​

获取所有活跃条件单​

取消条件单​

设置持仓止盈止损​

删除持仓止盈止损​

技术说明​

部分平仓 (Partial TP/SL)​

触发单同步​

唯一性​

地址格式​

更新日志​

快速参考

Position TP/SL API (仓位止盈止损)

Trigger Orders API (条件单/触发单)

⚠️ 重要提示：条件单与普通订单分离

前端必须同时查询两个接口

订单系统对比

基础信息

环境地址

请求头

Part 1: Position TP/SL API (仓位止盈止损)

1.1 设置止盈止损

1.2 查询止盈止损

1.3 更新止盈止损

1.4 删除止盈止损

Part 2: Trigger Orders API (条件单/触发单)

2.1 查询条件单列表 ⭐

2.2 查询单个条件单

2.3 取消条件单 ⭐

2.4 创建条件单

2.5 查询执行历史

2.6 查询市场配置

2.7 查询用户统计

错误码

前端集成示例

获取所有活跃条件单

取消条件单

设置持仓止盈止损

删除持仓止盈止损

技术说明

部分平仓 (Partial TP/SL)

触发单同步

唯一性

地址格式

更新日志