HyperFunTrading API

HyperFunTrading API Documentation

Overview

HyperFunTrading is the trading module for HyperFun vaults on Hyperliquid. It handles:

• Perpetual trading (open/close positions)

• L1 fund transfers (Spot ↔ Perp)

• Auto-rebalancing (EVM ↔ L1)

• API wallet management

Contract Address: Deployed as a proxy for each vault (get from vault.tradingModule())

---

Constants

Name	Value	Description
USDC	0xb88339CB7199b77E23DB6E890353E22632Ba630f	USDC token on HyperEVM
CORE_DEPOSIT_WALLET	0x6B9E773128f453f5c2C60935Ee2DE2CBc5390A24	For EVM → L1 deposits

Asset Indices (Hyperliquid Perps)

Asset	Index	szDecimals	Max Leverage
BTC	0	5	50x
ETH	1	4	50x
SOL	5	2	20x
SUI	57	1	20x
HYPE	132	1	20x

---

Authorization

Role	Can Call
Leader	All trading functions, API wallet management
API Wallet	All trading functions (if active & not expired)
Admin	Fund withdrawals, refill reserve
Vault	autoRebalance() only

---

Trading Functions

executeMarketOrder

Execute a market order with IOC (Immediate-Or-Cancel).

function executeMarketOrder(
    uint32 asset,      // Asset index (0=BTC, 1=ETH, 5=SOL, etc.)
    bool isBuy,        // true=LONG, false=SHORT
    uint64 size,       // Size in 1e8 format (1.5 SOL = 150000000)
    uint64 price       // Price in 1e8 format with 3% slippage
) external

With custom leverage:

function executeMarketOrder(
    uint32 asset,
    bool isBuy,
    uint64 size,
    uint64 price,
    uint32 leverage    // 1 to maxLeverage, 0 = use max
) external

Example (Python/JS):

// Long 1.5 SOL at $150 with 3% slippage
const asset = 5;  // SOL
const isBuy = true;
const size = 150000000;  // 1.5 * 1e8
const price = 15450000000;  // $154.50 * 1e8 (with slippage)
const leverage = 10;

await trading.executeMarketOrder(asset, isBuy, size, price, leverage);

---

executeLimitOrder

Execute a limit order with GTC (Good-Till-Cancel).

function executeLimitOrder(
    uint32 asset,
    bool isBuy,
    uint64 size,       // Size in 1e8 format
    uint64 price       // Exact limit price in 1e8 format
) external

With custom leverage:

function executeLimitOrder(
    uint32 asset,
    bool isBuy,
    uint64 size,
    uint64 price,
    uint32 leverage
) external

---

executeLimitOrderRaw

Execute limit order WITHOUT margin check. Use for split orders to avoid multiple L1 actions per TX.

function executeLimitOrderRaw(
    uint32 asset,
    bool isBuy,
    uint64 size,
    uint64 price
) external

Important: Caller must ensure margin is pre-transferred to L1 Perp before calling.

---

batchLimitOrders

Execute multiple limit orders in one transaction (for DCA / split orders).

function batchLimitOrders(
    uint32 asset,
    bool isBuy,
    uint64[] calldata sizes,   // Array of sizes
    uint64[] calldata prices,  // Array of prices (same length)
    uint32 leverage
) external

Limits: 1-20 orders per batch.

Example:

// Place 3 limit buy orders for SOL at different prices
const sizes = [50000000, 50000000, 50000000];  // 0.5 SOL each
const prices = [14800000000, 14900000000, 15000000000];  // $148, $149, $150

await trading.batchLimitOrders(5, true, sizes, prices, 10);

---

closePositionAdvanced

Close a position using oracle price with slippage.

function closePositionAdvanced(
    uint32 asset,
    uint32 slippageBps,  // 100-5000 (1%-50%)
    bool reduceOnly      // true = won't flip position
) external

Example:

// Close SOL position with 3% slippage
await trading.closePositionAdvanced(5, 300, true);

---

executeCloseOrderAdvanced

Close with custom size and price (for partial closes).

function executeCloseOrderAdvanced(
    uint32 asset,
    bool isBuy,          // Opposite of position direction
    uint64 size,
    uint64 price,
    bool reduceOnly
) external

---

cancelOrder

Cancel a pending limit order.

function cancelOrder(
    uint32 asset,
    uint64 oid          // Order ID from Hyperliquid API
) external

---

Fund Transfer Functions

transferToPerp

Transfer USDC from L1 Spot to L1 Perp.

function transferToPerp(uint64 amount) external  // amount in 6 decimals

transferFromPerp

Transfer USDC from L1 Perp to L1 Spot.

function transferFromPerp(uint64 amount) external  // amount in 6 decimals

sweepToSpot

Sweep all withdrawable funds from Perp to Spot.

function sweepToSpot() external

forceReturnToSpot

Force return all withdrawable from Perp to Spot (use if sweepToSpot doesn't work).

function forceReturnToSpot() external

---

View Functions

getL1Position

Get current position size for an asset.

function getL1Position(uint32 asset) external view returns (int64 szi)

Returns: Position size in szDecimals format.

• Positive = LONG

• Negative = SHORT

• For SOL (szDecimals=2): szi=150 means 1.5 SOL

getL1PositionFull

Get full position data.

function getL1PositionFull(uint32 asset) external view returns (
    int64 szi,       // Position size in szDecimals
    uint64 entryNtl  // Entry notional in 1e6
)

getL1SpotBalance

Get L1 Spot USDC balance.

function getL1SpotBalance() external view returns (uint256)  // 6 decimals

getL1AccountValue

Get L1 Perp account value (includes unrealized PnL).

function getL1AccountValue() external view returns (uint256)  // 6 decimals

getAccountMarginSummary

Get detailed margin info.

function getAccountMarginSummary() external view returns (
    int64 accountValue,   // Total account value
    uint64 marginUsed,    // Margin used by positions
    uint64 ntlPos,        // Total notional position
    int64 rawUsd          // Raw USD balance
)

getOraclePrice

Get current oracle price for an asset.

function getOraclePrice(uint32 asset) external view returns (uint64)

Format: price_USD * 10^(6-szDecimals)

getSzDecimals

Get size decimals for an asset.

function getSzDecimals(uint32 asset) external view returns (uint32)

getMaxLeverage

Get maximum leverage for an asset.

function getMaxLeverage(uint32 asset) external view returns (uint32)

previewNormalizedSize

Preview how size will be normalized (rounded).

function previewNormalizedSize(uint32 asset, uint64 size) external view returns (
    uint64 normalizedSize,  // Actual size after rounding
    uint32 szDecimals,      // Asset's szDecimals
    uint64 minSize          // Minimum valid size
)

getTotalAssets

Get total vault assets (EVM + L1 Spot + L1 Perp - Pending Sells).

function getTotalAssets() external view returns (uint256)  // 18 decimals

checkReserve

Check if EVM reserve is low.

function checkReserve() external view returns (bool isLow)

---

API Wallet Setup (Complete Flow)

Overview

AI/Bot 要交易需要完成以下步骤：

┌─────────────────────────────────────────────────────────────┐
│  Step 1: Leader 添加 API Wallet                              │
│  trading.addApiWallet(botAddress, "MyBot", 90)              │
│  → 在 EVM 上记录                                             │
│  → 自动在 L1 上注册 (ACTION_ADD_API_WALLET)                  │
├─────────────────────────────────────────────────────────────┤
│  Step 2: 设置 Builder Fee (可选，用于交易返佣)               │
│  token.approveBuilderFee(builderAddress, 50)                │
│  → 允许指定 builder 收取交易手续费返佣                        │
├─────────────────────────────────────────────────────────────┤
│  Step 3: API Wallet 可以开始交易                             │
│  trading.executeMarketOrder(...)                            │
└─────────────────────────────────────────────────────────────┘

Step 1: addApiWallet (Required)

Leader 添加 API wallet，同时在 EVM 和 L1 上注册。

function addApiWallet(
    address apiWallet,      // Bot/AI 的钱包地址
    string calldata name,   // 名称 (显示在 Hyperliquid)
    uint256 durationDays    // 60-180 天，或 0 = 永久
) external

Example:

// Leader 调用
await trading.addApiWallet(
    "0xYourBotAddress",
    "TradingBot-v1",
    90  // 90天有效期
);

权限: 仅 Leader 可调用

L1 Action: 自动发送 ACTION_ADD_API_WALLET 到 Hyperliquid

---

Step 2: approveBuilderFee (Optional)

设置交易手续费返佣（如果需要）。这是在 Token 合约 上调用，不是 Trading。

// 在 HyperFunToken 合约上
function approveBuilderFee(
    address builder,       // Builder 地址
    uint64 maxFeeRate      // Fee rate in decibps (50 = 0.05%)
) external

谁可以调用:

• Admin

• Factory Owner

• Factory 合约本身

Note: 如果 Factory 设置了 defaultBuilder，新创建的 vault 会自动 approve。

---

Step 3: API Wallet 开始交易

API Wallet 现在可以调用所有交易函数：

// API Wallet (Bot) 调用
const tradingWithBot = trading.connect(botSigner);

// 开仓
await tradingWithBot.executeMarketOrder(5, true, 100000000, price);

// 平仓
await tradingWithBot.closePositionAdvanced(5, 300, true);

---

API Wallet Management Functions

renewApiWallet

续期 API wallet（Leader only）。

function renewApiWallet(
    address apiWallet,
    uint256 durationDays   // 60-180 days, or 0 for unlimited
) external

removeApiWallet

移除 API wallet 授权（Leader only）。

function removeApiWallet(address apiWallet) external

Note: L1 上的注册无法移除（Hyperliquid 限制），但 EVM 上的检查会阻止交易。

getApiWalletStatus

获取 API wallet 状态。

function getApiWalletStatus(address apiWallet) external view returns (
    bool active,           // 是否有效
    uint256 expiresAt,     // 过期时间戳
    uint256 daysRemaining, // 剩余天数
    string memory name     // 名称
)

isApiWalletValid

检查 API wallet 是否有效。

function isApiWalletValid(address wallet) external view returns (bool)

---

Complete Setup Example

const { ethers } = require("ethers");

// Contracts
const tokenAbi = [...];   // HyperFunToken ABI
const tradingAbi = [...]; // HyperFunTrading ABI

const token = new ethers.Contract(vaultAddress, tokenAbi, leaderSigner);
const trading = new ethers.Contract(tradingAddress, tradingAbi, leaderSigner);

// Step 1: Add API Wallet (Leader)
const botAddress = "0xYourBotAddress";
await trading.addApiWallet(botAddress, "AI-Trader", 90);
console.log("API Wallet added!");

// Step 2: Approve Builder Fee (Optional, Admin/Factory Owner)
// Usually done by Factory automatically
// await token.approveBuilderFee(builderAddress, 50);

// Step 3: Verify setup
const status = await trading.getApiWalletStatus(botAddress);
console.log("Active:", status.active);
console.log("Expires:", new Date(status.expiresAt * 1000));
console.log("Days remaining:", status.daysRemaining.toString());

// Step 4: Bot can now trade
const tradingWithBot = trading.connect(botSigner);
const isValid = await tradingWithBot.isApiWalletValid(botAddress);
console.log("Bot authorized:", isValid);

// Execute trade as bot
await tradingWithBot.executeMarketOrder(5, true, 100000000, 15450000000, 10);

---

Admin Functions (Admin Only)

withdrawPerpToEVM

Withdraw USDC from L1 Perp to EVM.

function withdrawPerpToEVM(uint64 amount) external  // 6 decimals

withdrawAllPerpToEVM

Withdraw all withdrawable from L1 Perp to EVM.

function withdrawAllPerpToEVM() external

withdrawAllSpotToEVM

Send all L1 Spot USDC to EVM.

function withdrawAllSpotToEVM() external

refillReserve

Refill EVM reserve from L1 Perp.

function refillReserve(uint64 amount) external

---

Size & Price Formatting

Size Format (1e8)

All sizes are in 1e8 format (8 decimal places):

Amount	Size Value
1.0 SOL	100000000
0.5 ETH	50000000
0.001 BTC	100000

Important: Sizes are normalized based on szDecimals:

• SOL (szDecimals=2): Minimum = 0.01 SOL = 1000000

• ETH (szDecimals=4): Minimum = 0.0001 ETH = 10000

• BTC (szDecimals=5): Minimum = 0.00001 BTC = 1000

Price Format (1e8)

All prices are in 1e8 format:

Price	Price Value
$150.00	15000000000
$3000.50	300050000000
$95000.00	9500000000000

---

Events

event OrderSent(uint32 indexed asset, bool isBuy, uint64 size, uint64 price);
event OrderCancelled(uint32 indexed asset, uint64 oid);
event ApiWalletAdded(address indexed apiWallet, string name, uint256 expiresAt);
event ApiWalletRemoved(address indexed apiWallet);
event ApiWalletRenewed(address indexed apiWallet, uint256 newExpiresAt);
event FundsTransferred(bool toPerp, uint64 amount);
event WithdrawnFromL1(uint256 amount);
event Rebalanced(bool toL1, uint256 amount, uint256 newRatioBps);
event DepositedToL1(uint256 amount);
event ReserveLow(uint256 currentBalance, uint256 totalAssets);

---

Example: Full Trading Flow

const { ethers } = require("ethers");

// Connect to trading module
const tradingAbi = [...]; // Use HyperFunTrading ABI
const trading = new ethers.Contract(tradingAddress, tradingAbi, signer);

// 1. Check current position
const position = await trading.getL1Position(5);  // SOL
console.log("Current SOL position:", position.toString());

// 2. Check balances
const spotBalance = await trading.getL1SpotBalance();
const perpValue = await trading.getL1AccountValue();
console.log("L1 Spot:", spotBalance / 1e6, "USDC");
console.log("L1 Perp:", perpValue / 1e6, "USDC");

// 3. Get oracle price
const oraclePrice = await trading.getOraclePrice(5);
const szDec = await trading.getSzDecimals(5);
const priceUsd = oraclePrice / Math.pow(10, 6 - szDec);
console.log("SOL Price:", priceUsd);

// 4. Open position
const size = 100000000;  // 1.0 SOL
const price = Math.floor(priceUsd * 1.03 * 1e8);  // +3% slippage
await trading.executeMarketOrder(5, true, size, price, 10);

// 5. Close position
await trading.closePositionAdvanced(5, 300, true);  // 3% slippage

---

Error Codes

Code	Meaning
Not authorized	Caller is not leader/API wallet
Not admin	Caller is not admin
No deposits	Vault has no deposits yet
Size too small	Size below minimum for asset
No L1 position	No position to close
Slippage 1-50%	Invalid slippage value
Array length mismatch	Batch order arrays different lengths
Invalid order count	Batch must be 1-20 orders

---

Contract Version

Current: V44 (includes pending sell fix)