SunPerp Perpetual Futures Trading

SunPerp 無期限先物取引

概要

このスキルを使うと、AI エージェントがSunPerpでUSDT建て無期限先物を取引できます。SunPerpはTRONブロックチェーン上の無期限先物DEXです。このスキルには、次の操作を行うスクリプトが含まれています。

• 市場データ：価格、板情報、ローソク足、資金調達率
• アカウント管理：残高、手数料率、取引明細
• 注文管理：注文の発注、キャンセル、照会（成行、指値、ポストオンリー）
• ポジション管理：ポジションの表示、レバレッジの設定、ポジションモードの設定、ポジションの決済

すべてのスクリプトは、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では、次の2種類のポジションモードを利用できます。

• 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まで。

ローソク足データの取得

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

Post-Only 注文を出す

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）

出金権限を含む認証が必要です。また、出金確認への署名に TRON_PRIVATE_KEY 環境変数が必要です。

export TRON_PRIVATE_KEY="your_hex_private_key"

USDT を出金する（全手順）

出金に必要な 2 段階の手順をすべて実行します：申請 → 署名 → 確認。

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

任意のパラメーター：currency=usdt（デフォルト）、chain=trc20usdt（デフォルト）、fee=0（デフォルト）。

出金申請のみ（ステップ 1）

手動署名用のノンスと内容を返します。

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 キーの取引権限が必要です
タイムスタンプエラー	システム時計が 5 分以上ずれている	システム時刻の同期を確認する
証拠金不足	注文に必要な利用可能証拠金が足りない	残高を表示し、数量またはレバレッジの引き下げを提案する
ポジションモードの競合	ポジションを保有中にモードを設定しようとしている	先にポジションを決済してから、モードを切り替える
注文が拒否された	価格が上限・下限の範囲外、または数量が小さすぎる	price_limit とコントラクト情報で最小値・最大値を確認する

エラー処理のパターン

スクリプトがエラーを返した場合：

1. JSON レスポンスのエラーメッセージ（code、message、または error-msg フィールド）を解析します
2. エラーの内容をわかりやすい言葉でユーザーに説明します
3. 具体的な修正方法を提案します
4. 取引操作では自動的に再試行してはいけません。必ずユーザーに確認してください

---

エージェントの安全ロック

重大な損失を防ぐため、スクリプトレベルで 2 つの必須の安全機構が適用されます。どちらも resources/sunperp_config.json の safety キーで設定します。

1. 最大レバレッジ上限

パラメーター	デフォルト	説明
safety.max_leverage	20	エージェントが使用できる最大レバレッジ

上限は次の2か所で適用されます。

• position.js set_leverage — API を呼び出す前に、上限を超える lever_rate を拒否します。
• order.js place — lever_rate がインラインで渡された場合、注文の送信前に検証します。

エージェントが上限を超えようとすると、スクリプトは明確なエラーを出して終了します。

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

上限を変更するには、設定ファイルの safety.max_leverage を編集します。これはオペレーター向けの設定であり、エージェントは実行時に変更できません。

2. 必須のストップロス

パラメーター	デフォルト	説明
safety.stop_loss.required	true	すべてのポジション開始注文にストップロスが必要かどうか
safety.stop_loss.default_percent	5	sl_trigger_price が省略された場合に自動計算される SL の距離
safety.stop_loss.max_percent	25	許可される SL の最大距離 — これを超えるストップロスは拒否されます

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

例 — 拒否（SL の幅が広すぎる）：

# 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 — Bank of AI のために M2M Agent Registry が作成