hyperliquid

Hyperliquid 交易

在 Hyperliquid 上交易永续期货和现货代币。Hyperliquid 是完全链上运行的去中心化交易所。订单使用此 Agent 的 EVM 钱包签名，并直接提交至 Hyperliquid L1。

前提条件

开始交易前，钱包策略必须处于启用状态。加载 wallet-policy 技能，并提出标准的通配符策略（拒绝导出密钥 + 允许 *）。此策略涵盖所有 Hyperliquid 操作——USDC 存款、EIP-712 订单签名和提款。

运行时模型：如何调用 Hyperliquid（请先阅读）

此技能采用脚本交付模式。它不会注册任何 hl_* Agent 工具——调用 hl_deposit、hl_order 或任何其他 hl_* 名称作为工具，都会因注册表中 “未找到”而失败。这是有意设计的，并非缺陷或缺少安装。

目前恰好有两种可用方式：

方式 1 — 只读查询（exports.py）

from core.skill_tools import hyperliquid

account = hyperliquid.hl_account()
mids    = hyperliquid.hl_market()
candles = hyperliquid.hl_candles(coin="BTC", interval="1h", hours_back=24)

可查询任意钱包，不限于你自己的钱包。 所有以用户为范围的函数都接受可选的 address 参数。查询 Agent 自己的钱包时可省略该参数；要查看第三方钱包，则传入 一个 0x 地址。这使得“分析这个钱包在 Hyperliquid 上的 PnL”成为可能—— Hyperliquid 是链下订单簿，DeBank 式的链上扫描无法看到其中任何数据。

hyperliquid.hl_portfolio(address="0x1f16...")   # PnL time series
hyperliquid.hl_account(address="0x1f16...")     # their open positions

共 32 个函数，分组如下：

分组	函数
账户	hl_account hl_balances hl_total_balance hl_user_role hl_user_fees hl_rate_limit hl_sub_accounts hl_referral hl_extra_agents
PnL 和历史记录	hl_portfolio hl_fills hl_fills_by_time hl_historical_orders hl_ledger hl_funding_payments hl_twap_fills hl_vault_equities
订单	hl_open_orders hl_open_orders_full hl_order_status
市场	hl_market hl_orderbook hl_candles hl_funding hl_predicted_funding hl_meta hl_meta_ctxs hl_spot_meta hl_spot_meta_ctxs hl_perp_dexs
质押	hl_staking hl_staking_delegations hl_staking_rewards

此方式仅支持只读操作——不会写入任何数据。

回答“这个钱包的 PnL 是多少？”

hl_portfolio 返回 8 个时间窗口——day、week、month、allTime 及对应的 perp* 窗口——每个窗口都包含 accountValueHistory 和 pnlHistory，数据格式为 [epoch_ms, value] 数组。pnlHistory 会在每个窗口开始时重置为 0，因此要查看 累计 PnL，请读取 allTime。

pf = dict(hyperliquid.hl_portfolio(address=addr))
pnl = float(pf["allTime"]["pnlHistory"][-1][1])

要还原成本基础，请结合三个来源：hl_ledger（资金流入和流出——存款、提款、金库间转移）、hl_fills_by_time（每笔成交已实现的 closedPnl，每次调用最多返回 2000 条——传入最后一笔成交的 time 作为下一次调用的 start，即可翻页），以及 hl_funding_payments（支付或收到的资金费）。先检查 hl_user_role：角色为 "missing" 表示该地址从未在此交易， 这与“没有持仓”并不相同。

方式 2 — 写入操作：下单、撤单、转账、存款（client.py）

所有写入操作都通过 HyperliquidClient 执行，该类负责 EIP-712 签名流程。 它是一个异步类——每次调用都要使用 await。

from skills.hyperliquid.client import HyperliquidClient

client = HyperliquidClient()

# Deposit USDC to the Hyperliquid bridge (minimum 5 USDC)
res = await client.deposit_usdc(amount=500)

# Place an order
res = await client.place_order(
    coin="BTC", is_buy=True, size=0.001, price=95000, order_type="limit",
)

# Cancel / leverage / transfer / withdraw
await client.cancel_all("BTC")
await client.update_leverage(coin="BTC", leverage=5, is_cross=True)
await client.transfer_usd(amount=100, to_perp=True)
await client.withdraw_from_bridge(amount=50)

使用方式 2 的前提条件：钱包策略必须处于启用状态——加载 wallet-policy 技能，并提出标准的通配符策略（拒绝导出密钥

• 允许 *）。此策略涵盖存款、EIP-712 订单签名和提款。

命名说明： 本文其余部分使用操作的历史 hl_* 名称来指代操作（例如 "hl_deposit"）。 这些名称是操作标签，并非可调用的工具——始终通过上述方式 1 或方式 2 执行操作。

可用工具

账户与市场信息

工具	功能
hl_total_balance	查看可用于交易的资金（请用此工具检查余额！）
hl_account	查看未平仓头寸和未实现 PnL
hl_balances	查看代币持仓（USDC、HYPE 等）
hl_portfolio	查看随时间变化的 PnL 和账户价值——日／周／月／全部时间
hl_ledger	查看存款、取款和转账——资金流入／流出记录
hl_fills_by_time	查看日期范围内的成交记录，用于成本基础核算
hl_market	获取加密货币或股票的当前价格
hl_meta_ctxs	全市场扫描：各资产的 markPx、资金费率、OI、交易量
hl_orderbook	查看订单簿深度和流动性
hl_fills	查看近期成交记录和执行价格
hl_candles	获取价格图表（1m、5m、1h、4h、1d）
hl_funding	查看永续合约的资金费率
hl_open_orders	查看待处理订单
hl_open_orders_full	查看待处理订单及止损／止盈详情

以上所有工具均支持使用 address="0x..." 检查任意钱包，而不仅是 Agent 自己的钱包。

交易

工具	功能
hl_order	买入或卖出永续合约（加密货币／股票）
hl_spot_order	买入或卖出现货代币
hl_tpsl_order	下达止损或止盈订单
hl_leverage	设置杠杆（1x 至资产上限）
hl_cancel	取消指定订单
hl_cancel_all	取消所有未成交订单
hl_modify	修改订单价格或数量

资金

工具	功能
hl_deposit	从 Arbitrum 存入 USDC（最低 5 美元）
hl_withdraw	将 USDC 转至 Arbitrum（手续费 1 USDC，约 5 分钟）
hl_transfer_usd	在现货／永续合约账户之间转移 USDC（很少需要）

平台

工具	功能
hl_approve_builder	批准 Starchild 收取构建者费用（首次下单时自动完成）
hl_builder_status	查看构建者批准状态和已收取的奖励

---

快速开始

只需告诉 Agent 你想交易什么——它会自动处理所有事项。

示例：

User: "Buy $20 of Bitcoin with 5x leverage"
Agent: [checks balance → sets leverage → places order → reports fill]
Result: "✓ Bought 0.0002 BTC at $95,432 with 5x leverage. Position opened."

User: "Long NVIDIA with $50, 10x"
Agent: [auto-detects NVIDIA = xyz:NVDA → executes → verifies]
Result: "✓ Bought 0.25 NVDA at $198.50 with 10x leverage. Filled at $198.62."

User: "Sell my ETH position"
Agent: [checks position size → closes → reports PnL]
Result: "✓ Sold 0.5 ETH at $3,421. Realized PnL: +$12.50"

你无需：

• 了解账户模式或资金转账
• 手动检查余额（Agent 会处理）
• 计算头寸规模（Agent 会处理）
• 核实成交情况（Agent 会处理）

只需说出你的需求，其余交给 Agent 处理。

---

Agent 行为指南

🤖 作为 Agent，你应始终自动执行以下操作（绝不询问用户）：

1. 检查可用资金——每次交易前都使用 hl_total_balance 查看可用保证金总额
2. 识别资产类型——判断用户要交易的是加密货币（BTC、ETH、SOL）还是股票／RWA（NVIDIA→xyz:NVDA、TESLA→xyz:TSLA）
3. 设置杠杆——下单前始终调用 hl_leverage（除非用户明确要求不要设置）
4. 核实成交情况——下达任何订单后，立即调用 hl_fills 检查是否成交
5. 报告结果——告知用户结果：成交价格、数量及任何 PnL
6. 建议风险管理——对于杠杆头寸，提醒用户设置止损，或主动提出代为设置

🎯 用户只需说：“买入 X”或“卖出 Y”，或“用 $N 做多 Z”

🔧 你来处理：

• 当前余额（hl_total_balance）
• 资产识别（加密货币还是 RWA）
• 杠杆设置（hl_leverage）
• 订单规模（根据用户给出的金额或数量计算）
• 执行交易（hl_order）
• 核实成交情况（hl_fills）
• 向用户报告最终结果

📊 余额检查优先级：

• ✅ 使用 hl_total_balance——无论账户模式如何，均显示实际可用保证金
• ❌ 不要使用 hl_account 检查余额——即使有可用资金，也可能显示 $0
• ❌ 不要使用 hl_balances 检查保证金——它只显示现货代币

🚀 主动执行，不要被动等待：

• 不要等用户问“成交了吗？”——自动检查
• 不要问“要我检查余额吗？”——直接检查
• 不要解释账户模式——用户不关心，直接执行

---

工具使用示例

检查账户状态

hl_account()              # Default crypto perps account
hl_account(dex="xyz")     # Builder dex (RWA/stock perps) account

返回 marginSummary（accountValue、totalMarginUsed、withdrawable）和 assetPositions 数组，其中包含每个仓位的 coin、szi（带符号的数量）、entryPx、unrealizedPnl 和 leverage。

重要： Builder 永续合约（xyz:NVDA、xyz:TSLA 等）有各自独立的清算所。在交易 RWA/股票永续合约时，务必检查正确的 dex。

检查现货余额

hl_balances()

返回余额数组，其中包含 USDC 和所有现货代币的 coin、hold、total。

检查市场价格

hl_market()                  # All mid prices
hl_market(coin="BTC")        # BTC price + metadata (maxLeverage, szDecimals)

Side 参数约定（请先阅读）

所有订单工具（hl_order、hl_spot_order、hl_tpsl_order、hl_modify） 使用相同的 side 参数。使用 "buy" 或 "sell"——这是文档中列出的值，应作为默认选项。

为确保安全，这些工具也接受以下别名，避免模型猜错方向，导致杠杆订单反向操作：

• 买入类： "buy"、"B"、"bid"、"long"、"L"、1、true
• 卖出类： "sell"、"S"、"A"、"ask"、"short"、0、false

无法识别的值会导致调用失败并返回明确错误——当 side 不明确时，工具绝不会默认卖出（或买入）。这是有意为之： 在杠杆仓位上悄然反转方向，是最糟糕的失败模式。

注意：Hyperliquid 的 L1 线协议内部使用 "B" 和 "A"，但此处的工具接口使用 buy/sell。调用时坚持使用 buy/sell，就不会出错。

下达永续合约限价单

hl_order(coin="BTC", side="buy", size=0.01, price=95000)

以 $95,000 的价格下达 0.01 BTC 的 GTC 限价买单。

下达永续合约市价单

hl_order(coin="ETH", side="sell", size=0.1)

省略 price 时，会以中间价 +/- 3% 的滑点提交 IoC 订单。

参数格式行为：

• 首选：传入正确的 JSON 类型（size 为数字，reduce_only 为布尔值）
• Hyperliquid 工具现在会对常见的 LLM 格式错误进行宽容转换：
  • 数字字符串，例如 "0.01" → 0.01
  • 布尔字符串，例如 "true"/"false" → true/false
  • 整数字符串，例如 "5"/"5.0" → 5
• 无效、空或非有限值仍会触发明确的验证错误

下达仅做市订单

hl_order(coin="BTC", side="buy", size=0.01, price=94000, order_type="alo")

ALO（仅添加流动性）即仅挂单。如果订单会立即成交，则会被拒绝。

机器人的实用防护措施： 如果 ALO 价格过于接近中间价（流动性较好的交易对通常在 0.1% 以内），Hyperliquid 可能会拒绝订单。对于做市/网格机器人，请先计算当前中间价，并跳过或调整落在不允许交叉缓冲区内的价格档位。

下达止损单

hl_tpsl_order(coin="BTC", side="sell", size=0.01, trigger_px=90000, tpsl="sl")

如果价格跌至 $90,000，则自动卖出 0.01 BTC。触发后以市价单执行。

触发时改为限价单（而非市价单）：

hl_tpsl_order(coin="BTC", side="sell", size=0.01, trigger_px=90000, tpsl="sl", is_market=false, limit_px=89900)

下达止盈单

hl_tpsl_order(coin="ETH", side="sell", size=0.5, trigger_px=3500, tpsl="tp")

如果价格涨至 $3,500，则自动卖出 0.5 ETH。触发后以市价单执行。

平掉永续合约仓位

hl_order(coin="BTC", side="sell", size=0.01, reduce_only=true)

使用 reduce_only=true 可确保订单只会平仓，不会建立新仓位。

下达现货订单

hl_spot_order(coin="HYPE", side="buy", size=10, price=25.0)

现货订单使用相同的接口，只需指定代币名称。

取消订单

hl_cancel(coin="BTC", order_id=12345678)

从 hl_open_orders 获取 order_id。

取消所有订单

hl_cancel_all()              # Cancel everything
hl_cancel_all(coin="BTC")    # Cancel only BTC orders

修改订单

hl_modify(order_id=12345678, coin="BTC", side="buy", size=0.02, price=94500)

设置杠杆

hl_leverage(coin="BTC", leverage=10)               # 10x cross margin
hl_leverage(coin="ETH", leverage=5, cross=false)    # 5x isolated margin

转账 USDC（很少需要）

hl_transfer_usd(amount=1000, to_perp=true)     # Spot → Perp
hl_transfer_usd(amount=500, to_perp=false)      # Perp → Spot

注意：通常不需要——资金会自动共享。只有在收到要求转账的错误时才使用。

将 USDC 提现至 Arbitrum

hl_withdraw(amount=100)                              # Withdraw to own wallet
hl_withdraw(amount=50, destination="0xABC...")        # Withdraw to specific address

费用：Hyperliquid 会扣除 1 USDC。处理时间约为 5 分钟。

从 Arbitrum 存入 USDC

hl_deposit(amount=500)

将 USDC 从 Agent 的 Arbitrum 钱包发送至 Hyperliquid 桥接合约。最低存款额：5 USDC。需要在 Arbitrum 上持有 USDC 余额。

获取 K 线

hl_candles(coin="BTC", interval="1h", lookback=48)

时间间隔：1m、5m、15m、1h、4h、1d。回溯时长以小时为单位。

检查资金费率

hl_funding()                 # All predicted fundings
hl_funding(coin="BTC")       # BTC predicted + 24h history

获取近期成交记录

hl_fills(limit=10)

---

Coin 与 RWA 的解析

当用户要求交易某个代码时，需要判断它是原生加密货币永续合约（使用普通名称），还是 RWA/股票永续合约（使用 xyz:TICKER 前缀）。

决策流程

1. 已知加密货币 → 使用普通名称："BTC"、"ETH"、"SOL"、"DOGE"、"HYPE" 等。
2. 已知股票／大宗商品／外汇 → 使用 xyz: 前缀："xyz:NVDA"、"xyz:TSLA"、"xyz:GOLD" 等。
3. 不确定 → 通过工具调用确认：
   • 首先尝试 hl_market(coin="X")——如果返回价格，则它是加密货币永续合约
   • 如果未找到，尝试 hl_market(dex="xyz") 列出所有 RWA 市场并搜索结果
   • 使用返回匹配项的调用方式

常见 RWA 类别（均使用 xyz: 前缀）

类别	示例
美国股票	xyz:NVDA、xyz:TSLA、xyz:AAPL、xyz:MSFT、xyz:AMZN、xyz:GOOG、xyz:META、xyz:TSM
大宗商品——金属	xyz:GOLD、xyz:SILVER、xyz:COPPER、xyz:PLATINUM、xyz:PALLADIUM、xyz:ALUMINIUM
大宗商品——能源	xyz:CL（WTI）、xyz:BRENTOIL、xyz:NATGAS、xyz:TTF（欧盟天然气）
大宗商品——农产品	xyz:CORN、xyz:WHEAT
大宗商品——其他	xyz:URANIUM
指数	xyz:SPY
外汇	xyz:EUR、xyz:GBP、xyz:JPY

如果用户说“买入 NVDA”或“交易 GOLD”，请使用 xyz:NVDA／xyz:GOLD。这些是现实世界资产，不是加密货币。

⚠️ HIP-3 大宗商品价格查询

全部 13 个大宗商品市场都是由 HIP-3 构建者部署的永续合约。 它们的代码使用 xyz: 前缀（例如 xyz:GOLD、xyz:CL），而不是 XAU、XAG 或 WTI 之类的标准格式。

完整大宗商品列表： GOLD、SILVER、COPPER、PLATINUM、PALLADIUM、ALUMINIUM、CL（WTI 原油）、BRENTOIL、NATGAS、TTF（欧盟天然气）、CORN、WHEAT、URANIUM。

重要注意事项： HIP-3 资产不包含在 allMids（标准价格源）中。这意味着：

• hl_market(coin="xyz:GOLD") 可能不会返回价格，也可能无法找到该资产
• hl_market(dex="xyz") 会列出所有构建者市场，但可能不包含中间价

获取大宗商品价格的可靠方式是使用 hl_candles：

# Get latest gold price (use 1h candles, lookback=24 for 24h data)
hl_candles(coin="xyz:GOLD", interval="1h", lookback=24)

# Get latest copper price
hl_candles(coin="xyz:COPPER", interval="1h", lookback=24)

# Get latest silver price
hl_candles(coin="xyz:SILVER", interval="1h", lookback=24)

最新一根 K 线的 close 字段即为当前价格。最早一根 K 线的 open 与最新一根 K 线的 close 可用于计算 24 小时涨跌幅。

带前缀名称——使用相同工具

所有现有工具都支持 xyz:TICKER——只需传入带前缀的币种名称：

hl_market(coin="xyz:NVDA")                                    # Check NVIDIA stock perp price
hl_market(dex="xyz")                                           # List ALL available RWA/stock perps
hl_orderbook(coin="xyz:NVDA")                                 # Check liquidity
hl_leverage(coin="xyz:NVDA", leverage=3)                      # Set leverage (auto-isolated)
hl_order(coin="xyz:NVDA", side="buy", size=0.5, price=188)    # Limit buy 0.5 NVDA
hl_order(coin="xyz:TSM", side="buy", size=1)                  # Market buy 1 TSM
hl_cancel(coin="xyz:NVDA", order_id=12345678)                 # Cancel order

示例：用户说“买入 NVIDIA”

1. 判断 NVIDIA 是股票 → 使用 xyz:NVDA
2. hl_market(coin="xyz:NVDA")——检查当前价格和杠杆限制
3. hl_leverage(coin="xyz:NVDA", leverage=3)——设置杠杆（构建者永续合约使用逐仓保证金）
4. hl_order(coin="xyz:NVDA", side="buy", size=0.5, price=188)——下达限价买单
5. hl_fills()——检查是否成交

注意事项

• 构建者永续合约（HIP-3）仅使用逐仓保证金——hl_leverage 会自动处理
• dex 前缀（例如 xyz）用于标识部署该永续合约的构建者
• 所有工具（K 线、订单簿、资金费率等）对带前缀名称的使用方式都相同

---

常见工作流

查询大宗商品价格

用户：“黄金价格是多少？”或“显示大宗商品价格”或“油价是多少？”

名称 → 代码映射：

• 金属：GOLD→xyz:GOLD、SILVER→xyz:SILVER、COPPER→xyz:COPPER、PLATINUM→xyz:PLATINUM、PALLADIUM→xyz:PALLADIUM、ALUMINIUM→xyz:ALUMINIUM
• 能源：WTI／原油→xyz:CL、布伦特原油→xyz:BRENTOIL、天然气→xyz:NATGAS、欧盟天然气→xyz:TTF
• 农产品：玉米→xyz:CORN、小麦→xyz:WHEAT
• 其他：铀→xyz:URANIUM

步骤：

1. 使用上表将大宗商品名称映射为 HIP-3 代码
2. hl_candles(coin="xyz:GOLD", interval="1h", lookback=24)——获取过去 24 小时的小时 K 线
3. 当前价格 = 最新一根 K 线的 close
4. 24 小时涨跌幅 = (last_close - first_open) / first_open * 100
5. 按需对每种大宗商品重复操作

不要对大宗商品使用 hl_market()——HIP-3 资产不在 allMids 中。始终使用 hl_candles。

流动性提示： CL（WTI）和 BRENTOIL 的成交量最高。ALUMINIUM、URANIUM、CORN、WHEAT、TTF 的流动性可能为零或非常低——交易这些品种前，请提醒用户。

交易加密货币永续合约（BTC、ETH、SOL 等）

用户：“买入 BTC”或“以 5 倍杠杆做多 ETH”

Agent 工作流：

1. hl_total_balance() → 检查可用资金
2. hl_leverage(coin="BTC", leverage=5) → 设置杠杆
3. hl_order(...) → 下单
4. hl_fills() → 确认成交并报告结果

交易股票/RWA（NVIDIA、TESLA、GOLD 等）

用户：“买入 NVIDIA”或“做空 TESLA”

Agent 工作流：

1. 检测资产类型 → 将“NVIDIA”转换为“xyz:NVDA”
2. hl_total_balance() → 检查可用资金
3. hl_leverage(coin="xyz:NVDA", leverage=10) → 设置杠杆
4. hl_order(coin="xyz:NVDA", ...) → 下单
5. hl_fills() → 确认成交并报告结果

平仓

用户：“平掉我的 BTC 仓位”

Agent 工作流：

1. hl_account() → 获取当前仓位大小
2. hl_order(coin="BTC", side="sell", size=X, reduce_only=true) → 平仓
3. hl_fills() → 报告盈亏

网格/做市机器人循环（服务模式）

对于在 FastAPI/工作进程服务中持续运行的机器人：

1. 通过 get_open_orders(address) 读取未完成订单
2. 通过 get_user_fills(address) 读取成交记录
3. 将成交记录作为“订单已执行”事件的事实来源
4. 成交时：
   • 买入成交 → 在下一个网格价位挂配对卖单
   • 卖出成交 → 在上一个网格价位挂配对买单
5. 定期进行对账：本地状态与交易所未完成订单

**重要提示：**不要将“订单从未完成订单中消失”视为订单必定已成交。这也可能意味着订单已取消、被拒绝或已过期。务必通过 get_user_fills 确认（必要时使用 get_order_status）。

现货交易

用户：“买入 100 个 HYPE 代币”

Agent 工作流：

1. hl_total_balance() → 检查可用 USDC
2. hl_spot_order(coin="HYPE", side="buy", size=100) → 买入代币
3. hl_balances() → 确认买入

充值/提现

充值： 用户：“向 Hyperliquid 充值 500 美元 USDC” Agent：hl_deposit(amount=500) → 完成

提现： 用户：“向我的 Arbitrum 钱包提现 100 美元” Agent：hl_withdraw(amount=100) → 完成（5 分钟，手续费 1 USDC）

---

订单类型

类型	参数	行为
限价单（GTC）	order_type="limit"	挂在订单簿上，直到成交或取消
市价单（IoC）	省略 price	立即成交，否则取消，按中间价 +/- 3% 滑点执行
只挂单（ALO）	order_type="alo"	如果订单会跨越买卖价差，则拒绝
立即成交或取消	order_type="ioc" + 显式价格	按指定价格立即成交，否则取消
止损	使用 tpsl="sl" 的 hl_tpsl_order	价格下跌时触发，以限制亏损
止盈	使用 tpsl="tp" 的 hl_tpsl_order	价格上涨时触发，以锁定收益

---

止损和止盈订单

止损和止盈订单是触发订单，当市场达到指定价格时会自动执行。使用这些订单可管理风险并锁定利润，无需全天候监控仓位。

工作原理

1. 下单：挂出带有触发价格的休眠触发订单
2. 监控：订单保持未激活状态，监视市场价格
3. 触发：当市场价格达到 trigger_px 时，订单激活
4. 执行：订单立即执行（作为市价单或限价单）

止损（SL）

适用场景：当价格走势对你不利时自动退出，以限制仓位亏损。

示例：你以 95,000 美元做多 BTC，希望在价格跌破 90,000 美元时退出。

hl_tpsl_order(coin="BTC", side="sell", size=0.1, trigger_px=90000, tpsl="sl")

• trigger_px=90000：BTC 跌至 90,000 美元时触发
• side="sell"：平掉你的多头仓位
• tpsl="sl"：将此订单标记为止损单
• 默认行为：触发时作为市价单执行（立即退出）

止盈（TP）

用例：当价格达到目标利润时自动平仓，锁定收益。

示例：你以 3,000 美元做多 ETH，并希望在 3,500 美元时止盈。

hl_tpsl_order(coin="ETH", side="sell", size=1.0, trigger_px=3500, tpsl="tp")

• trigger_px=3500：ETH 涨至 3,500 美元时触发
• side="sell"：平掉多头仓位
• tpsl="tp"：标记为止盈订单
• 默认：触发时按市价单执行（立即平仓）

市价与限价执行

默认情况下，TP/SL 订单会在触发时按市价单执行（立即成交，但可能产生滑点）。

如需更精细地控制，可在触发时使用限价单：

hl_tpsl_order(
    coin="BTC",
    side="sell",
    size=0.1,
    trigger_px=90000,
    tpsl="sl",
    is_market=false,
    limit_px=89900
)

• trigger_px=90000：在 90,000 美元时触发
• is_market=false：使用限价单（而非市价单）
• limit_px=89900：触发时的限价（89,900 美元）

权衡：限价单可避免滑点，但在快速波动的市场中可能无法成交。

空头仓位

对于空头仓位，需要反转 side 参数：

空头止损（价格上涨时退出）：

hl_tpsl_order(coin="BTC", side="buy", size=0.1, trigger_px=98000, tpsl="sl")

空头止盈（价格下跌时退出）：

hl_tpsl_order(coin="BTC", side="buy", size=0.1, trigger_px=92000, tpsl="tp")

最佳实践

1. 始终使用 reduce_only=true（默认值）——确保 TP/SL 只平仓，不会开新仓
2. 使数量与仓位匹配——TP/SL 数量应等于或小于仓位数量
3. 同时设置止盈和止损——保护上行收益（止盈）和下行风险（止损）
4. 考虑波动性——止损不要设得太紧，否则正常的价格波动也会触发
5. 检查未结订单——使用 hl_open_orders 确认 TP/SL 订单处于有效状态

常见错误

错误	问题	解决方案
方向错误	SL 买入而不是卖出	多头仓位 → SL/TP 使用 side="sell"
数量过大	TP/SL 开立新仓位	将 size 设为 ≤ 仓位数量，并使用 reduce_only=true
将触发价设为限价	混淆价格含义	trigger_px = 激活时机，limit_px = 执行价格
杠杆仓位未设止损	存在强平风险	杠杆仓位务必设置止损

---

永续合约与现货

方面	永续合约	现货
工具	hl_order	hl_spot_order
杠杆	支持（最高可达资产上限）	不支持
资金费率	每小时支付/收取	无
做空	支持（原生）	必须持有代币才能卖出
查看仓位	hl_account	hl_balances

---

风险管理

• 交易前务必检查账户状态——了解保证金使用情况和已有仓位
• 开立新仓位前明确设置杠杆（默认值可能有所不同）
• 平仓时使用 reduce_only，避免意外开立反向仓位
• 监控资金费率——正资金费率较高时，持有多头的成本较高
• 从小额开始——Hyperliquid 的每种资产都有最低订单数量（查看 szDecimals）
• Post-only（ALO）订单可节省手续费（做市与吃单费率）
• 市价单后检查成交情况——IoC 订单可能部分成交，也可能完全无法成交

---

建造者代码（平台费用）

Starchild 会对通过此技能下达的每笔永续合约和现货订单自动收取 2 bps（0.02%）的建造者费用。此费用用于支持平台运营，与 Hyperliquid 自身的交易费用分开计算。

工作原理：

• 用户首次下单时，技能会通过 ApproveBuilderFee 操作自动批准 Starchild 建造者地址（由用户的主钱包签名）
• 后续所有订单都会包含 builder 参数：{"b": "0x2c5320F40305fFC933385c6DCec5493fbA7b98b8", "f": 20}（20 个十分之一基点 = 2 bps）
• 费用以计价资产／抵押资产（USDC）收取，并累积到建造者的推荐奖励中
• 用户可随时在 app.hyperliquid.xyz 撤销批准

工具：

• hl_approve_builder — 手动批准 Starchild 建造者（通常会在首次下单时自动完成）
• hl_builder_status — 检查批准状态并查看未领取的建造者奖励

**如果建造者批准失败：**订单仍会在不带建造者参数的情况下提交。错误会被记录，但不会阻止交易。

---

常见错误

错误	解决方法
"Unknown perp asset"	检查币种名称。加密货币："BTC"、"ETH"。股票："xyz:NVDA"、"xyz:TSLA"
"Insufficient margin"	使用 hl_total_balance 检查资金。减小仓位或增加 USDC
"Order must have minimum value of $10"	增加仓位。公式：size × price ≥ $10
"Size too small"	BTC 的最小值通常为 0.001。检查资产的 szDecimals
"Order would cross"	ALO 订单被拒绝。改用普通限价单
"User or wallet does not exist"	先使用 hl_deposit(amount=500) 存入 USDC
"Minimum deposit is 5 USDC"	Hyperliquid 要求每笔存款至少为 $5
"Policy violation"	加载 wallet-policy 技能并提议通配符策略
"Action disabled when unified account is active"	统一模式下（默认）转账受阻。直接下单即可
"'side' must be one of: buy/sell ..."	传入了无法识别的方向。请使用 "buy" 或 "sell"。参见上文的 Side Parameter Convention