Open Broker - Hyperliquid 交易命令行工具

在 Hyperliquid DEX 上执行交易操作，支持构建者费用。

安装

npm install -g openbroker

快速开始

# 1. Setup (generates wallet, creates config, approves builder fee)
openbroker setup

# 2. Fund your wallet with USDC on Arbitrum, then deposit at https://app.hyperliquid.xyz/

# 3. Start trading
openbroker account
openbroker buy --coin ETH --size 0.1

重要提示：交易前查找资产

交易不熟悉的资产前，务必先进行搜索。Hyperliquid 上有主流永续合约（ETH、BTC、SOL...）、HIP-3 永续合约（xyz:CL、xyz:GOLD、km:USOIL...）和现货市场。请使用搜索功能来发现正确的交易代码：

openbroker search --query GOLD              # Find all GOLD markets across all providers
openbroker search --query oil               # Find oil-related assets (CL, BRENTOIL, USOIL...)
openbroker search --query BTC --type perp   # BTC perps only
openbroker search --query NATGAS --type hip3  # HIP-3 only

或者使用ob_search插件工具：{ "query": "gold" }或{ "query": "oil", "type": "hip3" }

HIP-3 资产使用dex:COIN格式——例如，xyz:CL而不仅仅是CL。如果您遇到类似“未找到市场数据”的错误，请搜索该资产以找到正确的前缀交易代码。常见的 HIP-3 DEX：xyz,flx,km,hyna,vntl,cash.

故障排除：CLI 回退方案

如果ob_*插件工具返回意外错误、空结果或崩溃，请回退到通过 Bash 使用等效的 CLI 命令。CLI 和插件工具共享相同的核心代码，但 CLI 具有更成熟的错误处理和输出功能。

插件工具	CLI 等效命令
ob_account	openbroker account --json
ob_positions	openbroker positions --json
ob_funding	openbroker funding --json --include-hip3
ob_markets	openbroker markets --json --include-hip3
ob_search	openbroker search --query <查询内容>
ob_buy	openbroker buy --coin <币种> --size <数量>
ob_sell	openbroker sell --coin <币种> --size <数量>
ob_limit	openbroker limit --coin <币种> --side <方向> --size <数量> --price <价格>
ob_tpsl	openbroker tpsl --coin <币种> --tp <价格> --sl <价格>
ob_cancel	openbroker cancel --all或--coin <币种>
ob_fills	openbroker fills --json
ob_orders	openbroker orders --json
ob_funding_scan	openbroker funding-scan --json
ob_candles	openbroker candles --coin <币种> --json
ob_auto_run	openbroker auto run <脚本> [--dry]
ob_auto_stop	（使用命令行界面时通过发送 SIGINT 信号来停止）
ob_auto_list	openbroker auto list

何时使用命令行界面回退：

• 插件工具返回空值、空数据或抛出错误
• 你需要插件工具未暴露的数据（例如，--verbose调试输出）
• 长时间运行的操作（策略）——命令行界面能更好地处理超时和进度

在任何交易命令行界面命令中添加--dry参数可以预览而不实际执行。在信息类命令中添加--json参数可以获得结构化输出。

命令参考

设置

openbroker setup              # One-command setup (wallet + config + builder approval)
openbroker approve-builder --check  # Check builder fee status (for troubleshooting)

设置命令提供三种模式：生成全新钱包

1. （推荐用于智能体）——创建一个专用的交易钱包，并自动批准构建者费用。无需浏览器操作步骤——只需存入USDC即可开始交易。导入现有密钥
2. ——使用您已有的私钥生成API钱包
3. ——创建一个受限钱包，可以交易但无法提款。需要主钱包通过浏览器进行批准。对于选项1和2，设置过程会自动保存配置并批准构建者费用。 对于选项3（API钱包），请参阅下方的API钱包设置部分。

全新钱包设置（推荐用于智能体）

这是为智能体设置的最简单方式。生成一个全新钱包，自动批准构建者费用，智能体在资金到位后即可立即开始交易。

流程：

运行

1. openbroker setup并选择选项1（"生成全新钱包"）CLI将生成钱包，保存配置，并自动批准构建者费用
2. The CLI generates a wallet, saves the config, and approves the builder fee automatically
3. 通过从您的Hyperliquid账户向代理的钱包地址发送USDC来为该钱包注资，使用发送功能，位于https://app.hyperliquid.xyz/。注资应仅在Hyperliquid L1上进行。
4. 开始交易

API钱包设置（替代方案）

API钱包可以代表主账户进行交易，但无法提取资金。如果您希望将资金保留在现有钱包中，仅委托交易权限，请使用此方法。

流程：

1. 运行openbroker setup并选择选项3（“生成API钱包”）
2. CLI将生成一个密钥对并打印一个批准URL（例如https://openbroker.dev/approve?agent=0xABC...）
3. 代理所有者需在浏览器中打开该URL并连接其主钱包（如MetaMask等）
4. 主钱包将签署两笔交易：ApproveAgent（授权API钱包）以及ApproveBuilderFee（批准1个基点的费用）
5. CLI会自动检测授权并保存配置

设置完成后，配置文件将包含：

HYPERLIQUID_PRIVATE_KEY=0x...        # API wallet private key
HYPERLIQUID_ACCOUNT_ADDRESS=0x...    # Master account address
HYPERLIQUID_NETWORK=mainnet

对代理程序很重要：使用API钱包时，请将授权URL传递给代理程序所有者（即控制主钱包的人员）。所有者必须在浏览器中完成授权，代理程序才能进行交易。CLI会等待授权，最长等待时间为10分钟。如果超时，请重新运行openbroker setup。

账户信息

openbroker account            # Balance, equity, margin
openbroker account --orders   # Include open orders
openbroker positions          # Open positions with PnL
openbroker positions --coin ETH  # Specific coin

资金费率

openbroker funding --top 20   # Top 20 by funding rate
openbroker funding --coin ETH # Specific coin

市场列表

openbroker markets --top 30   # Top 30 main perps
openbroker markets --coin BTC # Specific coin

所有市场（永续合约 + 现货 + HIP-3）

openbroker all-markets                 # Show all markets
openbroker all-markets --type perp     # Main perps only
openbroker all-markets --type hip3     # HIP-3 perps only
openbroker all-markets --type spot     # Spot markets only
openbroker all-markets --top 20        # Top 20 by volume

搜索市场（跨提供商查找资产）

openbroker search --query GOLD    # Find all GOLD markets
openbroker search --query BTC     # Find BTC across all providers
openbroker search --query ETH --type perp  # ETH perps only

现货市场

openbroker spot                   # Show all spot markets
openbroker spot --coin PURR       # Show PURR market info
openbroker spot --balances        # Show your spot balances
openbroker spot --top 20          # Top 20 by volume

交易成交记录

openbroker fills                          # Recent fills
openbroker fills --coin ETH               # ETH fills only
openbroker fills --coin BTC --side buy --top 50

订单历史

openbroker orders                         # Recent orders (all statuses)
openbroker orders --open                  # Currently open orders only
openbroker orders --open --coin ETH       # Open orders for a specific coin
openbroker orders --coin ETH --status filled
openbroker orders --top 50

订单状态

openbroker order-status --oid 123456789   # Check specific order
openbroker order-status --oid 0x1234...   # By client order ID

费用表

openbroker fees                           # Fee tier, rates, and volume

K线数据（OHLCV）

openbroker candles --coin ETH                           # 24 hourly candles
openbroker candles --coin BTC --interval 4h --bars 48   # 48 four-hour bars
openbroker candles --coin SOL --interval 1d --bars 30   # 30 daily bars

融资历史

openbroker funding-history --coin ETH              # Last 24h
openbroker funding-history --coin BTC --hours 168  # Last 7 days

近期交易（行情记录）

openbroker trades --coin ETH              # Last 30 trades
openbroker trades --coin BTC --top 50     # Last 50 trades

速率限制

openbroker rate-limit                     # API usage and capacity

资金费率扫描器（跨交易所）

openbroker funding-scan                          # Scan all dexes, >25% threshold
openbroker funding-scan --threshold 50 --pairs   # Show opposing funding pairs
openbroker funding-scan --hip3-only --top 20     # HIP-3 only
openbroker funding-scan --watch --interval 120   # Re-scan every 2 minutes

交易指令

HIP-3 永续合约交易

所有交易指令均支持使用dex:COIN语法来交易 HIP-3 资产：

openbroker buy --coin xyz:CL --size 1              # Buy crude oil on xyz dex
openbroker sell --coin xyz:BRENTOIL --size 1        # Sell brent oil
openbroker limit --coin xyz:GOLD --side buy --size 0.1 --price 2500

市价单（快速）

openbroker buy --coin ETH --size 0.1
openbroker sell --coin BTC --size 0.01
openbroker buy --coin SOL --size 5 --slippage 100  # Custom slippage (bps)

市价单（完整）

openbroker market --coin ETH --side buy --size 0.1
openbroker market --coin BTC --side sell --size 0.01 --slippage 100

限价单

openbroker limit --coin ETH --side buy --size 1 --price 3000
openbroker limit --coin SOL --side sell --size 10 --price 200 --tif ALO

为现有持仓设置止盈/止损

# Set take profit at $40, stop loss at $30
openbroker tpsl --coin HYPE --tp 40 --sl 30

# Set TP at +10% from entry, SL at entry (breakeven)
openbroker tpsl --coin HYPE --tp +10% --sl entry

# Set only stop loss at -5% from entry
openbroker tpsl --coin ETH --sl -5%

# Partial position TP/SL
openbroker tpsl --coin ETH --tp 4000 --sl 3500 --size 0.5

触发单（独立止盈/止损）

# Take profit: sell when price rises to $40
openbroker trigger --coin HYPE --side sell --size 0.5 --trigger 40 --type tp

# Stop loss: sell when price drops to $30
openbroker trigger --coin HYPE --side sell --size 0.5 --trigger 30 --type sl

取消订单

openbroker cancel --all           # Cancel all orders
openbroker cancel --coin ETH      # Cancel ETH orders only
openbroker cancel --oid 123456    # Cancel specific order

高级执行

时间加权平均价格（原生交易所订单）

# Buy 1 ETH over 30 minutes (exchange handles slicing)
openbroker twap --coin ETH --side buy --size 1 --duration 30

# Sell 0.5 BTC over 2 hours without randomized timing
openbroker twap --coin BTC --side sell --size 0.5 --duration 120 --randomize false

# Cancel a running TWAP
openbroker twap-cancel --coin ETH --twap-id 77738308

# Check TWAP status
openbroker twap-status --active

分批建仓/平仓（网格订单）

# Place 5 buy orders ranging 2% below current price
openbroker scale --coin ETH --side buy --size 1 --levels 5 --range 2

# Scale out with exponential distribution
openbroker scale --coin BTC --side sell --size 0.5 --levels 4 --range 3 --distribution exponential --reduce

条件单（入场 + 止盈 + 止损）

# Long ETH with 3% take profit and 1.5% stop loss
openbroker bracket --coin ETH --side buy --size 0.5 --tp 3 --sl 1.5

# Short with limit entry
openbroker bracket --coin BTC --side sell --size 0.1 --entry limit --price 100000 --tp 5 --sl 2

追踪订单（跟随价格）

# Chase buy with ALO orders until filled
openbroker chase --coin ETH --side buy --size 0.5 --timeout 300

# Aggressive chase with tight offset
openbroker chase --coin SOL --side buy --size 10 --offset 2 --timeout 60

订单类型

限价单 vs 触发单

限价单(openbroker limit):

• 达到价格立即执行
• 挂单直至成交或取消
• 低于市价的限价卖单会立即成交（吃单）
• 不适用于止损

触发订单(openbroker trigger,openbroker tpsl):

• 保持休眠直到触发价格被触及
• 仅当价格达到触发水平时激活
• 设置止损和止盈的正确方式
• 不会过早成交

何时使用每种订单

场景	命令
以低于市价的特定价格买入	openbroker limit
以高于市价的特定价格卖出	开仓限价单
止损（价格下跌时退出）	openbroker trigger --type sl
止盈（在目标价位退出）	openbroker trigger --type tp
为现有持仓添加止盈/止损	openbroker tpsl

通用参数

所有命令都支持--dry用于模拟运行（预览而不实际执行）。

参数	描述
--coin	资产代码（ETH、BTC、SOL、HYPE 等）
--side	订单方向：买入或卖出
--size	订单大小（以基础资产计）
--price	限价
--dry	预览而不执行
--help	显示命令帮助

订单参数

参数	描述
--trigger	触发价格（针对触发订单）
--type	触发类型：tp或sl
--slippage	滑点容差，单位为基点（针对市价订单）
--tif	有效时间：GTC、IOC、ALO
--reduce	仅减仓订单

止盈/止损价格格式

格式	示例	描述
绝对价格	--tp 40	价格为40美元
百分比上涨	--tp +10%	高于入场价 10%
百分比下跌	--sl -5%	低于入场价 5%
入场价格	--sl 入场价	盈亏平衡止损

配置

配置按以下优先级顺序加载：

1. 环境变量
2. .env在当前目录中
3. ~/.openbroker/.env（全局配置）

运行openbroker setup以交互方式创建全局配置。

变量	必需	描述
HYPERLIQUID_PRIVATE_KEY	是	钱包私钥 (0x...)
HYPERLIQUID_NETWORK	否	主网（默认）或测试网
HYPERLIQUID_ACCOUNT_ADDRESS	否	主账户地址（API钱包必需）

构建者费用（1个基点/0.01%）是硬编码的，不可配置。

OpenClaw插件（可选）

此技能可通过Bash独立运行——上述每个命令都通过openbroker命令行界面执行。如需增强功能，同一个openbrokernpm包也提供为OpenClaw插件，您可以与此技能同时启用。

插件新增功能

• 结构化智能体工具（ob_account、ob_buy ob_limit等）——使用具有正确输入模式的类型化工具调用，而非Bash字符串。代理会收到结构化的JSON响应。后台持仓监视器
• ——每30秒轮询一次您的Hyperliquid账户，并在持仓开仓/平仓、盈亏发生显著变动或保证金使用达到危险水平时发送Webhook警报。自动化工具
• （ob_auto_run、ob_auto_stop、ob_auto_list）——可在代理内部启动、停止和管理自定义交易自动化。CLI命令
• ——openclaw ob status和openclaw ob watch用于检查监视器状态。启用插件

该插件与

openbroker捆绑在同一包中。npm 包。要在您的 OpenClaw 配置中启用它：

plugins:
  entries:
    openbroker:
      enabled: true
      config:
        hooksToken: "your-hooks-secret"   # Required for watcher alerts
        watcher:
          enabled: true
          pollIntervalMs: 30000
          pnlChangeThresholdPct: 5
          marginUsageWarningPct: 80

该插件从~/.openbroker/.env（通过openbroker setup命令设置）读取钱包凭证，因此您无需在插件配置中重复privateKey，除非您想要覆盖它。

用于监听器警报的 Webhook 设置

为了让仓位警报能够到达代理，请在您的网关配置中启用钩子：

hooks:
  enabled: true
  token: "your-hooks-secret"   # Must match hooksToken above

如果没有钩子，监听器仍会运行并跟踪状态（可通过ob_watcher_status访问），但它无法唤醒代理。

使用或不使用插件

• 仅使用技能（无插件）：使用 Bash 命令（例如openbroker buy --coin ETH --size 0.1）。无后台监控。
• 技能 + 插件：代理优先使用ob_*在工具可用时使用工具（结构化数据），对于工具未涵盖的命令（策略、规模）则回退到Bash。后台监视器会自动发送警报。

交易自动化

自动化功能允许您编写自定义的事件驱动交易逻辑，作为TypeScript脚本。您可以精确编写所需的逻辑，OpenBroker会处理轮询、事件检测和SDK访问。

重要提示：捆绑的示例仅供参考，并非现成的策略

OpenBroker随附了捆绑的自动化示例（dca、grid、funding-arb、mm-spread、mm-maker），这些示例展示了常见模式。这些示例旨在供阅读和学习，而非直接作为生产策略运行。当用户请求一个策略时（例如，"在HYPE上运行DCA"），您应该：

1. 阅读相关的捆绑示例源代码，以理解自动化API模式
2. 编写一个自定义自动化程序，根据用户的具体要求（币种、规模、阈值、风险参数、止盈/止损逻辑等）量身定制。
3. 将其保存到~/.openbroker/automations/并使用openbroker auto run

运行它。请勿直接运行openbroker auto run --example dca --set coin=HYPE

。示例使用通用默认值，缺乏真实策略所需的精细风险管理、仓位规模控制和止盈/止损逻辑。请务必编写一个专为特定目的构建的自动化程序。

openbroker auto examples    # List examples with config fields

要查看捆绑的示例及其配置模式：可用示例：dca（定投）、grid（网格）、funding-arb（资金费率套利）、mm-spread（做市价差）、

mm-maker

自动化是一个.ts文件，它导出一个默认函数。该函数接收一个AutomationAPI，其中包含完整的Hyperliquid客户端、类型化事件订阅、持久化状态和日志记录器。运行时会每10秒（可配置）轮询Hyperliquid，并在检测到变化时分发事件。

编写自动化

在~/.openbroker/automations/（或任何路径）中创建一个.ts文件：

// ~/.openbroker/automations/funding-scalp.ts
export default function(api) {
  const COIN = 'ETH';

  api.on('funding_update', async ({ coin, annualized }) => {
    if (coin !== COIN) return;

    if (annualized > 0.5 && !api.state.get('isShort')) {
      api.log.info('High positive funding — going short');
      await api.client.marketOrder(COIN, false, 0.1);
      api.state.set('isShort', true);
    } else if (annualized < -0.1 && api.state.get('isShort')) {
      api.log.info('Funding normalized — closing short');
      await api.client.marketOrder(COIN, true, 0.1);
      api.state.set('isShort', false);
    }
  });

  api.onStop(async () => {
    if (api.state.get('isShort')) {
      api.log.warn('Closing short on shutdown');
      await api.client.marketOrder('ETH', true, 0.1);
      api.state.set('isShort', false);
    }
  });
}

AutomationAPI 参考

属性 / 方法	描述
api.client	完整的 HyperliquidClient —marketOrder()、limitOrder()、triggerOrder()、cancelAll(),getUserStateAll(),getAllMids(),updateLeverage(), 以及其他35个以上的方法
api.on(event, handler)	订阅一个市场/账户事件（参见下方的事件列表）
api.every(ms, handler)	以循环间隔运行一个处理程序（与轮询循环对齐）
api.onStart(handler)	在所有处理程序注册后、首次轮询前调用
api.onStop(handler)	在关闭时调用（SIGINT）。用于清理——平仓、取消订单
api.onError(handler)	当处理程序抛出错误时调用。错误已记录——用于恢复逻辑
api.state.get(key)	获取一个持久化的值（在重启后仍然存在，存储在~/.openbroker/state/中）
api.state.set(key, value)	设置一个持久化值
api.state.delete(key)	删除一个持久化值
api.state.clear()	清除所有状态
api.publish(message, options?)	通过webhook向OpenClaw智能体发送消息。触发智能体回合——智能体接收消息并可以通知用户、采取行动等。如果送达则返回true。选项：{ name?, wakeMode?, deliver?, channel? }
api.log.info/warn/error/debug(msg)	结构化日志记录器
api.utils	roundPrice、roundSize、sleep、normalizeCoin、formatUsd年化资金费率api.id
自动化ID（文件名或	--id标志）api.dryRun
true	如果运行时带有--dry（写入方法被拦截）事件

事件

载荷	触发时机	tick
{ 时间戳, 轮询次数 }	每个轮询周期（默认：10秒）	price_change
{ 币种, 旧价格, 新价格, 变化百分比 }	轮询间中间价变动 > 0.01%	funding_update
{ 币种, 资金费率, 年化率, 溢价 }	每次轮询所有资产时	position_opened
position_opened	{ 币种, 方向, 数量, 入场价格 }	检测到新持仓
持仓已平仓	{ 币种, 先前数量, 入场价格 }	持仓不再存在
持仓已变更	{ 币种, 旧数量, 新数量, 入场价格 }	持仓数量已变更
盈亏阈值	{ 币种, 未实现盈亏, 变化百分比, 持仓价值 }	盈亏变动 > 持仓价值的5%
保证金警告	{ 已用保证金百分比, 权益, 已用保证金 }	保证金使用率 > 80%

事件详情 — 选择合适的事件

tick— 通用的心跳事件

触发每一个轮询周期（默认：10秒），无论市场状况如何。当您需要在每次轮询时检查某些内容时使用此事件 — 例如绝对价格阈值、自定义条件、定期账户检查。这是最可靠的事件，因为它总是会触发。

有效载荷： { 时间戳: 数字, 轮询计数: 数字 }

使用场景：

• 检查价格是否超过/低于绝对阈值（例如："当 ETH < 3000 美元时提醒我"）
• 不适合其他事件的自定义条件（例如："如果我没有持仓且资金费率很高，则入场"）
• 需要每次轮询都运行的周期性任务（尽管api.every()对于更长的时间间隔更合适）

示例 —— 绝对价格警报：

api.on('tick', async () => {
  const mids = await api.client.getAllMids();
  const price = parseFloat(mids['HYPE']);
  if (price < 38 && !api.state.get('alerted')) {
    api.state.set('alerted', true);
    await api.publish(`HYPE dropped below $38 — now at $${price.toFixed(3)}`);
  }
});

注意： tick事件的有效载荷中不包含价格数据 —— 你必须通过api.client.getAllMids()自行获取。这是因为 tick 事件在任何其他事件处理之前触发。如果你只关心价格变动，请改用price_change事件。

price_change—— 相对价格变动

当某个币种的中价变动≥ 0.01% 时触发与前一次轮询相比。这种方法可以过滤掉四舍五入的噪音，同时捕捉到几乎所有的真实价格变动。比较是在连续轮询之间进行的（而非基于固定基准），因此能够检测到增量变化。

载荷： { coin: 字符串, oldPrice: 数字, newPrice: 数字, changePct: 数字 }

使用场景：

• 响应价格变动（突破、动量、均值回归）
• 监控特定代币的波动性
• 构建价格触发的入场/出场逻辑

不适用场景：

• 检查价格是否高于/低于固定阈值——请改用tick事件，因为price_change事件仅在两次轮询间出现相对变动时触发。在缓慢波动期间（例如价格以$0.001/秒的速度缓慢下跌），任何两次10秒轮询间的变化可能小于0.01%，因此即使价格已超过阈值，该事件也不会触发。

示例——动量检测器：

api.on('price_change', async ({ coin, changePct, newPrice }) => {
  if (coin !== 'ETH') return;
  if (changePct > 0.5) {
    api.log.info(`ETH surging +${changePct.toFixed(2)}% — price $${newPrice}`);
    // Enter long on strong upward momentum
  }
});

funding_update——资金费率数据

触发频率每次轮询对于每一个拥有资金费率数据的资产。这是高频的——如果有150个永续合约资产，每次轮询会触发150次。在你的处理程序中根据币种进行过滤。

数据载荷： { coin: 字符串, fundingRate: 数字, annualized: 数字, premium: 数字 }

• fundingRate— 原始的小时资金费率（例如，0.0001 = 0.01%/小时）
• annualized— 年化利率（fundingRate × 8760 × 100，以百分比表示）
• premium— 溢价成分

使用场景：

• 资金费率套利策略
• 监控极端资金费率（入场/出场信号）
• 扫描所有资产中的最高/最低资金费率

示例——资金费率短线交易：

api.on('funding_update', async ({ coin, annualized }) => {
  if (coin !== 'ETH') return;
  if (annualized > 50 && !api.state.get('isShort')) {
    api.log.info(`ETH funding at ${annualized.toFixed(1)}% annualized — shorting`);
    await api.client.marketOrder('ETH', false, 0.1);
    api.state.set('isShort', true);
  }
});

position_opened— 检测到新持仓

当出现一个在上次轮询中不存在的持仓时触发。适用于跟踪其他系统建立的持仓，或确认自己的订单已成交。

载荷： { coin: 字符串, side: 'long' | 'short', size: 数字, entryPrice: 数字 }

使用时机：

• 为新仓位自动设置止盈/止损
• 当仓位开立时（由您或另一系统执行）进行记录/告警
• 启动针对特定仓位的监控

示例 — 为新仓位自动设置止盈/止损：

api.on('position_opened', async ({ coin, side, size, entryPrice }) => {
  const tpPrice = side === 'long' ? entryPrice * 1.05 : entryPrice * 0.95;
  const slPrice = side === 'long' ? entryPrice * 0.97 : entryPrice * 1.03;
  await api.client.takeProfit(coin, side !== 'long', size, tpPrice);
  await api.client.stopLoss(coin, side !== 'long', size, slPrice);
  api.log.info(`Set TP at ${tpPrice} / SL at ${slPrice} for ${coin}`);
});

仓位已关闭— 仓位已消失

当先前轮询中存在的仓位不再出现时触发。仓位可能是由您手动关闭、被强制平仓，或是因止盈/止损而平仓。

载荷： { coin: 字符串, previousSize: 数字, entryPrice: 数字 }

使用时机：

• 当仓位关闭时进行记录/告警
• 清理相关订单或状态
• 仓位关闭后的重新入场逻辑

示例：

api.on('position_closed', async ({ coin, previousSize, entryPrice }) => {
  api.log.info(`${coin} position closed (was ${previousSize} @ ${entryPrice})`);
  api.state.delete(`${coin}_tp`);
  await api.publish(`Position closed: ${coin} (entry: $${entryPrice})`);
});

仓位已变更— 仓位规模或方向发生变化

当现有持仓的规模发生变化时触发（例如部分平仓、加仓或反转方向）。当新开仓或现有持仓完全平仓时不会触发——请使用position_opened和position_closed来处理这些情况。

载荷： { coin: 字符串, oldSize: 数字, newSize: 数字, entryPrice: 数字 }

• oldSize/newSize为有符号数值：正数 = 多头，负数 = 空头

使用场景：

• 检测部分平仓或仓位规模调整
• 当持仓规模变化时调整止盈/止损
• 跟踪分批建仓操作

示例：

api.on('position_changed', async ({ coin, oldSize, newSize }) => {
  if (Math.abs(newSize) > Math.abs(oldSize)) {
    api.log.info(`${coin} position increased: ${oldSize} → ${newSize}`);
  } else {
    api.log.info(`${coin} position reduced: ${oldSize} → ${newSize}`);
  }
});

pnl_threshold——显著盈亏变动

当未实现盈亏变动达到≥ 5% 的持仓价值时触发在连续两次轮询之间。这是一个大幅波动检测器——适用于风险管理警报，而非日常监控。

载荷： { coin: string, unrealizedPnl: number, changePct: number, positionValue: number }

• changePct—— 盈亏变化占持仓总价值的百分比（而非盈亏本身的百分比）

使用场景：

• 针对大幅盈亏波动的风险警报
• 在市场突发不利波动时自动平仓或减仓
• 通过以下方式向用户发送升级警报api.publish()

示例：

api.on('pnl_threshold', async ({ coin, unrealizedPnl, changePct }) => {
  if (unrealizedPnl < 0) {
    await api.publish(
      `⚠️ ${coin} PnL dropped sharply: $${unrealizedPnl.toFixed(2)} (${changePct.toFixed(1)}% of position)`,
      { name: 'pnl-alert' },
    );
  }
});

保证金警告—— 高保证金使用率

当保证金使用率超过80%净资产时触发。首次触发后，仅当保证金使用率再增加5个百分点时才会再次触发（防止警报轰炸）。当保证金使用率回落至80%以下时重置。

载荷： { marginUsedPct: number, equity: number, marginUsed: number }

使用场景：

• 自动降低风险（关闭最小仓位以释放保证金）
• 在清算风险前提醒用户
• 保证金高时暂停新开仓

示例：

api.on('margin_warning', async ({ marginUsedPct, equity }) => {
  await api.publish(
    `🚨 Margin at ${marginUsedPct.toFixed(1)}% — equity: $${equity.toFixed(2)}. Consider reducing exposure.`,
    { name: 'margin-alert' },
  );
});

选择正确的事件 — 快速指南

使用场景	最佳事件	原因
价格突破固定水平时提醒	tick（行情更新）	每次轮询都会触发 — 无最小变化阈值
响应价格动量/波动性	price_change（价格变化）	提供轮询间的相对变化数据
资金费率策略	funding_update（资金费率更新）	直接提供年化费率
新开仓位的自动止盈/止损	position_opened（仓位已开）	新仓位出现时精确触发
记录仓位平仓	position_closed（仓位已平）	当仓位消失时触发
追踪仓位规模变化	仓位变动事件	仅在规模变化时触发
风险管理 — 盈亏大幅波动	盈亏阈值	仅在大幅波动时触发（≥仓位价值的5%）
风险管理 — 保证金	保证金警告	在保证金使用率达80%以上时触发
周期性任务（定投、再平衡）	api.every(毫秒, 函数)	对于较长间隔优于逐笔触发

可用的客户端方法

该api.client对象公开完整的HyperliquidClient。所有币种参数均接受HIP-3前缀代码（例如xyz:CL）。可选用户参数默认使用配置的钱包地址。

交易

方法	描述
marketOrder(coin, isBuy, size, slippageBps?, leverage?)	通过中间价 ± 滑点设置IOC限价单进行市价交易。返回OrderResponse
limitOrder(coin, isBuy, size, price, tif?, reduceOnly?, leverage?)	限价订单。tif：'Gtc'（默认）、'Ioc'、'Alo'。返回OrderResponse
triggerOrder(coin, isBuy, size, triggerPrice, limitPrice, tpsl, reduceOnly?, leverage?)	触发（条件）订单。tpsl：'tp'或'sl'当价格达到触发价格时激活，然后以限价执行。返回OrderResponse
stopLoss(coin, isBuy, size, triggerPrice, slippageBps?)	止损快捷方式。设置带有滑点缓冲（默认 100 bps / 1%）的限价以确保成交。reduceOnly始终为 true。返回OrderResponse
takeProfit(coin, isBuy, size, triggerPrice)	止盈快捷方式。限价 = 触发价格（有利方向）。reduceOnly始终为 true。返回OrderResponse
cancel(coin, oid)	通过数字 OID 取消单个订单。返回CancelResponse
cancelAll(coin?)	取消所有未成交订单。如果币种若提供币种参数，则仅取消该资产的订单。返回CancelResponse[]（取消响应数组）
order(币种, 买入方向, 数量, 价格, 订单类型, 仅减仓?, 包含构建器?, 杠杆?)	底层订单提交接口。订单类型：`{ limit: { tif: 'Gtc'（限价：时间条件为“Good till cancel”）

市场数据

方法	返回
getAllMids()（获取所有中间价）	Record<string, string>（记录<字符串, 字符串>）—— 所有资产（主流+HIP-3）的中间价格。键 = 币种名称，值 = 价格字符串
getMetaAndAssetCtxs()（获取元数据与资产上下文）	MetaAndAssetCtxs（元数据与资产上下文）—— 市场元数据（包含数量精度、最大杠杆等参数的资产集合）与资产上下文（资金费率、未平仓量、交易量、标记/预言机价格）
getL2Book(币种)（获取二级订单簿）	{ 买单队列, 卖单队列, 最优买价, 最优卖价, 中间价, 买卖价差, 基点价差 }— 包含计算价差的L2订单簿
获取最近交易记录（币种）	数组<{ 币种, 方向, 价格, 数量, 时间, 哈希, 交易ID }>— 最新交易记录。方向：'B'（买）或'A'（卖）
获取K线快照（币种，间隔，开始时间，结束时间？）	数组<{ 时间戳, 收盘时间, 币种, 间隔, 开盘价, 收盘价, 最高价, 最低价, 成交量, 交易笔数 }>— OHLCV K线。间隔：'1分钟'、'5分钟'、'15分钟'、'1小时'、'4小时'、'1天'. 时间为Unix毫秒
getFundingHistory(coin, startTime, endTime?)	数组<{ coin, fundingRate, premium, time }>— 历史每小时资金费率
getPredictedFundings()	数组<[coin, Array<[venue, { fundingRate, nextFundingTime }]>]>— 所有交易场所的预测资金费率
getPerpDexs()	`数组<{ name, fullName, deployer }
getAllPerpMetas()	数组<{ dexName, meta, assetCtxs }>— 每个永续合约DEX的元数据+上下文（主网 + 所有HIP-3）
getSpotMeta()	{ tokens, universe }— 现货市场元数据（代币信息，交易对）
getSpotMetaAndAssetCtxs()	{ meta, assetCtxs }— 现货元数据 + 价格/成交量上下文
getTokenDetails(tokenId)	代币详情：供应量，部署者，价格。返回null如果未找到

账户

方法	返回
获取用户所有状态（用户？）	清算所状态— 跨所有去中心化交易所的完整账户状态：保证金摘要（账户价值，总保证金使用量，可提取金额），交叉保证金摘要，以及资产持仓数组[]（每个包含持仓.币种，.持仓数量，.入场价格，.未实现盈亏，.持仓价值，.杠杆率，.已用保证金,.liquidationPx)
getUserState(user?, dex?)	ClearinghouseState— 单一交易所的账户状态（对于主要永续合约，省略dex参数）
getOpenOrders(user?)	OpenOrder[]— 所有交易所的所有未平仓订单。每条记录包含：{ coin, side, limitPx, sz, oid, timestamp, orderType }
getUserFills(user?, aggregateByTime?)	Array<{ coin, px, sz, side, time, closedPnl, fee, oid, tid, crossed, builderFee }>— 交易成交历史。side:'B'（买入）或'A'（卖出）
getHistoricalOrders(user?)	数组<{ 订单: { 币种, 方向, 限价, 数量, 原始数量, 订单标识, 时间戳, 订单类型, 有效时间, 触发条件, 触发价格, 是否已触发, 是否为持仓止盈止损, 仅减仓 }, 状态, 状态时间戳 }>— 所有订单（已成交、已取消等）
获取订单状态（订单标识, 用户?）	{ 状态, 订单? }— 通过数字订单标识或字符串客户端订单标识查询特定订单的状态
获取用户资金费率（用户?, 开始时间?, 结束时间?）	数组<{ 时间, 哈希值, 变动: { 币种, 美元稳定币, 持仓数量, 资金费率 } }>— 收取/支付的资金费用
获取用户费用（用户?）	{ 每日用户交易量, 费用表, 用户交叉费率, 用户附加费率, 活跃推荐折扣, 活跃质押折扣 }— 费用等级、费率及交易量
获取用户速率限制（用户?）	{ 累计交易量, 已使用请求数, 请求容量, 剩余请求数 }— API 速率限制状态
获取现货余额（用户?）	{ 余额: 数组<{ 币种, 代币, 冻结额, 总额, 入场净值 }> }— 现货代币余额
获取子账户（用户?）	数组<{ 子账户用户, 名称 }>— 主钱包的子账户
获取账户模式(用户?)	字符串— 账户抽象模式：'标准'、'统一'、'投资组合'或'去中心化交易所抽象'
是否为统一账户(用户?)	布尔值—真如果是统一账户或投资组合保证金（在去中心化交易所间共享USDC）

杠杆与配置

方法	描述
更新杠杆(币种, 杠杆, 是否全仓?)	设置杠杆。是否全仓默认为真（交叉保证金）。HIP-3资产被强制隔离并限制在其最大杠杆率
approveBuilderFee(maxFeeRate?, builder?)	批准构建者费用（必须从主钱包调用，而非API钱包）。默认费率：'0.1%'
getMaxBuilderFee(user?, builder?)	检查已批准的构建者费用。返回费用字符串（例如：'0.01%'）或null若未批准

实用属性

属性 / 方法	描述
getAssetIndex(coin)	获取币种的数字资产索引（内部用于订单传输）
getSzDecimals(coin)	获取币种的数量小数精度
isHip3(coin)	检查币种是否为HIP-3资产
getCoinDex(coin)	获取币种的交易所名称（null（针对主要永续合约）
getAllAssetNames()	获取所有已知资产名称（主要资产 + HIP-3资产）
getHip3AssetNames()	仅获取HIP-3资产名称
invalidateMetaCache()	强制在下一次调用时刷新市场元数据

实用函数 (api.utils)

函数	描述
roundPrice(price, szDecimals, isSpot?)	将价格四舍五入至5位有效数字（永续合约最多6位小数，现货最多8位）
roundSize(size, szDecimals)	将数量按资产特定小数精度四舍五入
sleep(ms)	基于Promise的延迟函数
normalizeCoin(coin)	标准化币种名称（大写，去除空格）
formatUsd(amount)	将数字格式化为USD字符串（例如：$1,234.56)
annualizeFundingRate(hourlyRate)	将小时资金费率转换为年化百分比

示例：价格突破

// ~/.openbroker/automations/breakout.ts
export default function(api) {
  const COIN = 'ETH';
  const BREAKOUT_PCT = 2;  // 2% move triggers entry
  const SIZE = 0.5;
  let basePrice = null;

  api.onStart(async () => {
    const mids = await api.client.getAllMids();
    basePrice = parseFloat(mids[COIN]);
    api.log.info(`Watching ${COIN} from $${basePrice} for ${BREAKOUT_PCT}% breakout`);
  });

  api.on('price_change', async ({ coin, newPrice }) => {
    if (coin !== COIN || !basePrice) return;
    const totalChange = ((newPrice - basePrice) / basePrice) * 100;

    if (Math.abs(totalChange) >= BREAKOUT_PCT && !api.state.get('inPosition')) {
      const side = totalChange > 0;  // true = long, false = short
      api.log.info(`Breakout! ${totalChange.toFixed(2)}% — entering ${side ? 'long' : 'short'}`);
      await api.client.marketOrder(COIN, side, SIZE);
      api.state.set('inPosition', true);
    }
  });
}

示例：计划定投

// ~/.openbroker/automations/hourly-dca.ts
export default function(api) {
  const COIN = 'ETH';
  const USD_PER_BUY = 100;

  // Buy $100 of ETH every hour
  api.every(60 * 60 * 1000, async () => {
    const mids = await api.client.getAllMids();
    const price = parseFloat(mids[COIN]);
    const size = parseFloat(api.utils.roundSize(USD_PER_BUY / price, 4));
    await api.client.marketOrder(COIN, true, size);
    const count = (api.state.get('buyCount') || 0) + 1;
    api.state.set('buyCount', count);
    api.log.info(`DCA #${count}: bought ${size} ${COIN} at $${price}`);
  });
}

示例：保证金守护者

// ~/.openbroker/automations/margin-guard.ts
export default function(api) {
  api.on('margin_warning', async ({ marginUsedPct, equity }) => {
    api.log.warn(`Margin at ${marginUsedPct.toFixed(1)}% — reducing positions`);

    // Close the smallest position to free margin
    const state = await api.client.getUserStateAll();
    const positions = state.assetPositions
      .filter(p => parseFloat(p.position.szi) !== 0)
      .sort((a, b) => Math.abs(parseFloat(a.position.positionValue)) - Math.abs(parseFloat(b.position.positionValue)));

    if (positions.length > 0) {
      const pos = positions[0].position;
      const size = Math.abs(parseFloat(pos.szi));
      const isBuy = parseFloat(pos.szi) < 0; // Close short = buy, close long = sell
      api.log.info(`Closing smallest position: ${pos.coin} (${pos.szi})`);
      await api.client.marketOrder(pos.coin, isBuy, size);
    }
  });
}

向代理发布消息（Webhooks）

使用api.publish()向 OpenClaw 代理发送消息。这会触发一个代理回合——代理接收消息，并可以通过用户偏好的渠道通知用户、执行交易操作或记录事件。

// Simple notification
await api.publish(`ETH broke above $4000 — current price: $${price}`);

// With options
await api.publish(`Margin at ${pct}% — positions at risk`, {
  name: 'margin-alert',           // appears in logs
  wakeMode: 'now',                // 'now' (default) or 'next-heartbeat'
  channel: 'slack',               // target channel (optional)
});

api.publish()返回true如果消息成功送达，返回false如果 Webhooks 未配置（无钩子令牌）。它要求OPENCLAW_HOOKS_TOKEN已设置（在作为 OpenClaw 插件运行时自动配置）。

示例：使用 publish 的价格警报自动化

// ~/.openbroker/automations/price-alert.ts
export default function(api) {
  const COIN = 'ETH';
  const THRESHOLD = 4000;

  api.on('price_change', async ({ coin, newPrice, changePct }) => {
    if (coin !== COIN) return;

    const crossed = api.state.get<boolean>('crossed', false);
    if (!crossed && newPrice >= THRESHOLD) {
      api.state.set('crossed', true);
      await api.publish(
        `${COIN} crossed above $${THRESHOLD}! Price: $${newPrice.toFixed(2)} (+${changePct.toFixed(2)}%)`,
      );
    } else if (crossed && newPrice < THRESHOLD) {
      api.state.set('crossed', false);
    }
  });
}

运行自动化

CLI：

openbroker auto run my-strategy --dry       # Test without trading
openbroker auto run ./funding-scalp.ts      # Run from path
openbroker auto run my-strategy --poll 5000 # Poll every 5s
openbroker auto run --example dca --set coin=HYPE --set amount=50 --dry  # Run bundled example
openbroker auto examples                    # List bundled examples with config
openbroker auto list                        # Show available scripts
openbroker auto status                      # Show running automations

插件工具（适用于OpenClaw代理）：

• ob_auto_run—{ "script": "funding-scalp", "dry": true }— 启动一个自动化流程
• ob_auto_run—{ "example": "dca", "config": { "coin": "HYPE", "amount": 50 }, "dry": true }— 运行一个捆绑的示例
• ob_auto_stop—{ "id": "funding-scalp" }— 停止一个正在运行的自动化流程
• ob_auto_list—{}— 列出可用的自动化流程、带有配置模式的捆绑示例，以及正在运行的自动化流程

选项：

标志	描述	默认值
--dry	拦截写入方法 — 不进行真实交易	false
--verbose	显示调试输出	false
--id <名称>	自定义自动化ID	文件名
--poll <毫秒>	轮询间隔（毫秒）	10000
--example <名称>	运行一个捆绑的示例自动化	-
--set 键=值	设置配置值（可重复）	-

代理编写自动化指南：

风险与安全（强制要求）：

• 始终为每个未平仓头寸附加一个强平监控自动化。订阅保证金警告和盈亏阈值事件，使用户永远不会因强平风险而措手不及。如果没有保证金/强平自动化已在运行，请在交易前创建一个。
• 使用api.publish()来通知用户重要事件——仓位开仓/平仓、止盈/止损触发、大幅盈亏波动、保证金警告、错误，以及任何需要人工关注的情况。切勿对关键事件进行静默处理。
• 务必注册一个api.onStop()处理程序以进行清理——在关闭时取消未成交订单并平仓（或至少提醒用户）。切勿遗留未处理订单或未管理仓位。
• 除非用户明确要求，否则不要使用--dry模式。自动化程序默认应以实盘模式运行。
• 在下单前务必验证是否有足够的保证金。在确定订单规模前检查账户状态。
• 根据账户净值限制仓位规模。除非用户明确指定规模，否则单笔交易的风险不应超过净值的合理百分比。
• 务必为新仓位设置止盈/止损——无论是在自动化程序内部设置，还是确认用户已设置。未受保护的仓位是一种风险。

状态与可靠性：

• 使用api.state为跟踪仓位状态、入场价格和标志位，确保它们能在重启后持续存在。切勿仅依赖内存变量——自动化程序会在网关重启后持续存在并自动重启。
• 使用幂等性防护措施（api.state.get/set）以防止重复下单。同一条件在多次轮询中可能触发多次事件——下单前务必检查状态。
• 运行时会按处理器捕获错误——一个处理器的故障不会导致其他处理器崩溃，但务必在处理器内优雅地处理预期错误（例如订单被拒、保证金不足）。

通信：

• 使用api.publish()将警报/事件发送回OpenClaw代理——请勿手动构建webhook请求。
• 在以下情况发布：仓位开立/关闭、止盈/止损触发、盈亏超过阈值、保证金警告、自动化错误以及任何自动化交易执行。用户应始终了解自动化程序做了什么及其原因。
• 在发布消息中包含可操作的上下文——币种、价格、数量、盈亏以及发生了什么——以便用户无需检查终端即可做出明智决策。

通用原则：

• 脚本从~/.openbroker/automations/按名称加载，或从任何绝对路径加载。
• 所有交易命令均支持 HIP-3 资产（api.client.marketOrder('xyz:CL', true, 1)）。
• 自动化脚本在网关重启后仍会持续运行——网关恢复时会自动重启它们。
• 对于间隔时间超过轮询周期的周期性任务，建议使用api.every(ms, fn)而非tick。

风险警告

• 请务必先使用--dry模式预览订单
• 在测试网（HYPERLIQUID_NETWORK=testnet）上从小仓位开始
• 监控仓位和强平价格
• 使用--reduce仅用于平仓

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。