Permet à un client IA de trader des contrats à terme perpétuels sur plusieurs DEX, de comparer les taux de financement, de gérer des portefeuilles et de lancer des bots de trading.
Aussi connu sous hypurrquant/perp-cli
- Étoiles
- 42
- Outils
- —
- Téléchargements, 30 jours
- —
- Dernière version
- —
- Dernier commit
- 13 nov. 2026
- Licence
- MIT
Qu'est-ce que perp-cli MCP ?
perp-cli est un serveur MCP. Permet à un client IA de trader des contrats à terme perpétuels sur plusieurs DEX, de comparer les taux de financement, de gérer des portefeuilles et de lancer des bots de trading.
Résumé généré à partir du README du projet
À propos du MCP server perp-cli
Le trading de contrats à terme perpétuels sur plusieurs plateformes d'échange décentralisées est ce que perp-cli permet aux développeurs et aux agents IA. Il fournit une interface unifiée pour interagir avec dix plateformes de trading différentes, incluant Hyperliquid, Pacifica, Lighter et Aster, tout en offrant des données de marché en lecture seule pour d'autres comme GRVT et Variational. Les utilisateurs peuvent gérer des portefeuilles complets, exécuter des ordres au marché ou à cours limité, et surveiller les taux de financement pour identifier des opportunités d'arbitrage.
Ce MCP server s'exécute localement via stdio et est conçu pour être utilisé avec des clients comme Claude Desktop ou Cursor. Bien que la récupération des données de marché ne nécessite aucune authentification, les outils de trading et de gestion de compte requièrent une configuration de portefeuille local utilisant le standard OWS. Le système inclut une protection de signature pour garantir la sécurité lorsqu'un agent IA gère des clés. Il est conçu avec une approche orientée agent, fournissant des sorties JSON structurées, des capacités de simulation (dry-run) et des limites de slippage pour prévenir toute perte financière involontaire lors de l'exécution automatisée.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Comment installer perp-cli MCP
Formats vérifiés le 10 nov. 2026Ajouter à CursorAjouter à GooseInstaller perp-cli MCP dans Claude Code
$ claude mcp add perp-cli -- npx -y perp-cliInstaller perp-cli MCP dans Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}Installer perp-cli MCP dans VS Code
.vscode/mcp.json
{
"servers": {
"perp-cli": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}Installer perp-cli MCP dans VS Code CLI
$ code --add-mcp '{"name":"perp-cli","type":"stdio","command":"npx","args":["-y","perp-cli"]}'Installer perp-cli MCP dans Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}Installer perp-cli MCP dans Codex
$ codex mcp add perp-cli -- npx -y perp-cliInstaller perp-cli MCP dans Codex config.toml
~/.codex/config.toml
[mcp_servers.perp-cli] command = "npx" args = ["-y", "perp-cli"]
Installer perp-cli MCP dans Gemini CLI
$ gemini mcp add -s user perp-cli npx -- -y perp-cliInstaller perp-cli MCP dans Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"perp-cli": {
"command": "npx",
"args": [
"-y",
"perp-cli"
]
}
}
}Vérifications automatisées
Exécuté le 13 nov. 2026Rapport complet →A passé nos vérifications automatisées. Il ne s'agit pas d'un audit de sécurité : lisez le code et donnez au serveur l'accès le plus restreint dont il a besoin. Fonctionnement des vérifications
- Dépôt source lié et accessibleRéussi
- Licence open source (OSI)Réussi
- Commit ou version publiée au cours de l'année écouléeRéussi
- Nom du package non proche d'un package populaireRéussi
- L'endpoint distant utilise HTTPSNon vérifié
- Les outils destructifs sont étiquetésNon vérifié
- Aucune instruction cachée destinée au modèleRéussi
- Aucun avis critique dans le package ou ses dépendancesNon vérifié
README
Voir sur GitHubperp-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
Questions sur perp-cli MCP
Comment ajouter perp-cli MCP à Claude Code ?
Exécutez claude mcp add perp-cli -- npx -y perp-cli dans votre terminal. Ajoutez --scope user pour le rendre disponible dans tous les projets.
Comment ajouter perp-cli MCP à Cursor ?
Ouvrez ~/.cursor/mcp.json et ajoutez le serveur sous mcpServers, avec la configuration Cursor indiquée dans la section d'installation ci-dessus.
Le MCP server perp-cli nécessite-t-il des clés API pour les données de marché ?
Non. Les outils de données de marché fonctionnent sans clés ; les outils de compte et de trading nécessitent d'effectuer d'abord la configuration perp afin que le serveur puisse lire le même portefeuille.
Combien d'outils MCP perp-mcp expose-t-il ?
perp-mcp fournit 31 outils à Claude Desktop, Cursor et d'autres clients MCP.
Comment configurer le MCP server perp-cli ?
Ajoutez une entrée mcpServers avec la commande npx et les arguments -y -p perp-cli perp-mcp. Ne placez jamais de clés privées dans la configuration MCP.
perp-cli peut-il scanner les opportunités d'arbitrage de taux de financement ?
Oui, il prend en charge les scans de taux de financement perp-perp et spot-perp avec une entrée et une sortie sur deux jambes en une seule commande.
Quelles plateformes perp-cli prend-il en charge pour le trading ?
Il permet de trader sur 10 plateformes, dont Hyperliquid (avec les DEX HIP-3), Pacifica, Lighter, Aster, Ondo Perps, Arcus, QFEX, RISEx et TxFlow.