AI 클라이언트가 여러 DEX에서 무기한 선물 거래를 수행하고, 펀딩비를 비교하며, 포트폴리오 관리 및 트레이딩 봇을 실행할 수 있도록 지원합니다.
다른 이름 hypurrquant/perp-cli
- 스타
- 42
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 13일
- 라이선스
- MIT
perp-cli MCP란?
perp-cli은(는) MCP server입니다. AI 클라이언트가 여러 DEX에서 무기한 선물 거래를 수행하고, 펀딩비를 비교하며, 포트폴리오 관리 및 트레이딩 봇을 실행할 수 있도록 지원합니다.
프로젝트 README에서 생성된 요약
perp-cli MCP server 정보
perp-cli는 개발자와 AI 에이전트가 여러 탈중앙화 거래소에서 무기한 선물을 거래할 수 있게 해줍니다. Hyperliquid, Pacifica, Lighter, Aster를 포함한 10개의 서로 다른 거래소와 상호작용할 수 있는 통합 인터페이스를 제공하며, GRVT 및 Variational과 같은 다른 거래소의 읽기 전용 시장 데이터도 제공합니다. 사용자는 전체 포트폴리오를 관리하고, 시장가 또는 지정가 주문을 실행하며, 펀딩비를 모니터링하여 차익거래 기회를 식포할 수 있습니다.
이 MCP server는 stdio를 통해 로컬에서 실행되며 Claude Desktop 또는 Cursor와 같은 클라이언트와 함께 사용하도록 설계되었습니다. 시장 데이터 조회에는 인증이 필요하지 않지만, 트레이딩 및 계정 관리 도구는 OWS 표준을 사용하는 로컬 지갑 설정이 필요합니다. 시스템에는 AI 에이전트가 키를 관리할 때 보안을 보장하기 위한 서명 가드레일이 포함되어 있습니다. 에이전트 우선 방식으로 구축되어 구조화된 JSON 출력, dry-run 기능, 자동 실행 중 의도치 않은 금융 손실을 방지하기 위한 슬리피지 제한을 제공합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
perp-cli MCP 설치 방법
형식 확인: 2026년 11월 10일Cursor에 추가Goose에 추가Claude Code에 perp-cli MCP 설치
$ claude mcp add perp-cli -- npx -y perp-cliCursor에 perp-cli MCP 설치
~/.cursor/mcp.json
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}VS Code에 perp-cli MCP 설치
.vscode/mcp.json
{
"servers": {
"perp-cli": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}VS Code CLI에 perp-cli MCP 설치
$ code --add-mcp '{"name":"perp-cli","type":"stdio","command":"npx","args":["-y","perp-cli"]}'Claude Desktop에 perp-cli MCP 설치
claude_desktop_config.json
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}Codex에 perp-cli MCP 설치
$ codex mcp add perp-cli -- npx -y perp-cliCodex config.toml에 perp-cli MCP 설치
~/.codex/config.toml
[mcp_servers.perp-cli] command = "npx" args = ["-y", "perp-cli"]
Gemini CLI에 perp-cli MCP 설치
$ gemini mcp add -s user perp-cli npx -- -y perp-cliGemini settings.json에 perp-cli MCP 설치
~/.gemini/settings.json
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}자동 검사
2026년 11월 13일에 실행됨전체 보고서 →자동 검사를 통과했습니다. 이는 보안 감사가 아닙니다. 코드를 직접 읽고 서버에 필요한 최소한의 권한만 부여하십시오. 검사 방식
- 소스 저장소 연결 및 접근 가능통과
- 오픈 소스 라이선스 (OSI)통과
- 최근 1년 내 커밋 또는 릴리스통과
- 패키지 이름이 인기 패키지와 유사하지 않음통과
- 원격 엔드포인트가 HTTPS 사용검사되지 않음
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 모델에 대한 숨겨진 지침 없음통과
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
README
GitHub에서 보기perp-cli
One CLI for perpetual futures across many DEXs — trade, compare funding, move funds and run bots from the terminal, or hand it to an AI agent (JSON output, MCP server, agent skill).
- Trade on 10 venues: Hyperliquid (incl. HIP-3 dexes), Pacifica, Lighter, Lighter RH, Aster, Ondo Perps, Arcus, QFEX, RISEx, TxFlow (bridge and perp-perp arb cover the original four: Pacifica, Hyperliquid, Lighter, Aster)
- Market data only: GRVT, Extended, Variational — plus Derive options data
Install
npm install -g perp-cli
perp --version
# Or without a global install
npx -y perp-cli --json portfolio
The package ships three executables: perp (the CLI), perp-mcp (the MCP server, stdio) and perp-guardrail (the signing guardrail).
Quick start
1. Look around — no keys needed.
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. Add a wallet. The setup wizard creates or imports an encrypted OWS vault wallet, picks venues and registers agent keys (it asks before every signature and never moves funds):
perp setup
perp wallet show
Keys are read from a hidden prompt or stdin — never from argv or ~/.perp/.env. One EVM key covers Hyperliquid, Lighter and Aster. For other paths (one-line key import, scriptable setup, keys created on the exchange website) see docs/setup.md.
3. Check your account and trade. Add -n testnet to any command to use 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 Skill
Drop-in skill for Claude Code, Cursor, Codex, Gemini CLI, and other agent CLIs. Bundles a non-interactive command guide, ops playbook, strategy framework, and reusable shell scripts (preflight, arb monitor, validation) so your agent stops at the right confirmation points and never wedges on interactive wizards.
Install
# 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
The skill ships inside the npm package (perp-cli/skills/perp-cli), so a global install also makes it available locally:
npm install -g perp-cli@latest
ls "$(npm root -g)/perp-cli/skills/perp-cli"
What's in the skill
| File | Purpose |
|---|---|
SKILL.md |
Top-level agent guide — rules, workflows, examples |
references/commands.md |
Full non-interactive command reference (every group) |
references/agent-operations.md |
Setup flows, idempotency, error handling, common mistakes |
references/strategies.md |
Funding-arb decision framework + risk management |
scripts/preflight.sh |
Install + wallet + connectivity + risk readiness check |
scripts/arb-monitor.sh |
Live monitor for open arb positions |
scripts/spot-perp-scan.sh |
Scan spot+perp opportunities with balance context |
scripts/funding-analysis.sh |
Cross-exchange funding overview / per-symbol drilldown |
scripts/validate-arb.sh |
Pre-execution validation (price / balance / risk / dry-run) |
See skills/perp-cli/SKILL.md for the full agent guide.
Features
- Funding rate arb — perp-perp and spot-perp scans, one-command dual-leg entry and exit
- Portfolio — one call returns balances, positions and risk across every venue
- Funds — deposit, withdraw, transfer, multi-provider bridge (CCTP / Relay / deBridge), inter-exchange rebalance
- Bots — TWAP, grid, DCA, trailing stop and more, with background job management
- Agent-first —
--json,--fields,--ndjson,--dry-run, runtime schema introspection - Safety — pre-trade validation, a slippage bound on every market order, client-id deduplication, response sanitization
Venues
| Venue | -e |
Trading | Chain / collateral |
|---|---|---|---|
| Hyperliquid | hyperliquid (hl) |
✅ | HyperEVM, USDC; HIP-3 dexes via --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 |
✅ | off-chain, USDC |
| Arcus | arcus |
✅ (access whitelist) | Robinhood chain, USDG |
| QFEX | qfex (qf) |
✅ (manual trading only) | custodial; equities, indices, commodities |
| RISEx | risex |
✅ (manual trading only; mainnet not yet verified) | RISE chain, USDC |
| GRVT | grvt |
market data only | USDT |
| Extended | extended (ext) |
market data only | Starknet; crypto + equities / FX |
| Variational | variational (var) |
market data only | RFQ venue |
| TxFlow | txflow (txf) |
✅ (manual trading only; mainnet not yet verified, whitelist) | official API (Beta), USDC |
| Derive | derive |
options data only | — |
- Support matrix and per-venue notes — funding, WebSocket, deposit / withdraw, lookups by address, restricted regions
- Mainnet verification — which features have been run with real money
- Trading details — time in force, TP/SL, stops, slippage, spot trading, builder fees
Common commands
# 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
Full list with every group: docs/commands.md. Global flags: --json, --fields <f>, --ndjson, --dry-run, -n testnet, -e <venue>, --dex <name> (HIP-3), -w, --wallet <name>.
Command Groups
| Group | Description |
|---|---|
market |
Prices, orderbook, funding, klines, HIP-3 dexes |
account |
Balance, positions, orders, margin |
trade |
Market/limit/stop orders, close, scale, split execution |
outcome |
Hyperliquid Outcome (HIP-4) — binary/range contracts, quoted per outcome (outcomeMeta quoteToken, USDC today), no leverage |
options |
Options market data, read-only (Derive: -e derive options underlyings / expiries / chain / quote) |
print |
Pacifica Print — strike orders earning a premium per cycle: games, quote, positions, history, events, deposit / cancel (--dry-run) |
vault |
Pacifica vaults (API: lakes) — list, info, positions, deposit (master wallet only) / withdraw (--dry-run) |
arb |
Funding rate arb — scan, exec, close, monitor (perp-perp & spot-perp) |
strategy |
19 bot algorithms (grid, dca, twap, APEX, REFLECT, presets) + nested scripted plans |
funds |
Deposit, withdraw, transfer, cross-chain bridge (multi-provider), inter-exchange rebalance |
risk |
Risk limits, liquidation distance, guardrails |
wallet |
Multi-wallet management, agent wallets (wallet agent ...), builder fees (wallet builder ..., off by default), margin mode / subaccount / API keys (wallet manage ...), on-chain balances |
history |
Execution log, PnL, performance breakdown |
portfolio |
Cross-exchange unified overview (replaces former account balance / status / dashboard; account balance --address reads any account's balances, keyless) |
health |
Adapter health check: ping every venue's REST endpoint (connectivity + latency) |
settings |
CLI settings (referrals, defaults, fees, builder fees, deBridge affiliate) |
backtest |
Strategy backtesting |
background |
Background process supervisor (tmux sessions for strategies, alerts, etc.) |
alerts |
Funding rate alerts (Telegram / Discord) with background daemon |
setup |
Setup wizard: OWS wallet, venues, agent wallets, slippage, default venue (alias: init; --non-interactive for scripts) |
Agent-First CLI Design
Built following agent-first CLI principles:
# 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
All responses are auto-sanitized (control chars stripped, prompt injection patterns blocked).
Errors include retryable flag — only retry when true.
MCP Server
perp-mcp serves 31 tools to Claude Desktop, Cursor and other MCP clients. Market data needs no keys; for account and trading tools run perp setup first (the server reads the same wallet). Never put private keys in the MCP config.
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": ["-y", "-p", "perp-cli", "perp-mcp"]
}
}
}
Testnet, the full tool list, resources and prompts: docs/mcp.md.
Documentation
| Doc | What's in it |
|---|---|
| Setup | Wallets, agent keys, keys created on the exchange website, where secrets are stored |
| Venues | Support matrix, venue ids, QFEX / RISEx / GRVT / Extended / Variational / TxFlow / Derive details |
| Trading | Time in force, TP/SL, stops, order edit, slippage, spot trading, builder fees |
| Commands | Every command group with examples, Telegram alerts |
| Mainnet verification | What has been run with real money, per venue |
| MCP server | Configuration, testnet, tools, resources, prompts |
| Signing guardrail | perp-guardrail, the OWS policy executable for agent keys |
| Testing | Test suites and the venue checklist |
| CHANGELOG | Release notes |
License
MIT
perp-cli MCP 질문
perp-cli MCP를 Claude Code에 추가하려면 어떻게 하나요?
터미널에서 claude mcp add perp-cli -- npx -y perp-cli를 실행합니다. 모든 프로젝트에서 사용할 수 있게 하려면 --scope user를 추가합니다.
perp-cli MCP를 Cursor에 추가하려면 어떻게 하나요?
~/.cursor/mcp.json를 열고 mcpServers 아래에 서버를 추가합니다. 위 설치 섹션에 표시된 Cursor 구성을 사용합니다.
perp-cli MCP server를 사용하려면 시장 데이터용 API 키가 필요한가요?
아니요. 시장 데이터 도구는 키 없이 작동합니다. 계정 및 트레이딩 도구는 서버가 동일한 지갑을 읽을 수 있도록 먼저 perp setup을 실행해야 합니다.
perp-mcp는 몇 개의 MCP 도구를 제공하나요?
perp-mcp는 Claude Desktop, Cursor 및 other MCP 클라이언트에 31개의 도구를 제공합니다.
perp-cli MCP server를 어떻게 설정하나요?
command npx와 args -y -p perp-cli perp-mcp를 포함한 mcpServers 항목을 추가하세요. MCP 설정에 개인 키를 절대 입력하지 마세요.
perp-cli로 펀딩비 차익거래 기회를 스캔할 수 있나요?
네. 명령어 하나로 양방향 진입 및 청산이 가능한 perp-perp 및 spot-perp 펀딩비 스캔을 지원합니다.
perp-cli가 지원하는 거래소는 어디인가요?
Hyperliquid (HIP-3 dex 포함), Pacifica, Lighter, Aster, Ondo Perps, Arcus, QFEX, RISEx, TxFlow를 포함한 10개 거래소에서 거래할 수 있습니다.