Perp Cli

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

perp-cli

さまざまな DEX の無期限先物を扱う CLI です。ターミナルから取引、資金調達率の比較、資金移動、ボットの実行ができ、AI エージェントに任せることもできます（JSON 出力、MCP サーバー、エージェントスキル）。

• 8 つの取引所で取引： Hyperliquid（HIP-3 dexes を含む）、Pacifica、Lighter、Lighter RH、Aster、Ondo Perps、Arcus、QFEX（ブリッジと無期限先物間のアービトラージは、Pacifica、Hyperliquid、Lighter、Aster の元の 4 つに対応）
• 市場データのみ： 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

このパッケージには 3 つの実行ファイルが含まれています。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ボルトウォレットの作成またはインポート、取引所の選択、エージェントキーの登録を行います（署名の前には必ず確認し、資金を移動することはありません）。

perp setup
perp wallet show

キーは非表示のプロンプトまたは stdin から読み込まれます。argv や ~/.perp/.env から読み込まれることはありません。1 つの EVM キーで Hyperliquid、Lighter、Aster を利用できます。他の方法（1 行でのキーインポート、スクリプトから実行可能なセットアップ、取引所のウェブサイトで作成したキー）については、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 エージェントスキル

Claude Code、Cursor、Codex、Gemini CLI、その他のエージェント CLI にすぐ導入できるスキルです。非対話型コマンドガイド、運用プレイブック、戦略フレームワーク、再利用可能なシェルスクリプト（事前チェック、アービトラージ監視、検証）が含まれています。エージェントが適切な確認ポイントで停止し、対話型ウィザードで行き詰まらないようにします。

インストール

# 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	エージェント向けのトップレベルガイド — ルール、ワークフロー、例
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	実行前の検証（価格／残高／リスク／ドライラン）

エージェント向けガイドの詳細は、skills/perp-cli/SKILL.mdをご覧ください。

機能

• 資金調達率アービトラージ — 無期限先物間および現物と無期限先物のスキャン、ワンコマンドでの両建てエントリーと決済
• ポートフォリオ — 1 回の呼び出しで、すべての取引所の残高、ポジション、リスクを取得
• 資金 — 入金、出金、送金、複数プロバイダー対応のブリッジ（CCTP / Relay / deBridge）、取引所間のリバランス
• ボット — TWAP、グリッド、DCA、トレーリングストップなどに対応し、バックグラウンドジョブも管理
• エージェント優先 — --json、--fields、--ndjson、--dry-run、実行時のスキーマイントロスペクション
• 安全性 — 取引前の検証、すべての成行注文に対するスリッページ上限、クライアント ID による重複排除、レスポンスのサニタイズ

取引所

取引所	-e	取引	チェーン／担保
Hyperliquid	hyperliquid (hl)	✅	HyperEVM、USDC；HIP-3 dexes は --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；暗号資産＋株式／FX
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	価格、オーダーブック、ファンディング、ローソク足、HIP-3 dexes
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	マルチウォレット管理、エージェントウォレット（wallet agent ...）、ビルダーフィー（wallet builder ...、デフォルトでは無効）、証拠金モード／サブアカウント／API キー（wallet manage ...）、オンチェーン残高
history	約定ログ、PnL、パフォーマンスの内訳
portfolio	取引所横断の統合概要（旧 account balance ／ status ／ dashboard を置き換え；account balance --address は任意のアカウントの残高を読み取り、キー不要）
health	アダプターのヘルスチェック：すべての取引所の REST エンドポイントに ping を実行（接続性＋レイテンシ）
settings	CLI 設定（紹介、デフォルト、手数料、ビルダーフィー、deBridge アフィリエイト）
backtest	戦略のバックテスト
background	バックグラウンドプロセスの管理（戦略、アラートなどの tmux セッション）
alerts	バックグラウンドデーモンを使ったファンディングレートアラート（Telegram ／ Discord）
setup	セットアップウィザード：OWS ウォレット、取引所、エージェントウォレット、スリッページ、デフォルトの取引所（エイリアス：init；スクリプトでは --non-interactive）

エージェント優先の CLI 設計

エージェント優先の 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 をご覧ください。

ドキュメント

ドキュメント	内容
セットアップ	ウォレット、エージェントキー、取引所のウェブサイトで作成したキー、シークレットの保存場所
取引所	サポート状況一覧、取引所 ID、QFEX / RISEx / GRVT / Extended / Variational / TxFlow / Derive の詳細
取引	有効期限、TP/SL、ストップ、注文編集、スリッページ、現物取引、ビルダーフィー
コマンド	各コマンドグループの例、Telegram アラート
メインネットの検証	取引所ごとに、実際の資金を使って実行した内容
MCP サーバー	設定、テストネット、ツール、リソース、プロンプト
署名ガードレール	エージェントキー向けの OWS ポリシー実行ファイル perp-guardrail
テスト	テストスイートと取引所チェックリスト
変更履歴	リリースノート

ライセンス

MIT