sunperp-perpetual-futures-trading

# SunPerp Perpetual Futures Trading ## Overview This skill enables AI agents to trade USDT-margined perpetual futures on [SunPerp](https://www.sunperp.com), the perpetual futures DEX on the TRON blockchain. It provides scripts for: - **Market data**: Prices, order books, candlesticks, funding rates - **Account management**: Balances, fee rates, trading bills - **Order management**: Place, cancel, and query orders (market, limit, post-only) - **Position management**: View positions, set leverage, set position mode, close positions All scripts communicate with the SunPerp REST API at `https://api.sunx.io`. ## Prerequisites > **Credentials depend on the operation:** Public market queries require no credentials. > Private account and trading calls use `SUNPERP_ACCESS_KEY` and `SUNPERP_SECRET_KEY`. > Withdrawals additionally require `TRON_PRIVATE_KEY` for confirmation signing. > No separate wallet or onboarding Skill is required; follow the operation-specific setup below. ### 1. Environment Setup Install Node.js dependencies from the skill directory: ```bash cd sunperp-skill npm install ``` ### 2. API Key Configuration The user must create API keys at https://www.sunperp.com/futures/api-manage/ and set them as environment variables: ```bash export SUNPERP_ACCESS_KEY="your_access_key" export SUNPERP_SECRET_KEY="your_secret_key" ``` > [!CAUTION] > Never hardcode API keys in commands or files. Always read them from environment variables. If the environment variables are not set, prompt the user to set them before proceeding. ### 3. Verify Setup Run a public endpoint to verify connectivity (no API key needed): ```bash node scripts/market.js ticker contract_code=BTC-USDT ``` Then verify authenticated access: ```bash node scripts/account.js balance ``` ## Usage Instructions ### Contract Code Format SunPerp contracts follow these naming patterns: | Type | Format | Example | |---|---|---| | Perpetual swap | `{SYMBOL}-USDT` | `BTC-USDT` | | Current week | `{SYMBOL}-USDT-CW` | `BTC-USDT-CW` | | Next week | `{SYMBOL}-USDT-NW` | `BTC-USDT-NW` | | Current quarter | `{SYMBOL}-USDT-CQ` | `BTC-USDT-CQ` | | Next quarter | `{SYMBOL}-USDT-NQ` | `BTC-USDT-NQ` | Popular perpetual contracts: `BTC-USDT`, `ETH-USDT`, `TRX-USDT`, `SOL-USDT`, `SUN-USDT`, `DOGE-USDT`, `XRP-USDT`. ### Position Modes SunPerp supports two position modes: - **single_side** (One-way): Use `position_side=both` for all orders. The `side` field determines direction. - **dual_side** (Hedge): Must specify `position_side=long` or `position_side=short`. Allows simultaneous long and short positions. Check the current mode before trading: ```bash node scripts/position.js get_mode ``` ### Margin Mode The API uses **cross margin** (`margin_mode=cross`) as the standard mode. All order and position scripts default to cross margin. --- ### Script Reference All scripts are located in the `scripts/` directory and invoked as: ```bash node scripts/<script>.js <command> [key=value ...] ``` --- ### Market Data (scripts/market.js) No authentication required for market data. #### Get 24h Ticker ```bash node scripts/market.js ticker contract_code=BTC-USDT ``` Returns: open, close, high, low, volume, best bid/ask. #### Get Order Book ```bash node scripts/market.js depth contract_code=BTC-USDT type=step0 ``` `type` values: `step0` (unmerged, 150 levels) through `step5`; `step6` (unmerged, 20 levels) through `step13`. #### Get Candlestick Data ```bash node scripts/market.js kline contract_code=BTC-USDT period=60min size=50 ``` `period` values: `1min`, `5min`, `15min`, `30min`, `60min`, `60min`, `4hour`, `1day`, `1mon`. #### Get Best Bid/Offer ```bash node scripts/market.js bbo contract_code=BTC-USDT ``` #### Get Last Trade ```bash node scripts/market.js trade contract_code=BTC-USDT ``` #### Get Recent Trades ```bash node scripts/market.js trades contract_code=BTC-USDT size=20 ``` #### Get Funding Rate ```bash node scripts/market.js funding contract_code=BTC-USDT ``` #### Get Index Price ```bash node scripts/market.js index contract_code=BTC-USDT ``` #### List Available Contracts ```bash node scripts/market.js contracts ``` #### Get Price Limits ```bash node scripts/market.js price_limit contract_code=BTC-USDT ``` --- ### Account (scripts/account.js) Requires authentication (API keys). #### Check Account Balance ```bash node scripts/account.js balance ``` Returns: equity, available margin, unrealized PnL, maintenance margin rate. #### Get Fee Rates ```bash node scripts/account.js fee contract_code=BTC-USDT ``` #### Get Trading Bills ```bash node scripts/account.js bills mar_acct=USDT ``` Optional: `contract=BTC-USDT`, `start_time=<ms>`, `end_time=<ms>`. --- ### Order Management (scripts/order.js) Requires authentication with **Trade** permission. #### Place a Market Order Open a long position (buy): ```bash node scripts/order.js place contract_code=BTC-USDT side=buy type=market volume=1 ``` Open a short position (sell): ```bash node scripts/order.js place contract_code=BTC-USDT side=sell type=market volume=1 ``` #### Place a Limit Order ```bash node scripts/order.js place contract_code=BTC-USDT side=buy type=limit volume=1 price=95000 ``` #### Place an Order with TP/SL ```bash node scripts/order.js place contract_code=BTC-USDT side=buy type=market volume=1 tp_trigger_price=100000 sl_trigger_price=90000 ``` #### Place a Post-Only Order ```bash node scripts/order.js place contract_code=BTC-USDT side=buy type=post_only volume=1 price=94000 ``` #### Place an Order in Hedge Mode When `position_mode=dual_side`, you must specify `position_side`: ```bash # 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 ``` #### Cancel an Order ```bash node scripts/order.js cancel contract_code=BTC-USDT order_id=123456789 ``` Or by client order ID: ```bash node scripts/order.js cancel contract_code=BTC-USDT client_order_id=my_order_1 ``` #### Cancel All Orders ```bash node scripts/order.js cancel_all ``` Optionally filter: `contract_code=BTC-USDT`, `side=buy`, `position_side=long`. #### Close Position for a Symbol ```bash node scripts/order.js close contract_code=BTC-USDT position_side=both ``` In hedge mode use `position_side=long` or `position_side=short`. #### Close All Positions ```bash node scripts/order.js close_all ``` #### List Open Orders ```bash node scripts/order.js open_orders contract_code=BTC-USDT ``` #### Get Order Info ```bash node scripts/order.js info contract_code=BTC-USDT order_id=123456789 ``` #### Get Order History ```bash node scripts/order.js history contract_code=BTC-USDT ``` Optional: `state=filled`, `start_time=<ms>`, `end_time=<ms>`, `limit=50`. #### Get Execution Details ```bash node scripts/order.js details contract_code=BTC-USDT order_id=123456789 ``` --- ### Position Management (scripts/position.js) Requires authentication. #### List Open Positions ```bash node scripts/position.js list ``` Or for a specific contract: ```bash node scripts/position.js list contract_code=BTC-USDT ``` Returns: entry price, volume, liquidation price, unrealized PnL, margin rate, leverage, ADL risk. #### Get Current Leverage ```bash node scripts/position.js get_leverage contract_code=BTC-USDT ``` #### Set Leverage ```bash node scripts/position.js set_leverage contract_code=BTC-USDT lever_rate=20 ``` > [!WARNING] > Increasing leverage increases liquidation risk. Always confirm the desired leverage with the user before setting it. #### Get Position Mode ```bash node scripts/position.js get_mode ``` #### Set Position Mode ```bash node scripts/position.js set_mode position_mode=single_side ``` > [!NOTE] > Position mode can only be changed when there are no open positions or orders. #### Get Risk Limits ```bash node scripts/position.js risk_limit contract_code=BTC-USDT ``` #### Get Position Limits ```bash node scripts/position.js position_limit contract_code=BTC-USDT ``` --- ### Wallet (scripts/wallet.js) Requires authentication with **Withdraw** permission. Also requires `TRON_PRIVATE_KEY` env var for signing withdrawal confirmations. ```bash export TRON_PRIVATE_KEY="your_hex_private_key" ``` #### Withdraw USDT (Full Flow) Performs the complete two-step withdraw: apply → sign → confirm. ```bash node scripts/wallet.js withdraw address=TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx amount=10 ``` Optional: `currency=usdt` (default), `chain=trc20usdt` (default), `fee=0` (default). #### Withdraw Apply Only (Step 1) Returns nonce and content for manual signing: ```bash node scripts/wallet.js apply address=TXxxxxxxxxxxxxxxxxxxxxxxxxxxxx amount=10 ``` #### Withdraw Confirm Only (Step 2) Confirm a previously applied withdrawal with a pre-computed signature: ```bash node scripts/wallet.js confirm nonce=<nonce_from_apply> signature=<hex_signature> ``` #### Query Deposit/Withdraw Records ```bash node scripts/wallet.js records type=deposit node scripts/wallet.js records type=withdraw ``` Optional: `currency=usdt`, `size=50`, `direct=next`, `from=<id>`. > [!CAUTION] > Withdrawals move funds off-platform and are irreversible. Always confirm the destination address and amount with the user before executing. --- ## Examples ### Example 1: Check Price and Open a Long Position ``` 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." ``` ### Example 2: Set Leverage and Place a Limit Order ``` 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."