diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 79d1bfd..1a709cd 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -115,6 +115,17 @@ "skills": [ "./skills/thoughtproof-reasoning-check" ] + }, + { + "name": "perp-skills", + "description": "Perpetual futures trading across Hyperliquid, Pacifica, Lighter, and Aster — execute trades, run TWAP/DCA/grid bots, scan funding rate arbitrage, and view multi-exchange portfolio.", + "source": "./", + "strict": false, + "skills": [ + "./skills/perp-trade", + "./skills/perp-arb", + "./skills/perp-portfolio" + ] } ] } diff --git a/skills/perp-arb/SKILL.md b/skills/perp-arb/SKILL.md new file mode 100644 index 0000000..1ae49cb --- /dev/null +++ b/skills/perp-arb/SKILL.md @@ -0,0 +1,92 @@ +--- +name: perp-arb +description: > + Use this skill when the user asks to scan for funding rate arbitrage, find perp-perp or spot-perp arb, check funding rates across exchanges, or run a funding rate scout across Hyperliquid, Pacifica, Lighter, or Aster. +tags: [perp, arbitrage, funding-rate, hyperliquid, pacifica, lighter, aster, trading] +--- + +# Perpetual Futures Funding Rate Arbitrage + +Scan for funding rate edge across Hyperliquid, Pacifica, Lighter, and Aster, and execute delta-neutral arbitrage positions via the `perp` CLI. + +## Prerequisites + +- Install perp-cli: `npm install -g perp-cli` +- Run setup wizard: `perp setup` (configures private key + default exchange) +- Funded margin accounts on at least two exchanges (for delta-neutral arb) +- Verify: `perp account balance -e hyperliquid && perp account balance -e pacifica` + +## Commands + +```bash +# Scan funding rates across all exchanges +perp arb scan + +# Scan with live continuous monitoring +perp arb scan --live + +# Execute arb: long on exchange A, short on exchange B +perp arb exec + +# Auto-run arb daemon (finds and enters opportunities automatically) +perp arb auto + +# Check open arb positions and PnL +perp arb status + +# Close an arb position on both legs +perp arb close + +# View arb history and performance +perp arb history + +# Rebalance capital across exchanges for arb +perp arb rebalance + +# Delta-neutral funding rate farming (spot long + perp short) +perp bot delta-neutral + +# Quick-start arb bot +perp bot quick-arb +``` + +## Workflow + +1. **Scan rates** — `perp arb scan` to see current funding spreads across all exchanges +2. **Identify edge** — look for annualized spread > 5% after fees (shown in scan output) +3. **Verify liquidity** — confirm both legs have sufficient depth for your size +4. **Execute** — `perp arb exec ` enters both legs simultaneously +5. **Monitor** — `perp arb status` shows open positions with real PnL and funding earned +6. **Close** — `perp arb close ` exits both legs when spread narrows + +## Examples + +```bash +# Scan all funding rates live +perp arb scan --live + +# Execute BTC arb: long on Lighter, short on Hyperliquid, $5000 size +perp arb exec BTC lighter hyperliquid 5000 + +# Check open arb positions +perp arb status + +# Auto arb daemon +perp arb auto + +# Delta-neutral bot (spot long + perp short for funding yield) +perp bot delta-neutral +``` + +## Error Handling + +| Error | Cause | Fix | +|-------|-------|-----| +| `Insufficient margin on ` | Not enough collateral | `perp funds deposit -e ` | +| `Liquidity too thin` | Order book too shallow for size | Reduce size or use `perp arb exec` with smaller `sizeUsd` | +| `Rate flipped negative` | Funding rate changed direction | Close with `perp arb close ` | + +## Related Skills + +- [perp-trade](../perp-trade/) — execute individual trades for each arb leg +- [perp-portfolio](../perp-portfolio/) — monitor all open positions and net exposure diff --git a/skills/perp-portfolio/SKILL.md b/skills/perp-portfolio/SKILL.md new file mode 100644 index 0000000..2b3c167 --- /dev/null +++ b/skills/perp-portfolio/SKILL.md @@ -0,0 +1,90 @@ +--- +name: perp-portfolio +description: > + Use this skill when the user asks to view their perp portfolio, check positions across exchanges, see their perpetual futures balances, show open perp positions, check unrealized PnL, or get a multi-exchange perp summary across Hyperliquid, Pacifica, Lighter, or Aster. +tags: [perp, portfolio, positions, pnl, hyperliquid, pacifica, lighter, aster] +--- + +# Multi-Exchange Perpetual Futures Portfolio + +View balances, open positions, PnL, and risk metrics across all configured perp exchanges via the `perp` CLI. + +## Prerequisites + +- Install perp-cli: `npm install -g perp-cli` +- Run setup wizard: `perp setup` (configures private key + default exchange) +- Verify: `perp account balance` + +## Commands + +```bash +# Cross-exchange portfolio overview (all exchanges) +perp portfolio + +# Portfolio for specific exchanges only +perp portfolio --exchange hyperliquid,pacifica + +# Account balance on one exchange +perp account balance [-e ] + +# Open positions +perp account positions [-e ] + +# PnL summary (realized + unrealized + funding) +perp account pnl [-e ] + +# Open orders +perp account orders [-e ] + +# Funding payment history +perp account funding-history [-e ] + +# Live status dashboard: balances, positions, top arb opportunities +perp status + +# Live PnL monitoring (real-time updates) +perp trade pnl-track +``` + +## Workflow + +1. **Overview** — run `perp portfolio` for a full cross-exchange summary +2. **Drill into an exchange** — `perp account positions -e hyperliquid` for detailed positions +3. **Check PnL** — `perp account pnl` for realized + unrealized breakdown +4. **Monitor risk** — look for high margin utilization (>70%) and positions near liquidation in the output +5. **Live view** — `perp status` for a unified real-time dashboard + +## Examples + +```bash +# Full portfolio view across all exchanges +perp portfolio + +# Hyperliquid positions only +perp account positions -e hyperliquid + +# PnL breakdown +perp account pnl + +# Funding payment history +perp account funding-history + +# Live unified dashboard +perp status + +# Real-time PnL tracking +perp trade pnl-track +``` + +## Error Handling + +| Error | Cause | Fix | +|-------|-------|-----| +| `No accounts configured` | Setup not run | Run `perp setup` | +| `Connection failed for ` | RPC/API issue | Check internet and retry; exchange may be down | +| `No positions found` | No open trades | Expected — account is flat | + +## Related Skills + +- [perp-trade](../perp-trade/) — open, close, and manage positions +- [perp-arb](../perp-arb/) — scan and execute funding rate arbitrage diff --git a/skills/perp-trade/SKILL.md b/skills/perp-trade/SKILL.md new file mode 100644 index 0000000..d7b5b41 --- /dev/null +++ b/skills/perp-trade/SKILL.md @@ -0,0 +1,114 @@ +--- +name: perp-trade +description: > + Use this skill when the user wants to open, close, or manage a perpetual futures position, set up a TWAP, DCA, grid, or trailing-stop bot, or place a perp order on Hyperliquid, Pacifica, Lighter, or Aster. +tags: [perp, trade, order, twap, dca, grid, bot, hyperliquid, pacifica, lighter, aster] +--- + +# Perpetual Futures Trade Execution + +Execute trades, manage positions, and run automated bots across Hyperliquid, Pacifica, Lighter, and Aster via the `perp` CLI. + +## Prerequisites + +- Install perp-cli: `npm install -g perp-cli` +- Run setup wizard: `perp setup` (configures private key + default exchange) +- Funded margin account on target exchange (deposit USDC via `perp funds deposit`) +- Verify setup: `perp account balance` + +## Commands + +```bash +# Account overview +perp account balance [-e ] +perp account positions [-e ] + +# Pre-flight check before any trade +perp trade check + +# Market order +perp trade market [-e ] [--leverage ] + +# Shorthand +perp trade buy +perp trade sell + +# Limit order +perp trade limit + +# TWAP +perp trade twap + +# Stop / TP-SL +perp trade stop +perp trade tpsl + +# Close position +perp trade close +perp trade close-all + +# Bots +perp bot quick-dca +perp bot grid +perp bot trailing-stop +perp bot quick-grid + +# Monitor live PnL +perp trade pnl-track +``` + +## Workflow + +1. **Check account balance** — `perp account balance -e ` +2. **Run pre-flight check** — `perp trade check ` to validate margin, liquidation price, and slippage before executing +3. **Place order** — use `perp trade market` for immediate fills, `perp trade limit` for price targets, or `perp trade twap` for large orders +4. **Confirm position** — `perp account positions` to verify fill +5. **Set risk controls** — `perp trade tpsl ` for take-profit/stop-loss + +## Examples + +```bash +# Check before buying +perp trade check BTC buy 1000 -e hyperliquid + +# Market buy $1000 BTC on Hyperliquid at 5x leverage +perp trade buy BTC 1000 -e hyperliquid --leverage 5 + +# TWAP sell $10k ETH over 5 minutes on Pacifica +perp trade twap ETH sell 10000 5m -e pacifica + +# Close BTC position +perp trade close BTC -e hyperliquid + +# Start a DCA bot: buy $100 ETH every 60 seconds +perp bot quick-dca ETH buy 100 60 + +# Grid bot on SOL +perp bot quick-grid SOL -e hyperliquid +``` + +## Error Handling + +| Error | Cause | Fix | +|-------|-------|-----| +| `Insufficient margin` | Account balance too low | `perp funds deposit` to add funds | +| `Leverage too high` | Exchange limit exceeded | Lower leverage with `perp trade leverage ` | +| `Symbol not found` | Wrong ticker or exchange | Check `perp market --help` for available markets | + +## Related Skills + +- [perp-portfolio](../perp-portfolio/) — view positions and PnL across all exchanges +- [perp-arb](../perp-arb/) — scan and execute funding rate arbitrage +- [moonpay-check-wallet](../moonpay-check-wallet/) — check wallet balances before funding + +## Security & Risk + +**Leverage warning:** Leveraged positions can result in 100% loss of margin if the price moves against you. Always set a stop-loss before entering leveraged trades: +```bash +perp trade tpsl # set take-profit and stop-loss levels +``` +Start with 1x leverage (`--leverage 1`) and increase only once familiar with the platform. + +**Liquidation:** If margin utilization exceeds the exchange threshold (~80-90%), your position will be force-closed. Monitor with `perp account positions` and `perp status`. + +**Private key storage:** `perp setup` stores your private key locally (encrypted). Location varies by OS — run `perp setup --help` to see the config path. Never share your key or commit it to version control. To rotate: run `perp setup` again and overwrite.