Hyperliquid

Hyperliquid（现货）：Hyperliquid链上订单簿的现货市场。行情与账户查询只需要钱包地址；下单、撤单、改单由API钱包（代理钱包）私钥做EIP-712签名后提交，不需要链上gas。永续合约与HIP-3、HIP-4（Outcome）品种由Futures_Hyperliquid交易所对象负责。

Futures_Hyperliquid（期货）：Hyperliquid链上订单簿的USDC保证金永续合约，包括主dex的永续、HIP-3（由builder部署的dex上的永续，代码带dex:前缀）以及HIP-4 Outcome（预测）品种。行情与账户查询只需要钱包地址；下单、撤单、改单、设置杠杆由API钱包（代理钱包）私钥做EIP-712签名后提交，不需要链上gas。现货由Hyperliquid交易所对象负责。

参考Hyperliquid 使用指南。

名称与配置

✓ 表示该交易所对象有这个配置项。

交易对与合约代码

Hyperliquid（现货）

交易对示例：HYPE_USDC、PURR_USDC

交易对写作币名_计价币，币名取Hyperliquid现货代币名（例如HYPE、PURR；跨链资产按交易所的代币名书写，如UBTC），不区分大小写。交易所内部的@1、@2这类交易对名由连接器按现货元数据换算，不需要直接使用。

Futures_Hyperliquid（期货）

交易对示例：BTC_USD、xyz:XYZ100_USD、BTC-above-100k---Dec_USD

永续合约的交易对写作币名_USD（也接受币名_USDC，返回的品种代码统一为USD），保证金是USDC，例如BTC_USD.swap。币名大小写由连接器按交易所的品种表还原（如kPEPE）。HIP-3品种的交易对带dex前缀，前缀保持小写，例如xyz:XYZ100_USD.swap。

HIP-4 Outcome品种的交易对为市场名称（空格、/换成-）加_USD，合约代码为结果方的名称，例如BTC-above-100k---Dec_USD.Yes；多个市场同名时，名称后追加-市场编号区分（如Recurring-1399_USD.Yes），只写名称会报歧义错误。可用的Outcome品种代码见exchange.GetMarkets()。

没有交割合约。Outcome品种的合约代码是结果方名称（如Yes、No），不是swap。

专属IO指令

Hyperliquid（现货）

表中长说明的其余部分：

• source：影响交易类动作Agent签名的source字段，以及转账类动作（usdSend、spotSend、withdraw3等）EIP-712签名的chainId（主网Arbitrum 42161，测试网Arbitrum Sepolia 421614）。不改变接口地址，连接测试网还需要用exchange.IO("base", "https://api.hyperliquid-testnet.xyz")切换。
• api：POST到/exchange时，参数是一个action对象，连接器自动加nonce并签名：转账类动作（usdSend、spotSend、withdraw3、usdClassTransfer、approveAgent、approveBuilderFee、userSetAbstraction）用钱包私钥WalletPrivateKey签名，动作里的hyperliquidChain等字段需要自己填写；其它动作用API钱包私钥签名。其它路径（如POST /info）原样发送，不签名。body（JSON对象或JSON字符串）给了就作为请求体（/exchange即action），否则用params作请求体；body是其它类型时报错。

通用指令base、currency见exchange.IO。

Futures_Hyperliquid（期货）

表中长说明的其余部分：

• dex：设置后，不带品种的范围查询（GetPositions()、GetOrders()、GetConditionOrders()、GetTickers()、GetMarkets()）只查这个dex，其中GetTickers()、GetMarkets()仍附带全部HIP-4 Outcome品种。空字符串清除设置，恢复默认：这些查询遍历主dex与全部HIP-3 dex汇总。带品种的调用总是按品种自身的dex前缀。设置时不检查名称是否存在，不存在的名称在之后的范围查询中报错。
• source：影响交易类动作Agent签名的source字段，以及转账类动作（usdSend、withdraw3、usdClassTransfer等）EIP-712签名的chainId（主网Arbitrum 42161，测试网Arbitrum Sepolia 421614）。不改变接口地址，连接测试网还需要用exchange.IO("base", "https://api.hyperliquid-testnet.xyz")切换；测试网没有HIP-3，范围查询只查主dex。
• split：symbol为Outcome品种代码（如BTC-above-100k---Dec_USD.Yes），写法与行情、下单相同：同名市场写带-市场编号的代码（如Recurring-1399_USD.Yes），只写名称报歧义错误；merge、mergeQuestion、negate的symbol同此规则。amount必须大于0。
• api：POST到/exchange时，参数是一个action对象，连接器自动加nonce并签名：转账类动作（usdSend、spotSend、withdraw3、usdClassTransfer、approveAgent、approveBuilderFee、userSetAbstraction）用钱包私钥WalletPrivateKey签名，动作里的hyperliquidChain等字段需要自己填写；其它动作用API钱包私钥签名。其它路径（如POST /info）原样发送，不签名。body（JSON对象或JSON字符串）给了就作为请求体（/exchange即action），否则用params作请求体；body是其它类型时报错。

通用指令base、currency见exchange.IO。

常用用法

用api查询Info接口，并查询其它地址的账户

            javascript
            
            
function main() {
    // POST /info不签名，参数对象就是请求体
    var mids = exchange.IO("api", "POST", "/info", {type: "allMids"})
    Log("BTC中间价:", mids["BTC"], "HYPE中间价:", mids["HYPE"])
    var meta = exchange.IO("api", "POST", "/info", {type: "spotMeta"})
    Log("现货代币数:", meta.tokens.length, "现货交易对数:", meta.universe.length)
    // 之后的账户、订单查询都针对这个地址（此处为HLP金库），签名下单的钱包不变；
    // 要恢复查询本账户，传回配置的钱包地址
    exchange.IO("walletAddress", "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303")
    Log("该地址的账户:", exchange.GetAccount())
    Log("该地址的挂单:", exchange.GetOrders())
}

以金库或子账户的身份交易

            javascript
            
            
function main() {
    var vault = "0x..."    // 换成金库或子账户地址
    // 之后的下单、撤单、改单以金库身份签名提交
    exchange.IO("vaultAddress", vault)
    // 查询仍使用钱包地址，查询金库的账户与订单要另外设置
    exchange.IO("walletAddress", vault)
    Log("金库账户:", exchange.GetAccount())
    var orders = exchange.GetOrders()
    for (var i = 0; i < orders.length; i++) {
        exchange.CancelOrder(orders[i].Id)
    }
    // 空字符串取消，之后又以钱包本身的身份交易
    exchange.IO("vaultAddress", "")
}

给签名动作设置过期时间

            javascript
            
            
function main() {
    // 之后的签名动作（下单、撤单、改单等）10秒后失效，晚于这个时间到达的动作被交易所拒绝
    exchange.IO("expiresAfter", Date.now() + 10 * 1000)
    var orders = exchange.GetOrders()
    for (var i = 0; i < orders.length; i++) {
        if (!exchange.CancelOrder(orders[i].Id)) {
            Log("撤单失败:", GetLastError())
        }
    }
    // 设置值一直有效，用完改回0，否则之后的动作都会被拒绝
    exchange.IO("expiresAfter", 0)
}

用api发送转账类动作：在现货与永续账户之间划转USDC

            javascript
            
            
function main() {
    // 转账类动作用配置项「钱包私钥」签名，hyperliquidChain、signatureChainId等字段由调用方填写
    var r = exchange.IO("api", "POST", "/exchange", {
        type: "usdClassTransfer",
        hyperliquidChain: "Mainnet",     // 测试网为Testnet
        signatureChainId: "0xa4b1",      // 签名链ID 42161；测试网为0x66eee（421614）
        amount: "10",                    // 字符串
        toPerp: true,                    // true：现货→永续；false：永续→现货
        nonce: Date.now()
    })
    Log(r)
}

列出HIP-3 dex，只查询其中一个dex的品种与持仓（仅Futures_Hyperliquid）

            javascript
            
            
function main() {
    // perpDexs：第一项是主dex（null），其后是各HIP-3 dex
    var dexs = exchange.IO("api", "POST", "/info", {type: "perpDexs"})
    var names = []
    for (var i = 0; i < dexs.length; i++) {
        if (dexs[i]) {
            names.push(dexs[i].name)
        }
    }
    Log("HIP-3 dex:", names.join(", "))
    // 之后不带品种的范围查询只查xyz（GetMarkets、GetTickers另外总带有HIP-4 Outcome品种）
    exchange.IO("dex", "xyz")
    var markets = exchange.GetMarkets()
    var n = 0
    for (var k in markets) {
        if (k.indexOf("xyz:") == 0) {
            n++
        }
    }
    Log("xyz的永续品种数:", n)
    Log("xyz上的持仓:", exchange.GetPositions())
    // 带品种的调用按品种自己的dex前缀，与IO("dex")无关
    Log(exchange.GetTicker("xyz:XYZ100_USD.swap"))
    // 空字符串清除设置，范围查询恢复为汇总主dex与全部HIP-3 dex
    exchange.IO("dex", "")
}

查找HIP-4 Outcome品种及其所属的问题（仅Futures_Hyperliquid）

            javascript
            
            
function main() {
    // GetMarkets()中Info.isOutcome为true的是Outcome品种，Info.outcomeId是Outcome编号
    var markets = exchange.GetMarkets()
    var byId = {}
    for (var k in markets) {
        var info = markets[k].Info
        if (info.isOutcome) {
            byId[info.outcomeId] = byId[info.outcomeId] || []
            byId[info.outcomeId].push(k)
        }
    }
    // 问题（question）由若干Outcome（namedOutcomes）加一个兜底Outcome（fallbackOutcome）组成
    var meta = exchange.IO("api", "POST", "/info", {type: "outcomeMeta"})
    Log("Outcome数:", meta.outcomes.length, "问题数:", meta.questions.length)
    var q = meta.questions[0]
    Log("问题", q.question, q.description)
    for (var i = 0; i < q.namedOutcomes.length; i++) {
        Log("Outcome", q.namedOutcomes[i], byId[q.namedOutcomes[i]])
    }
    Log("兜底Outcome", q.fallbackOutcome, byId[q.fallbackOutcome])
    var symbol = byId[q.namedOutcomes[0]][0]
    Log(symbol, exchange.GetDepth(symbol))
}

拆分、合并与取反HIP-4 Outcome头寸（仅Futures_Hyperliquid）

            javascript
            
            
function main() {
    var symbol = "BTC-above-100k---Dec_USD.Yes"    // 换成GetMarkets()中的Outcome品种代码
    // 拆分：按数量10拆出该Outcome各结果方的头寸，数量必须大于0
    var r = exchange.IO("split", symbol, 10)
    Log("split:", r ? r.status : GetLastError())
    // 合并：把各结果方的头寸合并回去，数量可以省略
    r = exchange.IO("merge", symbol, 10)
    Log("merge:", r ? r.status : GetLastError())
    // negate、mergeQuestion只用于属于某个问题的Outcome，否则报错
    r = exchange.IO("negate", symbol, 10)
    Log("negate:", r ? r.status : GetLastError())
    r = exchange.IO("mergeQuestion", symbol)
    Log("mergeQuestion:", r ? r.status : GetLastError())
}

函数支持差异

Hyperliquid（现货）

不支持（调用时报错并返回空值）：exchange.CreateConditionOrder、exchange.ModifyConditionOrder、exchange.CancelConditionOrder、exchange.GetConditionOrder、exchange.GetConditionOrders、exchange.GetHistoryConditionOrders。

以回退方式支持：

• exchange.GetRecords：原生周期为1分钟、3分钟、5分钟、15分钟、30分钟、1小时、2小时、4小时、8小时、12小时、1天、3天、1周、1月；其它周期由托管者合成。

Futures_Hyperliquid（期货）

没有不支持的标准函数。

以回退方式支持：

• exchange.GetRecords：原生周期为1分钟、3分钟、5分钟、15分钟、30分钟、1小时、2小时、4小时、8小时、12小时、1天、3天、1周；其它周期由托管者合成。Outcome品种没有K线。

保证金、账户与模拟盘

Futures_Hyperliquid（期货）

保证金模式：用exchange.IO("cross", bool)选择全仓/逐仓，在下一次exchange.SetMarginLevel()时随杠杆一起提交（交易所的updateLeverage动作）；杠杆向下取整为整数。HIP-3品种的保证金按dex分账。

持仓模式：只有单向持仓。平仓单（closebuy、closesell）以只减仓方式提交。

账户：账户为统一账户或组合保证金模式时，exchange.GetAccount()的余额与权益取现货USDC余额，未实现盈亏取永续账户；普通账户取永续账户（HIP-3按当前品种所在的dex）。余额币为USDC。

注意事项

Hyperliquid（现货）

• 市价单按中间价±0.5%作为限价、以IOC方式提交；市价买单的数量是要买入的币数，不是计价币金额。显式指定{type: "limit"}而价格不大于0时报错，不会当市价单发出。
• 下单选项放在最后一个对象参数里：{tif: "ioc"}为IOC，{postOnly: true}为只做Maker（交易所的Alo，不能用于市价单），限价单不支持fok（报错）。builder（builder费用，形如{b: builder地址, f: 整数费率}）与grouping并入下单动作一起签名，其它键被忽略。
• 价格最多5位有效数字，且小数位不超过8减去该币的数量小数位（szDecimals），整数价格总是合法。exchange.GetMarkets()的TickSize、PricePrecision按当前价格所在的量级计算，价格跨过10的整数次幂时最小变动价位随之变化，例如HYPE_USDC（szDecimals为2）在100以下为0.001，100及以上为0.01。下单、改单的价格不符合规则时直接报错，错误信息给出该价位的最小变动价位和两侧最近的合法价格，不会自动取整；市价单的保护价由连接器按规则取整。
• 订单的AvgPrice是按交易所成交记录（userFillsByTime）按订单汇总的实际成交均价，未成交为0。订单刚成交的几秒内交易所成交记录可能还没更新，这时为0（部分成交记录已更新时为已更新部分的均价），稍后再查即为准确值；交易所只保留最近10000笔成交，更早成交的订单为0。只有已成交的订单才会多查一次成交记录，查询结果会缓存。
• exchange.ModifyOrder()成功后订单ID会改变，返回值是新的订单ID。
• exchange.GetTicker()的Buy、Sell为盘口买一、卖一（一侧没有挂单时用中间价），Last、High、Low都是中间价，交易所没有24小时最高、最低价；exchange.GetTickers()的Buy、Sell也是中间价。
• exchange.GetHistoryOrders()只能取交易所返回的最近订单，不支持since参数，传入大于0的since会报错。

Futures_Hyperliquid（期货）

• 市价单按中间价±0.5%作为限价、以IOC方式提交；Outcome品种为中间价±1%（限制在0.001到0.999之间）。条件单触发后按市价执行时同样按中间价±0.5%定价。显式指定{type: "limit"}而价格不大于0时报错，不会当市价单发出。
• 下单选项放在最后一个对象参数里：{tif: "ioc"}为IOC，{postOnly: true}为只做Maker（交易所的Alo；条件单与Outcome品种的市价单使用时报错，其它市价单总是IOC），限价单不支持fok（报错）。builder（builder费用，形如{b: builder地址, f: 整数费率}）、grouping并入下单动作一起签名；orders（非空数组）整体替换连接器生成的订单腿，腿的内容由调用方按交易所格式填写；其它键被忽略。
• 价格最多5位有效数字，且小数位不超过6减去该合约的数量小数位（szDecimals），整数价格总是合法。exchange.GetMarkets()的TickSize、PricePrecision按当前价格所在的量级计算，价格跨过10的整数次幂时最小变动价位随之变化。下单、改单（含条件单的委托价）的价格不符合规则时直接报错，错误信息给出该价位的最小变动价位和两侧最近的合法价格，不会自动取整；市价单的保护价由连接器按规则取整。HIP-4 Outcome品种不做本地校验。
• 订单与条件单的AvgPrice是按交易所成交记录（userFillsByTime）按订单汇总的实际成交均价，未成交为0。订单刚成交的几秒内交易所成交记录可能还没更新，这时为0（部分成交记录已更新时为已更新部分的均价），稍后再查即为准确值；交易所只保留最近10000笔成交，更早成交的订单为0。只有已成交的订单才会多查一次成交记录，查询结果会缓存。
• 条件单支持止盈、止损，不支持OCO；止盈、止损各是一张独立的触发单。exchange.ModifyOrder()、exchange.ModifyConditionOrder()成功后订单ID会改变，返回值是新的订单ID。
• exchange.GetTicker()、exchange.GetTickers()的Last为中间价，Buy、Sell为交易所给出的买、卖冲击价（不是盘口买一、卖一，需要时用exchange.GetDepth()），High、Low也取这两个冲击价，交易所没有24小时最高、最低价。
• exchange.GetFundings()：主dex取预测资金费率（每小时结算）；HIP-3品种需要传入品种代码，返回最近24小时的资金费率记录。
• exchange.GetHistoryOrders()、exchange.GetHistoryConditionOrders()只能取交易所返回的最近订单，不支持since参数，传入大于0的since会报错。
• HIP-4 Outcome品种是现货式头寸：用买入、卖出交易（下单数量为整数），不支持只减仓，平仓单（closebuy、closesell）会报错；持仓来自现货账户中的Outcome代币。Outcome品种没有K线、资金费率，GetTicker()的Last为中间价，Buy、Sell为0。交易所还没有给出中间价的Outcome品种（刚上市、尚未成交等）仍出现在GetMarkets()中（PricePrecision为4，Info.assetCtx.midPx为null），GetTickers()不含该品种，对它调用GetTicker()或下市价单会报错；持有这种品种时，持仓按中间价0估值（Margin为0，Profit为负的买入成本）。