SunPerp Perpetual Futures Trading

SunPerp 永续期货交易

概述

此技能支持 AI Agent 在 SunPerp 上交易 USDT 保证金永续期货。SunPerp 是 TRON 区块链上的永续期货 DEX。它提供以下脚本：

• 市场数据：价格、订单簿、K 线、资金费率
• 账户管理：余额、费率、交易账单
• 订单管理：下单、撤单和查询订单（市价单、限价单、只挂单）
• 持仓管理：查看持仓、设置杠杆、设置持仓模式、平仓

所有脚本都通过 SunPerp REST API https://api.sunx.io 通信。

前置条件

凭据要求因操作而异： 查询公开市场数据无需凭据。 私有账户和交易调用需要 SUNPERP_ACCESS_KEY 和 SUNPERP_SECRET_KEY。 提现还需要 TRON_PRIVATE_KEY 用于确认签名。 无需单独的钱包或入门技能；请按照下方针对具体操作的设置说明进行操作。

1. 环境设置

在技能目录中安装 Node.js 依赖：

cd sunperp-skill
npm install

2. API 密钥配置

用户必须在 https://www.sunperp.com/futures/api-manage/ 创建 API 密钥，并将其设置为环境变量：

export SUNPERP_ACCESS_KEY="your_access_key"
export SUNPERP_SECRET_KEY="your_secret_key"

注意

切勿在命令或文件中硬编码 API 密钥。始终从环境变量读取密钥。如果未设置环境变量，请先提示用户进行设置，再继续操作。

3. 验证设置

运行一个公开端点以验证连接（无需 API 密钥）：

node scripts/market.js ticker contract_code=BTC-USDT

然后验证身份验证访问：

node scripts/account.js balance

使用说明

合约代码格式

SunPerp 合约遵循以下命名模式：

类型	格式	示例
永续掉期	{SYMBOL}-USDT	BTC-USDT
当周	{SYMBOL}-USDT-CW	BTC-USDT-CW
次周	{SYMBOL}-USDT-NW	BTC-USDT-NW
当季	{SYMBOL}-USDT-CQ	BTC-USDT-CQ
次季	{SYMBOL}-USDT-NQ	BTC-USDT-NQ

热门永续合约：BTC-USDT、ETH-USDT、TRX-USDT、SOL-USDT、SUN-USDT、DOGE-USDT、XRP-USDT。

持仓模式

SunPerp 支持两种持仓模式：

• single_side（单向）：所有订单均使用 position_side=both。方向由 side 字段决定。
• dual_side（双向）：必须指定 position_side=long 或 position_side=short。允许同时持有多头和空头仓位。

交易前检查当前模式：

node scripts/position.js get_mode

保证金模式

API 将全仓保证金（margin_mode=cross）作为标准模式。所有订单和持仓脚本默认使用全仓保证金。

---

脚本参考

所有脚本均位于 scripts/ 目录中，调用方式如下：

node scripts/<script>.js <command> [key=value ...]

---

市场数据（scripts/market.js）

获取市场数据无需身份验证。

获取 24 小时行情

node scripts/market.js ticker contract_code=BTC-USDT

返回：开盘价、收盘价、最高价、最低价、成交量、最佳买价/卖价。

获取订单簿

node scripts/market.js depth contract_code=BTC-USDT type=step0

type 的取值：step0（未合并，150 档）至 step5；step6（未合并，20 档）至 step13。

获取 K 线数据

node scripts/market.js kline contract_code=BTC-USDT period=60min size=50

period 的取值：1min、5min、15min、30min、60min、60min、4hour、1day、1mon。

获取最佳买价/卖价

node scripts/market.js bbo contract_code=BTC-USDT

获取最新成交

node scripts/market.js trade contract_code=BTC-USDT

获取近期成交

node scripts/market.js trades contract_code=BTC-USDT size=20

获取资金费率

node scripts/market.js funding contract_code=BTC-USDT

获取指数价格

node scripts/market.js index contract_code=BTC-USDT

列出可用合约

node scripts/market.js contracts

获取价格限制

node scripts/market.js price_limit contract_code=BTC-USDT

---

账户（scripts/account.js）

需要身份验证（API 密钥）。

查看账户余额

node scripts/account.js balance

返回：权益、可用保证金、未实现盈亏、维持保证金率。

获取费率

node scripts/account.js fee contract_code=BTC-USDT

获取交易账单

node scripts/account.js bills mar_acct=USDT

可选参数：contract=BTC-USDT、start_time=<ms>、end_time=<ms>。

---

订单管理（scripts/order.js）

需要通过身份验证，并拥有交易权限。

下市价单

开多头仓位（买入）：

node scripts/order.js place contract_code=BTC-USDT side=buy type=market volume=1

开空头仓位（卖出）：

node scripts/order.js place contract_code=BTC-USDT side=sell type=market volume=1

下限价单

node scripts/order.js place contract_code=BTC-USDT side=buy type=limit volume=1 price=95000

使用 TP/SL 下单

node scripts/order.js place contract_code=BTC-USDT side=buy type=market volume=1 tp_trigger_price=100000 sl_trigger_price=90000

下限价只挂单

node scripts/order.js place contract_code=BTC-USDT side=buy type=post_only volume=1 price=94000

在双向持仓模式下下单

当 position_mode=dual_side 时，必须指定 position_side：

# Open long
node scripts/order.js place contract_code=BTC-USDT side=buy type=market volume=1 position_side=long

# Close long
node scripts/order.js place contract_code=BTC-USDT side=sell type=market volume=1 position_side=long

# Open short
node scripts/order.js place contract_code=BTC-USDT side=sell type=market volume=1 position_side=short

# Close short
node scripts/order.js place contract_code=BTC-USDT side=buy type=market volume=1 position_side=short

撤销订单

node scripts/order.js cancel contract_code=BTC-USDT order_id=123456789

也可以通过客户端订单 ID 撤销：

node scripts/order.js cancel contract_code=BTC-USDT client_order_id=my_order_1

撤销所有订单

node scripts/order.js cancel_all

可选筛选条件：contract_code=BTC-USDT、side=buy、position_side=long。

平掉某个交易对的持仓

node scripts/order.js close contract_code=BTC-USDT position_side=both

在双向持仓模式下，使用 position_side=long 或 position_side=short。

平掉所有持仓

node scripts/order.js close_all

列出未平订单

node scripts/order.js open_orders contract_code=BTC-USDT

获取订单信息

node scripts/order.js info contract_code=BTC-USDT order_id=123456789

获取订单历史记录

node scripts/order.js history contract_code=BTC-USDT

可选参数：state=filled、start_time=<ms>、end_time=<ms>、limit=50。

获取成交详情

node scripts/order.js details contract_code=BTC-USDT order_id=123456789

---

持仓管理 (scripts/position.js)

需要身份验证。

列出未平持仓

node scripts/position.js list

也可以指定合约：

node scripts/position.js list contract_code=BTC-USDT

返回：入场价格、成交量、强平价格、未实现盈亏、保证金率、杠杆、自动减仓（ADL）风险。

获取当前杠杆

node scripts/position.js get_leverage contract_code=BTC-USDT

设置杠杆

node scripts/position.js set_leverage contract_code=BTC-USDT lever_rate=20

警告

提高杠杆会增加强平风险。设置前，务必向用户确认所需的杠杆倍数。

获取持仓模式

node scripts/position.js get_mode

设置持仓模式

node scripts/position.js set_mode position_mode=single_side

说明

只有在没有未平持仓或订单时，才能更改持仓模式。

获取风险限额

node scripts/position.js risk_limit contract_code=BTC-USDT

获取持仓限额

node scripts/position.js position_limit contract_code=BTC-USDT

---

钱包 (scripts/wallet.js)

需要通过 Withdraw 权限进行身份验证。签署提现确认还需要 TRON_PRIVATE_KEY 环境变量。

export TRON_PRIVATE_KEY="your_hex_private_key"

提取 USDT（完整流程）

执行完整的两步提现流程：申请 → 签名 → 确认。

node scripts/wallet.js withdraw address=TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx amount=10

可选参数：currency=usdt（默认）、chain=trc20usdt（默认）、fee=0（默认）。

仅申请提现（第 1 步）

返回用于手动签名的 nonce 和内容：

node scripts/wallet.js apply address=TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx amount=10

仅确认提现（第 2 步）

使用预先计算的签名确认先前申请的提现：

node scripts/wallet.js confirm nonce=<nonce_from_apply> signature=<hex_signature>

查询充值/提现记录

node scripts/wallet.js records type=deposit
node scripts/wallet.js records type=withdraw

可选参数：currency=usdt、size=50、direct=next、from=<id>。

注意

提现会将资金转移到平台外，且无法撤销。执行前，务必向用户确认收款地址和金额。

---

示例

示例 1：查询价格并开多仓

User: "Buy 5 contracts of BTC-USDT at market price"

Agent steps:
1. Check the current price:
   node scripts/market.js ticker contract_code=BTC-USDT

2. Check account balance:
   node scripts/account.js balance

3. Confirm with user: "BTC-USDT is currently at $96,500. You have $10,000 available margin.
   Placing a market buy for 5 contracts. Proceed?"

4. After user confirms, place the order:
   node scripts/order.js place contract_code=BTC-USDT side=buy type=market volume=5

5. Verify the position was opened:
   node scripts/position.js list contract_code=BTC-USDT

6. Report: "Opened long position: 5 BTC-USDT contracts at $96,502 avg entry.
   Liquidation price: $48,251. Current unrealized PnL: $0."

示例 2：设置杠杆并下限价单

User: "Set leverage to 20x on ETH-USDT and place a limit buy at $3,200 for 10 contracts"

Agent steps:
1. Set leverage:
   node scripts/position.js set_leverage contract_code=ETH-USDT lever_rate=20

2. Check current price for context:
   node scripts/market.js ticker contract_code=ETH-USDT

3. Confirm with user: "Leverage set to 20x. ETH-USDT is at $3,350.
   Placing limit buy for 10 contracts at $3,200. Proceed?"

4. After user confirms, place the order:
   node scripts/order.js place contract_code=ETH-USDT side=buy type=limit volume=10 price=3200

5. Verify the order was placed:
   node scripts/order.js open_orders contract_code=ETH-USDT

6. Report: "Limit buy order placed: 10 ETH-USDT at $3,200. Order ID: 987654321. Status: open."

示例 3：平仓并查看盈亏

User: "Close my BTC-USDT position"

Agent steps:
1. Check existing position:
   node scripts/position.js list contract_code=BTC-USDT

2. Report position details and confirm:
   "You have a long position of 5 BTC-USDT contracts. Entry: $96,502, Current: $97,100.
   Unrealized PnL: +$2.99. Close at market? Proceed?"

3. After user confirms, close:
   node scripts/order.js close contract_code=BTC-USDT position_side=both

4. Verify:
   node scripts/position.js list contract_code=BTC-USDT

5. Report: "Position closed. Realized PnL: +$2.95 after fees."

示例 4：监控资金费率

User: "What's the funding rate for TRX-USDT?"

Agent steps:
1. Get funding rate:
   node scripts/market.js funding contract_code=TRX-USDT

2. Report: "TRX-USDT funding rate: 0.01% (next funding in 2h 15m).
   Positive rate means longs pay shorts."

---

错误处理

常见错误场景

错误	原因	解决方法
缺少环境变量	未设置 SUNPERP_ACCESS_KEY / SUNPERP_SECRET_KEY	请用户设置 API 密钥
HTTP 401	API 密钥无效或已过期	请用户检查或重新生成密钥
HTTP 403	权限不足	订单操作需要 API 密钥具备 Trade 权限
时间戳错误	系统时钟偏差超过 5 分钟	检查系统时间同步
保证金不足	可用保证金不足以支持该订单	显示余额，建议降低成交量或杠杆
持仓模式冲突	在持仓未平时尝试设置持仓模式	先平仓，再切换模式
订单被拒绝	价格超出限制或成交量过小	检查 price_limit 和合约信息中的最小值/最大值

错误处理模式

脚本返回错误时：

1. 从 JSON 响应中解析错误消息（code、message 或 error-msg 字段）
2. 用通俗易懂的语言向用户解释错误
3. 提出具体的纠正措施
4. 不要自动重试交易操作——务必先向用户确认

---

Agent 安全锁

脚本级别强制执行两项必需的安全机制，以防止灾难性损失。两项机制均在 resources/sunperp_config.json 的 safety 键下配置。

1. 最大杠杆上限

参数	默认值	描述
safety.max_leverage	20	Agent 可使用的最大杠杆

此上限会在两个位置强制执行：

• position.js set_leverage — 在调用 API 前，拒绝任何高于上限的 lever_rate。
• order.js place — 如果内联传入了 lever_rate，则会在提交订单前进行校验。

如果 Agent 尝试超过上限，脚本会退出并显示明确错误：

ERROR: Leverage 50x exceeds the agent safety cap of 20x.
Adjust max_leverage in sunperp_config.json to raise this limit.

如需更改上限，请编辑配置文件中的 safety.max_leverage。这是操作员级别的设置，Agent 无法在运行时更改。

2. 强制止损

参数	默认值	描述
safety.stop_loss.required	true	每笔开仓订单是否都必须设置止损
safety.stop_loss.default_percent	5	未提供 sl_trigger_price 时自动计算的止损距离
safety.stop_loss.max_percent	25	允许的最大止损距离——拒绝距离更大的止损

当 required 为 true 时，每笔开仓订单（即非 reduce_only 订单）都必须设置止损：

• 如果提供了 sl_trigger_price：校验其与参考价格的距离是否在 max_percent 范围内。
• 如果限价单未提供该参数：在入场价下方（做多）或上方（做空）按 default_percent 自动计算。
• 如果市价单未提供该参数：脚本会获取当前市场价格并自动计算。如果获取价格失败，则拒绝订单，并提示显式提供 sl_trigger_price。

示例 — 限价做多单自动止损：

# Limit buy at $95,000 — SL auto-set to $90,250 (5% below)
node scripts/order.js place contract_code=BTC-USDT side=buy type=limit volume=1 price=95000

示例 — 显式设置止损：

node scripts/order.js place contract_code=BTC-USDT side=buy type=market volume=1 sl_trigger_price=90000

示例 — 拒绝订单（止损距离过大）：

# 30% distance exceeds max_percent of 25%
node scripts/order.js place contract_code=BTC-USDT side=buy type=limit volume=1 price=95000 sl_trigger_price=66500

说明

reduce_only 标志（平仓订单）不受止损要求限制，因为这类订单本身就在降低风险。

---

安全注意事项

注意

私钥和 API 密钥：切勿记录、显示或存储 API 密钥。只能通过环境变量读取这些密钥。

警告

交易确认：执行任何交易前，务必先与用户确认以下信息：

• 合约代码和方向（做多/做空）
• 订单类型（市价/限价）和交易量
• 价格（限价单）
• 当前杠杆设置
• 预估保证金要求

安全检查清单

• 仅从环境变量加载 API 密钥
• 命令输出或日志中不包含任何密钥
• 执行前显示交易确认信息
• 应用杠杆变更前进行确认
• 杠杆始终不超过 safety.max_leverage 上限
• 每笔开仓订单都设置了止损
• 应用持仓模式变更前进行确认
• 全部平仓操作需要用户明确确认
• 全部撤单操作需要用户明确确认

用户沟通模板

交易前确认：

📋 Order Summary:
  Contract: {contract_code}
  Side: {side} ({long/short})
  Type: {type}
  Volume: {volume} contracts
  Price: {price or "market"}
  Leverage: {lever_rate}x (cap: {max_leverage}x)
  Stop-loss: ${sl_trigger_price}
  Est. margin: ~${margin}

Proceed? (yes/no)

交易后报告：

✅ Order executed:
  Order ID: {order_id}
  Avg. fill price: ${trade_avg_price}
  Fee: ${fee}

持仓摘要：

📊 Position: {contract_code} {direction}
  Volume: {volume} contracts
  Entry: ${open_avg_price}
  Mark: ${mark_price}
  Liq. price: ${liquidation_price}
  Unrealized PnL: ${profit_unreal} ({profit_rate}%)
  Leverage: {lever_rate}x

---

版本 2.0.0 — 由 M2M Agent Registry 为 Bank of AI 创建