Ermöglicht es einem AI-Client, Perpetual Futures über mehrere DEXs zu handeln, Funding Rates zu vergleichen, Portfolios zu verwalten und Trading Bots auszuführen.
Auch bekannt als hypurrquant/perp-cli
- Stars
- 42
- Tools
- —
- Downloads, 30 Tage
- —
- Neueste Version
- —
- Letzter Commit
- 13. Nov. 2026
- Lizenz
- MIT
Was ist perp-cli MCP?
perp-cli ist ein MCP server. Ermöglicht es einem AI-Client, Perpetual Futures über mehrere DEXs zu handeln, Funding Rates zu vergleichen, Portfolios zu verwalten und Trading Bots auszuführen.
Zusammenfassung generiert aus dem README des Projekts
Über perp-cli MCP server
Der Handel mit Perpetual Futures über mehrere dezentrale Börsen hinweg ist das, was perp-cli für Entwickler und AI Agents ermöglicht. Es bietet eine einheitliche Schnittstelle zur Interaktion mit zehn verschiedenen Trading Venues, darunter Hyperliquid, Pacifica, Lighter und Aster, während es Read-only Market Data für andere wie GRVT und Variational bereitstellt. Nutzer können komplette Portfolios verwalten, Market- oder Limit-Orders ausführen und Funding Rates überwachen, um Arbitrage-Möglichkeiten zu identifizieren.
Dieser MCP server läuft lokal via stdio und ist für die Nutzung mit Clients wie Claude Desktop oder Cursor konzipiert. Während für den Abruf von Market Data keine Authentifizierung erforderlich ist, benötigen Trading- und Account-Management-Tools ein lokales Wallet-Setup über den OWS-Standard. Das System enthält eine Signing Guardrail, um die Sicherheit zu gewährleisten, wenn ein AI Agent Keys verwaltet. Es wurde nach einem Agent-First-Ansatz entwickelt und bietet strukturierte JSON-Outputs, Dry-Run-Funktionen sowie Slippage-Limits, um unbeabsichtigte finanzielle Verluste während der automatisierten Ausführung zu verhindern.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du perp-cli MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügenperp-cli MCP in Claude Code installieren
$ claude mcp add perp-cli -- npx -y perp-cliperp-cli MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}perp-cli MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"perp-cli": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}perp-cli MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"perp-cli","type":"stdio","command":"npx","args":["-y","perp-cli"]}'perp-cli MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}perp-cli MCP in Codex installieren
$ codex mcp add perp-cli -- npx -y perp-cliperp-cli MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.perp-cli] command = "npx" args = ["-y", "perp-cli"]
perp-cli MCP in Gemini CLI installieren
$ gemini mcp add -s user perp-cli npx -- -y perp-cliperp-cli MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}Automatisierte Checks
Geluften am 13. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren
- Source Repository verknüpft und erreichbarBestanden
- Open Source Lizenz (OSI)Bestanden
- Commit oder Release im letzten JahrBestanden
- Package-Name ähnelt keinem populären PackageBestanden
- Remote Endpoint nutzt HTTPSNicht geprüft
- Destruktive Tools sind markiertNicht geprüft
- Keine versteckten Anweisungen an das ModellBestanden
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenNicht geprüft
README
Auf GitHub ansehenperp-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 Fragen
Wie füge ich perp-cli MCP zu Claude Code hinzu?
Führe claude mcp add perp-cli -- npx -y perp-cli in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich perp-cli MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Benötigt der perp-cli MCP server API-Keys für Marktdaten?
Nein. Market Data Tools funktionieren ohne Keys; Account- und Trading-Tools erfordern ein vorheriges perp setup, damit der Server auf dasselbe Wallet zugreifen kann.
Wie viele MCP tools stellt perp-mcp bereit?
perp-mcp stellt 31 Tools für Claude Desktop, Cursor und andere MCP Clients bereit.
Wie konfiguriere ich den perp-cli MCP server?
Füge einen mcpServers Eintrag mit dem command npx und den args -y -p perp-cli perp-mcp hinzu. Gib niemals Private Keys in der MCP Config an.
Kann perp-cli nach Arbitrage-Möglichkeiten bei Funding Rates suchen?
Ja, es unterstützt Perp-Perp und Spot-Perp Funding Rate Scans mit einem Ein-Befehl-System für den gleichzeitigen Einstieg und Ausstieg beider Positionen.
Welche Börsen unterstützt perp-cli für den Handel?
Es handelt an 10 Venues, darunter Hyperliquid (mit HIP-3 dexes), Pacifica, Lighter, Aster, Ondo Perps, Arcus, QFEX, RISEx und TxFlow.