Perp Cli

English | 한국어 | 中文 | 日本語

perp-cli

一个适用于多个 DEX 的永续合约 CLI——可在终端交易、比较资金费率、转移资金和运行机器人，也可交由 AI Agent 使用（JSON 输出、MCP 服务、Agent 技能）。

• 在 8 个平台交易： Hyperliquid（包括 HIP-3 DEX）、Pacifica、Lighter、Lighter RH、Aster、Ondo Perps、Arcus、QFEX（桥接和永续合约间套利支持最初的四个平台：Pacifica、Hyperliquid、Lighter、Aster）
• 仅提供市场数据： RISEx、GRVT、Extended、Variational、TxFlow（非官方 API）——另提供 Derive 期权数据

安装

npm install -g perp-cli
perp --version

# Or without a global install
npx -y perp-cli --json portfolio

该软件包提供三个可执行文件：perp（CLI）、perp-mcp（MCP 服务，stdio）和 perp-guardrail（签名防护机制）。

快速开始

1. 先了解一下——无需密钥。

perp -e hl market list                  # markets, prices, funding
perp -e hl market book BTC              # order book
perp arb scan --rates                   # funding rates across venues

2. 添加钱包。 设置向导会创建或导入加密的 OWS Vault 钱包、选择平台并注册 Agent 密钥（每次签名前都会询问，且绝不会转移资金）：

perp setup
perp wallet show

密钥通过隐藏提示或 stdin 读取——绝不会从 argv 或 ~/.perp/.env 读取。一个 EVM 密钥即可用于 Hyperliquid、Lighter 和 Aster。其他方式（单行密钥导入、可脚本化设置、在交易所网站创建密钥）请参阅 docs/setup.md。

3. 查看账户并交易。 在任意命令中添加 -n testnet 即可使用测试网。

perp --json portfolio                                 # balances + positions + risk on every venue
perp --json --dry-run -e hl trade market BTC buy 0.001   # validate only, nothing is sent
perp --json -e hl trade market BTC buy 0.001          # market order (bounded by the slippage setting)
perp --json -e hl trade close BTC

AI Agent 技能

可直接用于 Claude Code、Cursor、Codex、Gemini CLI 和其他 Agent CLI 的技能。它包含非交互式命令指南、运维手册、策略框架和可复用的 Shell 脚本（预检、套利监控、验证），帮助 Agent 在适当的确认步骤停下，避免卡在交互式向导中。

安装

# Claude Code — slash command
/install-skill hypurrquant/perp-cli

# Cursor / Codex / generic agent CLIs — via npx
npx skills add hypurrquant/perp-cli

# Manual install (any agent that reads a Skills directory)
git clone https://github.com/hypurrquant/perp-cli.git
cp -R perp-cli/skills/perp-cli ~/.claude/skills/        # or your CLI's skills dir

该技能包含在 npm 软件包中（perp-cli/skills/perp-cli），因此全局安装后也可在本地使用：

npm install -g perp-cli@latest
ls "$(npm root -g)/perp-cli/skills/perp-cli"

技能内容

文件	用途
SKILL.md	Agent 顶层指南——规则、工作流、示例
references/commands.md	完整的非交互式命令参考（所有命令组）
references/agent-operations.md	设置流程、幂等性、错误处理、常见错误
references/strategies.md	资金费率套利决策框架 + 风险管理
scripts/preflight.sh	安装 + 钱包 + 连通性 + 风险准备情况检查
scripts/arb-monitor.sh	开放套利仓位的实时监控
scripts/spot-perp-scan.sh	扫描现货 + 永续合约机会，并结合余额信息
scripts/funding-analysis.sh	跨交易所资金费率概览 / 按币种深入分析
scripts/validate-arb.sh	执行前验证（价格 / 余额 / 风险 / 模拟运行）

完整的 Agent 指南请参阅 skills/perp-cli/SKILL.md。

功能

• 资金费率套利 — 永续合约间及现货与永续合约间的扫描，一条命令即可双腿开仓和平仓
• 投资组合 — 一次调用即可获取所有平台的余额、仓位和风险信息
• 资金 — 存款、取款、转账、多提供商桥接（CCTP / Relay / deBridge）、交易所间再平衡
• 机器人 — TWAP、网格、DCA、移动止损等，支持后台任务管理
• Agent 优先 — --json、--fields、--ndjson、--dry-run、运行时架构自省
• 安全 — 交易前验证、每笔市价单都设有滑点上限、客户端 ID 去重、响应清理

交易平台

交易平台	-e	交易	链 / 抵押品
Hyperliquid	hyperliquid (hl)	✅	HyperEVM、USDC；通过 --dex 指定 HIP-3 dex
Pacifica	pacifica (pac)	✅	Solana、USDC
Lighter	lighter (lt)	✅	Ethereum L2、USDC
Lighter RH	lighter-rh (lrh)	✅	Robinhood chain、USDG
Aster	aster (ast)	✅	BNB Chain、USDT / USDC
Ondo Perps	ondo	✅	链下、USDC
Arcus	arcus	✅（访问需加入白名单）	Robinhood chain、USDG
QFEX	qfex (qf)	✅（仅支持手动交易）	托管式；股票、指数、大宗商品
RISEx	risex	只读	RISE chain、USDC
GRVT	grvt	仅市场数据	USDT
Extended	extended (ext)	仅市场数据	Starknet；加密货币 + 股票 / 外汇
Variational	variational (var)	仅市场数据	RFQ 交易平台
TxFlow	txflow (txf)	仅市场数据	非官方 API
Derive	derive	仅期权数据	—

• 支持矩阵和各交易平台说明 — 资金费率、WebSocket、充值 / 提现、按地址查询、受限地区
• 主网验证 — 已使用真实资金运行过的功能
• 交易详情 — 有效期、TP/SL、止损、滑点、现货交易、构建者费用

常用命令

# Market data
perp --json -e <EX> market list | book <SYM> | funding <SYM> | kline <SYM> 1h

# Trading
perp --json -e <EX> trade buy <SYM> <SIZE> --tp <PX> --sl <PX>    # entry protected by TP/SL
perp --json -e <EX> trade limit <SYM> buy <PX> <SIZE>
perp --json -e <EX> trade close <SYM>                              # or: flatten (every position)

# Account
perp --json portfolio
perp --json -e <EX> account positions
perp --json account balance --address <ADDR>                       # any account, keyless

# Funding arb
perp --json arb scan --min 5
perp --json arb exec <SYM> <longEx> <shortEx> <USD>

# Funds
perp --json funds deposit hyperliquid 100
perp --json funds bridge send --from solana --to arbitrum --amount 100

包含所有分组的完整列表：docs/commands.md。全局标志：--json、--fields <f>、--ndjson、--dry-run、-n testnet、-e <venue>、--dex <name>（HIP-3）、-w, --wallet <name>。

命令分组

分组	描述
market	价格、订单簿、资金费率、K 线、HIP-3 dex
account	余额、持仓、订单、保证金
trade	市价 / 限价 / 止损订单、平仓、加仓、拆分执行
outcome	Hyperliquid Outcome（HIP-4）— 二元 / 区间合约，按结果报价（outcomeMeta quoteToken，目前为 USDC），不提供杠杆
options	期权市场数据，只读（Derive：-e derive options underlyings / expiries / chain / quote）
print	Pacifica Print — 挂出赚取每周期权利金的行权订单：游戏、报价、持仓、历史记录、事件、充值 / 取消（--dry-run）
vault	Pacifica 金库（API：lakes）— 列表、信息、持仓、充值（仅限主钱包）/ 提现（--dry-run）
arb	资金费率套利 — 扫描、执行、平仓、监控（永续合约-永续合约和现货-永续合约）
strategy	19 种机器人算法（网格、DCA、TWAP、APEX、REFLECT、预设）+ 嵌套脚本计划
funds	充值、提现、转账、跨链桥接（多服务提供方）、交易所间再平衡
risk	风险限额、清算距离、风险防护
wallet	多钱包管理、Agent 钱包（wallet agent ...）、构建者费用（wallet builder ...，默认关闭）、保证金模式 / 子账户 / API 密钥（wallet manage ...）、链上余额
history	执行日志、PnL、绩效细分
portfolio	跨交易所统一概览（取代原有的 account balance / status / dashboard；account balance --address 可免密钥读取任意账户的余额）
health	适配器健康检查：ping 每个交易平台的 REST 端点（连通性 + 延迟）
settings	CLI 设置（推荐、默认值、费用、构建者费用、deBridge 联盟计划）
backtest	策略回测
background	后台进程管理器（用于策略、提醒等的 tmux 会话）
alerts	资金费率提醒（Telegram / Discord），支持后台守护进程
setup	设置向导：OWS 钱包、交易平台、Agent 钱包、滑点、默认交易平台（别名：init；脚本可使用 --non-interactive）

Agent 优先的 CLI 设计

根据 Agent 优先的 CLI 原则 构建：

# Every command returns structured JSON envelope
perp --json portfolio
# → { "ok": true, "data": {...}, "meta": { "timestamp": "..." } }

# Filter output to specific fields (saves tokens)
perp --json --fields totalEquity,risk portfolio

# Stream large lists as NDJSON (one JSON per line)
perp --json --ndjson -e hl market list

# Pre-validate before executing
perp --json -e hl trade check BTC buy 0.01
perp --json --dry-run -e hl trade market BTC buy 0.01

# Idempotent orders with client ID (Hyperliquid: a 128-bit cloid, 0x + 32 hex; --auto-id generates one)
perp --json -e hl trade market BTC buy 0.01 --client-id 0x1234567890abcdef1234567890abcdef
perp --json -e hl trade status c:0x1234567890abcdef1234567890abcdef

所有响应都会自动清理（剥离控制字符，阻止提示词注入模式）。 错误包含 retryable 标志 — 仅当其值为 true 时重试。

MCP 服务

perp-mcp 为 Claude Desktop、Cursor 和其他 MCP 客户端提供 31 个工具。市场数据无需密钥；如需使用账户和交易工具，请先运行 perp setup（服务会读取同一个钱包）。切勿将私钥放入 MCP 配置中。

{
  "mcpServers": {
    "perp-cli": {
      "command": "npx",
      "args": ["-y", "-p", "perp-cli", "perp-mcp"]
    }
  }
}

有关测试网、完整工具列表、资源和提示词，请参阅：docs/mcp.md。

文档

文档	内容
设置	钱包、Agent 密钥、在交易所网站上创建的密钥、密钥的存储位置
交易场所	支持矩阵、交易场所 ID、QFEX / RISEx / GRVT / Extended / Variational / TxFlow / Derive 详情
交易	有效时间、TP/SL、止损单、订单修改、滑点、现货交易、构建者费用
命令	各命令组及示例、Telegram 提醒
主网验证	各交易场所使用真实资金运行过的内容
MCP 服务	配置、测试网、工具、资源、提示词
签名防护	perp-guardrail，用于 Agent 密钥的 OWS 策略可执行文件
测试	测试套件和交易场所检查清单
更新日志	发布说明

许可证

MIT