仓位管理 (Positions)

查询和管理交易仓位。

获取仓位列表

接口信息

Method: GET
Path: /api/v1/positions
Authentication: 需要身份验证

响应示例

{
  "positions": [
    {
      "position_id": "550e8400-e29b-41d4-a716-446655440000",
      "symbol": "BTCUSDT",
      "side": "long",
      "status": "open",
      "size_in_usd": "6500.00",
      "size_in_tokens": "0.1",
      "collateral_amount": "650.00",
      "entry_price": "65000.00",
      "mark_price": "65500.00",
      "liquidation_price": "60000.00",
      "leverage": 10,
      "margin_ratio": "0.10",
      "unrealized_pnl": "50.00",
      "unrealized_pnl_percent": "7.69",
      "realized_pnl": "0.00",
      "accumulated_funding_fee": "0.50",
      "accumulated_borrowing_fee": "0.10",
      "net_value": "649.40",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T01:00:00Z"
    }
  ],
  "total_unrealized_pnl": "50.00",
  "total_collateral": "650.00"
}

响应字段说明

字段	类型	描述
positions	array	仓位列表
total_unrealized_pnl	string	总未实现盈亏
total_collateral	string	总抵押品数量

Position 对象字段

字段	类型	描述
position_id	string	仓位 UUID
symbol	string	交易对
side	string	持仓方向（long/short）
status	string	仓位状态（open/closed/liquidated）
size_in_usd	string	仓位大小（USD）
size_in_tokens	string	仓位大小（代币数量）
collateral_amount	string	抵押品数量
entry_price	string	开仓均价
mark_price	string	当前标记价格
liquidation_price	string	清算价格
leverage	number	杠杆倍数
margin_ratio	string	保证金率
unrealized_pnl	string	未实现盈亏
unrealized_pnl_percent	string	未实现盈亏百分比
realized_pnl	string	已实现盈亏
accumulated_funding_fee	string	累计资金费用
accumulated_borrowing_fee	string	累计借贷费用
net_value	string	净值（扣除费用后）
created_at	string	创建时间
updated_at	string	更新时间

获取单个仓位

接口信息

Method: GET
Path: /api/v1/positions/:position_id
Authentication: 需要身份验证

路径参数

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

响应示例

{
  "position_id": "550e8400-e29b-41d4-a716-446655440000",
  "symbol": "BTCUSDT",
  "side": "long",
  "status": "open",
  "size_in_usd": "6500.00",
  "size_in_tokens": "0.1",
  "collateral_amount": "650.00",
  "entry_price": "65000.00",
  "mark_price": "65500.00",
  "liquidation_price": "60000.00",
  "leverage": 10,
  "margin_ratio": "0.10",
  "unrealized_pnl": "50.00",
  "unrealized_pnl_percent": "7.69",
  "realized_pnl": "0.00",
  "accumulated_funding_fee": "0.50",
  "accumulated_borrowing_fee": "0.10",
  "net_value": "649.40",
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T01:00:00Z"
}

开仓/增加仓位

接口信息

Method: POST
Path: /api/v1/positions
Authentication: 需要身份验证
Content-Type: application/json

请求参数

参数	类型	必须	描述
symbol	string	是	交易对
side	string	是	方向（long/short）
collateral_amount	string	是	抵押品数量
leverage	number	是	杠杆倍数（1-100）
signature	string	是	签名
timestamp	number	是	Unix 时间戳（秒）

请求示例

{
  "symbol": "BTCUSDT",
  "side": "long",
  "collateral_amount": "1000.00",
  "leverage": 10,
  "signature": "0x...",
  "timestamp": 1704067200
}

响应示例

{
  "success": true,
  "message": "Position opened successfully",
  "position": {
    "position_id": "550e8400-e29b-41d4-a716-446655440000",
    "symbol": "BTCUSDT",
    "side": "long",
    "size_in_usd": "10000.00",
    "collateral_amount": "1000.00",
    "leverage": 10,
    "entry_price": "65000.00",
    "mark_price": "65000.00",
    "liquidation_price": "60000.00"
  }
}

错误响应

HTTP 状态码	错误码	描述
400	INSUFFICIENT_BALANCE	余额不足
400	PRICE_UNAVAILABLE	无法获取当前市场价格
400	POSITION_OPEN_FAILED	开仓失败

平仓/减少仓位

接口信息

Method: POST
Path: /api/v1/positions/:position_id/close
Authentication: 需要身份验证
Content-Type: application/json

路径参数

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

请求参数

参数	类型	必须	描述
amount	string	否	平仓数量（不传则全平）
price	string	否	限价（不传则市价）
signature	string	是	签名
timestamp	number	是	Unix 时间戳（秒）

请求示例

{
  "amount": "0.05",
  "price": null,
  "signature": "0x...",
  "timestamp": 1704067200
}

响应示例

{
  "success": true,
  "message": "Position partially closed",
  "position": {
    "position_id": "550e8400-e29b-41d4-a716-446655440000",
    "symbol": "BTCUSDT",
    "side": "long",
    "size_in_usd": "3250.00",
    "size_in_tokens": "0.05",
    "unrealized_pnl": "25.00"
  }
}

增加保证金

接口信息

Method: POST
Path: /api/v1/positions/:position_id/collateral/add
Authentication: 需要身份验证
Content-Type: application/json

路径参数

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

请求参数

参数	类型	必须	描述
amount	string	是	增加的保证金数量

请求示例

{
  "amount": "100.00"
}

响应示例

{
  "success": true,
  "message": "Collateral added successfully",
  "position": {
    "position_id": "550e8400-e29b-41d4-a716-446655440000",
    "collateral_amount": "750.00",
    "liquidation_price": "58000.00"
  }
}

减少保证金

接口信息

Method: POST
Path: /api/v1/positions/:position_id/collateral/remove
Authentication: 需要身份验证
Content-Type: application/json

路径参数

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

请求参数

参数	类型	必须	描述
amount	string	是	减少的保证金数量

请求示例

{
  "amount": "50.00"
}

响应示例

{
  "success": true,
  "message": "Collateral removed successfully",
  "position": {
    "position_id": "550e8400-e29b-41d4-a716-446655440000",
    "collateral_amount": "600.00",
    "liquidation_price": "61000.00"
  }
}

检查清算状态

接口信息

Method: GET
Path: /api/v1/positions/:position_id/liquidation
Authentication: 需要身份验证

路径参数

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

响应示例

{
  "is_liquidatable": false,
  "reason": null,
  "remaining_collateral_usd": "649.40",
  "min_collateral_usd": "32.50",
  "min_collateral_for_leverage": "650.00"
}

响应字段说明

字段	类型	描述
is_liquidatable	boolean	是否可被清算
reason	string \| null	清算原因
remaining_collateral_usd	string	剩余抵押品价值（USD）
min_collateral_usd	string	最小抵押品要求（USD）
min_collateral_for_leverage	string	当前杠杆所需最小抵押品

仓位管理 (Positions)

获取仓位列表​

接口信息​

响应示例​

响应字段说明​

Position 对象字段​

获取单个仓位​

接口信息​

路径参数​

响应示例​

开仓/增加仓位​

接口信息​

请求参数​

请求示例​

响应示例​

错误响应​

平仓/减少仓位​

接口信息​

路径参数​

请求参数​

请求示例​

响应示例​

增加保证金​

接口信息​

路径参数​

请求参数​

请求示例​

响应示例​

减少保证金​

接口信息​

路径参数​

请求参数​

请求示例​

响应示例​

检查清算状态​

接口信息​

路径参数​

响应示例​

响应字段说明​

获取仓位列表

接口信息

响应示例

响应字段说明

Position 对象字段

获取单个仓位

接口信息

路径参数

响应示例

开仓/增加仓位

接口信息

请求参数

请求示例

响应示例

错误响应

平仓/减少仓位

接口信息

路径参数

请求参数

请求示例

响应示例

增加保证金

接口信息

路径参数

请求参数

请求示例

响应示例

减少保证金

接口信息

路径参数

请求参数

请求示例

响应示例

检查清算状态

接口信息

路径参数

响应示例

响应字段说明