diff --git a/CHANGELOG.md b/CHANGELOG.md index c349003..5b9b527 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,24 @@ catch up if you are on an older skill version — apply the entries above yours The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and the skills follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [7.10.0] — targets CLI v7.3.0 + +### Added + +- `mm perps vault list`, `mm perps vault info`, `mm perps vault deposit`, and `mm perps vault withdraw` in `references/perps.md` for Hyperliquid vaults. The docs cover the 1 USDC minimum, the deposit lock period and `lockedUntilTimestamp`, and that `--dry-run` only validates flags. +- `mm perps account mode get` and `mm perps account mode set` in `references/perps.md` for switching between standard and unified Hyperliquid accounts. `set` has no `--dry-run` and changes the whole Hyperliquid account. +- `--vault
` on `mm perps open`, `close`, `modify`, `cancel`, `positions`, `orders`, and `balance` to trade or read on behalf of a vault. Deposits, withdrawals, and spot to perp transfers are not available with `--vault`. +- `--tif` with `gtc`, `ioc`, or `alo` on `mm perps open` and `mm perps quote`. `gtc` and `alo` need a limit order. +- `--reduce-only` on `mm perps open`, with matching guidance in `workflows/perps-open-position.md`. +- `INVALID_TIF`, `REDUCE_ONLY_REJECTED`, and `ALREADY_SET_ACCOUNT_MODE` in `references/errors.md`, and troubleshooting rows for those plus vault lock and vault deposit balance failures. +- SKILL.md routing rows for the vault and account mode commands, input validation rules for `--vault`, `--tif`, and `--mode`, and confirmation rules for vault deposits and withdrawals and account mode changes. The `description` now also triggers on Hyperliquid vaults. + +### Changed + +- The SKILL.md perps trading confirmation rule now also covers `--tif`, `--reduce-only`, and `--vault`. +- `UNSUPPORTED_ROUTE` in `references/errors.md` also covers locked vault equity and `--vault` combined with deposits, withdrawals, or transfers. +- Bumped `cliVersion` to `7.3.0`. + ## [7.9.0] — targets CLI v7.2.0 ### Added diff --git a/README.md b/README.md index 2c6c88e..700cb88 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # MetaMask Agent CLI Skills -SKILLs for the MetaMask Agent CLI (`@metamask/agent-wallet` v7.2.0). These skills enable AI agents to authenticate, manage wallets, swap tokens, bridge across chains, trade perpetual futures, earn yield on DeFi vaults, and more using the MetaMask Agent Wallet CLI (`mm`). +SKILLs for the MetaMask Agent CLI (`@metamask/agent-wallet` v7.3.0). These skills enable AI agents to authenticate, manage wallets, swap tokens, bridge across chains, trade perpetual futures, earn yield on DeFi vaults, and more using the MetaMask Agent Wallet CLI (`mm`). This repository is also packaged as a **plugin** for Claude Code, Cursor, Codex, Antigravity CLI (`agy`), and Grok Build. The plugin ships the same skills plus a session-start hook that checks CLI readiness via `mm doctor` and records local install attribution. @@ -117,7 +117,7 @@ The plugin does not bundle `mm`. After the agent asks and the user consents: ```bash npm install -g @metamask/agent-wallet@latest # or pin to the skill's cliVersion, e.g.: -npm install -g @metamask/agent-wallet@7.2.0 +npm install -g @metamask/agent-wallet@7.3.0 ``` Requires a supported Node.js version. Then complete onboarding with `mm login` and `mm init` (see the skill workflows). diff --git a/skills/metamask-agent-wallet/SKILL.md b/skills/metamask-agent-wallet/SKILL.md index fda687b..b68a36a 100644 --- a/skills/metamask-agent-wallet/SKILL.md +++ b/skills/metamask-agent-wallet/SKILL.md @@ -1,11 +1,11 @@ --- name: metamask-agent-wallet -description: Use when the user asks anything about blockchain wallets, transactions, signing, token transfers, supported chains, wallet balances, perpetual futures trading and funding rates, prediction markets, token swaps, cross-chain bridges, market data, token discovery, tokenized real-world assets, RWAs, AI-generated market and asset summaries via pulse, decoding EVM calldata, DeFi earn/yield vaults, installing or removing third-party `mm` CLI plugins, or authentication via the MetaMask Agentic CLI; also when an HTTP request returns 402 Payment Required / x402, when an MCP tool call returns an x402 payment-required result, or the agent needs to pay for a paywalled API, endpoint, file, tool, or resource. Single entry point for all mm CLI operations. Financial operations are protected by server-enforced access controls including MFA approval, configurable wallet policies, and trading-mode guards (guard/beast) that restrict operation scope independently of the agent. +description: Use when the user asks anything about blockchain wallets, transactions, signing, token transfers, supported chains, wallet balances, perpetual futures trading, funding rates, and Hyperliquid vaults, prediction markets, token swaps, cross-chain bridges, market data, token discovery, tokenized real-world assets, RWAs, AI-generated market and asset summaries via pulse, decoding EVM calldata, DeFi earn/yield vaults, installing or removing third-party `mm` CLI plugins, or authentication via the MetaMask Agentic CLI; also when an HTTP request returns 402 Payment Required / x402, when an MCP tool call returns an x402 payment-required result, or the agent needs to pay for a paywalled API, endpoint, file, tool, or resource. Single entry point for all mm CLI operations. Financial operations are protected by server-enforced access controls including MFA approval, configurable wallet policies, and trading-mode guards (guard/beast) that restrict operation scope independently of the agent. license: MIT metadata: author: metamask - version: "7.9.0" - cliVersion: "7.2.0" + version: "7.10.0" + cliVersion: "7.3.0" --- # MetaMask Agentic CLI Skill @@ -85,6 +85,12 @@ Match the user's intent to a command and reference file, then read the reference | Transfer USDC between spot and perp accounts | `mm perps transfer` | [perps.md](references/perps.md) | | List perpetual futures venues | `mm perps list-venues` | [perps.md](references/perps.md) | | List available DEXs for a venue | `mm perps dexs` | [perps.md](references/perps.md) | +| List vault equities for the wallet | `mm perps vault list` | [perps.md](references/perps.md) | +| Show Hyperliquid vault details | `mm perps vault info` | [perps.md](references/perps.md) | +| Deposit USDC into a Hyperliquid vault | `mm perps vault deposit` | [perps.md](references/perps.md) | +| Withdraw USDC from a Hyperliquid vault | `mm perps vault withdraw` | [perps.md](references/perps.md) | +| Show Hyperliquid account mode | `mm perps account mode get` | [perps.md](references/perps.md) | +| Switch Hyperliquid account mode | `mm perps account mode set` | [perps.md](references/perps.md) | | Set Predict trading mode | `mm predict mode` | [predict.md](references/predict.md) | | One-time Predict setup | `mm predict setup` | [predict.md](references/predict.md) | | Create or refresh Predict credentials | `mm predict auth` | [predict.md](references/predict.md) | @@ -177,13 +183,13 @@ Run these checks before the first CLI operation in a session, in order. ### 1. Version compatibility -This skill is written for `@metamask/agent-wallet` v7.2.0, as specified by `cliVersion` in the frontmatter. The CLI requires Node.js 22.18 or later; on an older runtime every command exits 1 with `UNSUPPORTED_NODE` before the CLI loads. Check the installed version: +This skill is written for `@metamask/agent-wallet` v7.3.0, as specified by `cliVersion` in the frontmatter. The CLI requires Node.js 22.18 or later; on an older runtime every command exits 1 with `UNSUPPORTED_NODE` before the CLI loads. Check the installed version: ```bash mm --version ``` -The installed version is the value after `@metamask/agent-wallet/`, such as `@metamask/agent-wallet/7.2.0 darwin-arm64 node-v22.18.0`. Compare its `major.minor` against the pinned `cliVersion`. Optionally check the latest published version (best-effort, skip silently on network failure): +The installed version is the value after `@metamask/agent-wallet/`, such as `@metamask/agent-wallet/7.3.0 darwin-arm64 node-v22.18.0`. Compare its `major.minor` against the pinned `cliVersion`. Optionally check the latest published version (best-effort, skip silently on network failure): ```bash npm view @metamask/agent-wallet version @@ -222,7 +228,7 @@ Before constructing any command, validate all user-provided values: | Flag | Validation rule | | --- | --- | -| `--to`, `--address` | Must match `^0x[0-9a-fA-F]{40}$` | +| `--to`, `--address`, `--vault` | Must match `^0x[0-9a-fA-F]{40}$` | | `--amount` | Human-readable decimal such as 0.5 or 100. Must match `^\d+\.?\d*$`. Reject spaces, semicolons, pipes, backticks, or shell metacharacters | | `--chain-id` | Must be a positive integer (`^\d+$`) | | `--payload` for send-transaction | Must be valid JSON. No unescaped shell metacharacters outside the JSON structure | @@ -232,6 +238,8 @@ Before constructing any command, validate all user-provided values: | `--size` | Human-readable positive decimal such as 0.01 or 1. Scientific notation and host-locale grouping/decimals are accepted and canonicalized by the CLI. Reject shell metacharacters. Malformed values return `INVALID_AMOUNT` | | `--venue` | Must be `hyperliquid` | | `--side` for perps | Must be `long` or `short` | +| `--tif` | Must be `gtc`, `ioc`, or `alo` | +| `--mode` for perps account | Must be `standard` or `unified` | | `--order-id` | Must be a positive integer (`^\d+$`) | | `--token-id` | Must be a non-empty outcome token ID string | | `--price`, `--limit-price` | Must be a positive number in range `(0, 1]` | @@ -264,8 +272,10 @@ Do not pass unvalidated user input into any command. | Typed-data signing | Always show domain, primary type, chain, verifying contract, and message summary before signing | | Swaps / bridges | Always confirm from/to tokens, amount, source/destination chain, slippage, quoted output, recipient address if `--to-address` is set, and the destination gas top-up if `--refuel` is set before executing | | x402 payments | Always confirm asset, decimals-correct amount, network, `payTo`, and resource URL or MCP tool before signing the authorization — over HTTP with `pay --confirm`, over MCP with `mcp-sign --confirm`. One payment attempt per resource, never auto-retry a payment. Autonomous auto-pay is not supported. | -| Perps trading | Always confirm symbol, side, size, leverage, venue, order type, and limit price if present before executing | +| Perps trading | Always confirm symbol, side, size, leverage, venue, order type, and limit price if present before executing. Also confirm time in force if `--tif` is set, that the order is reduce-only if `--reduce-only` is set, and the vault address if `--vault` is set | | Perps deposit/withdraw | Always confirm amount, asset, venue, network, and destination where applicable before executing | +| Perps vault deposit/withdraw | Always confirm vault address and name from `mm perps vault info`, amount, venue, and network before executing. For deposits, say that the equity is locked for a period before it can be withdrawn | +| Perps account mode set | Always show the current mode from `mm perps account mode get` and the target mode, and say that the change applies to the whole Hyperliquid account, before executing | | Predict trading | Always confirm token ID, side, size, price, order type, market, and outcome before executing | | Predict deposit | Always confirm amount before executing | | Predict withdraw | Always confirm amount and recipient before executing. `--to` defaults to owner EOA | diff --git a/skills/metamask-agent-wallet/references/errors.md b/skills/metamask-agent-wallet/references/errors.md index 4627cd3..3be0c76 100644 --- a/skills/metamask-agent-wallet/references/errors.md +++ b/skills/metamask-agent-wallet/references/errors.md @@ -58,6 +58,7 @@ This reference lists error codes the CLI actually emits. SDK-only or remapped co | `INVALID_MNEMONIC` | BYOK mnemonic is invalid | | `INVALID_VENUE` | Invalid perpetual venue value | | `INVALID_NETWORK` | Invalid network value. Must be `mainnet` or `testnet` | +| `INVALID_TIF` | Invalid `--tif` on `mm perps open` or `mm perps quote`. Must be `gtc`, `ioc`, or `alo`, and `gtc` or `alo` need `--type limit` with `--limit-px` | | `INVALID_WINDOW` | Invalid `--window` on `mm perps funding-rates`. Must be `1h`, `8h`, or `1d` | | `INVALID_ASSET` | Invalid asset value | | `INVALID_SIDE` | Invalid side value. Must be `long`/`short` or `buy`/`sell` | @@ -176,7 +177,7 @@ This reference lists error codes the CLI actually emits. SDK-only or remapped co | --- | --- | | `UNSUPPORTED_VENUE` | Unsupported perpetual venue | | `UNSUPPORTED_NETWORK` | Unsupported network for perps | -| `UNSUPPORTED_ROUTE` | Unsupported deposit or withdraw route | +| `UNSUPPORTED_ROUTE` | Unsupported deposit or withdraw route. Also returned when vault equity is still locked on `mm perps vault withdraw`, and when `--vault` is combined with a deposit, withdrawal, or spot to perp transfer | | `UNSUPPORTED_ASSET` | Unsupported asset | | `UNSUPPORTED_SOURCE_CHAIN` | Unsupported source chain for perps deposit | | `INVALID_SYMBOL` | Unknown perpetual market symbol | @@ -190,6 +191,8 @@ This reference lists error codes the CLI actually emits. SDK-only or remapped co | `POSITION_NOT_FOUND` | Position not found | | `QUOTE_FAILED` | Quote generation failed | | `ORDER_REJECTED` | Order rejected | +| `REDUCE_ONLY_REJECTED` | A `--reduce-only` order on `mm perps open` would increase or flip the position. Check `mm perps positions`, or drop `--reduce-only` if the user wants to add to the position | +| `ALREADY_SET_ACCOUNT_MODE` | `mm perps account mode set` target matches the current mode. Nothing changed | | `CANCEL_FAILED` | Order cancellation failed | | `SIGNING_FAILED` | Signing operation failed | | `WITHDRAW_FAILED` | Withdrawal failed | diff --git a/skills/metamask-agent-wallet/references/perps.md b/skills/metamask-agent-wallet/references/perps.md index 23cb274..d5ead39 100644 --- a/skills/metamask-agent-wallet/references/perps.md +++ b/skills/metamask-agent-wallet/references/perps.md @@ -11,7 +11,9 @@ Most `perps` commands accept these flags (`list-venues` does not): | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` | | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | -The `--yes` flag skips interactive confirmation on `open`, `close`, `modify`, and `cancel` only. On `deposit`, `transfer`, and `withdraw`, `--yes` is accepted but has no effect because those commands do not prompt. Perps commands do not use `--wait`. In BYOK mode with an encrypted mnemonic, state-changing commands also accept `--password` to unlock the mnemonic. Set `MM_PASSWORD` env var instead of passing inline. +The `--yes` flag skips interactive confirmation on `open`, `close`, `modify`, and `cancel` only. On `deposit`, `transfer`, and `withdraw`, `--yes` is accepted but has no effect because those commands do not prompt. Perps commands do not use `--wait`. + +`open`, `close`, `modify`, `cancel`, `positions`, `orders`, and `balance` accept `--vault
` to trade or read on behalf of a Hyperliquid vault instead of the connected wallet. `deposit`, `withdraw`, `transfer`, and vault deposits or withdrawals are not available on behalf of a vault and return `UNSUPPORTED_ROUTE`. In BYOK mode with an encrypted mnemonic, state-changing commands also accept `--password` to unlock the mnemonic. Set `MM_PASSWORD` env var instead of passing inline. ## `perps markets` Command @@ -49,7 +51,7 @@ Show the connected wallet's perpetual account balances for a venue. ### Syntax ```bash -mm perps balance [--venue ] [--network ] [--dex ] [--all-dexes] +mm perps balance [--venue ] [--network ] [--dex ] [--all-dexes] [--vault
] ``` ### Supported Flags @@ -60,6 +62,7 @@ mm perps balance [--venue ] [--network ] [--dex ] [--all-de | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | | `--dex` | No | HIP-3 DEX name. Omit to query only the main Hyperliquid DEX. Run `mm perps dexs` to see options | | `--all-dexes` | No | Aggregate balances across all DEXs. Mutually exclusive with `--dex` | +| `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to read the vault's account instead of the connected wallet's. Malformed values return `INVALID_ADDRESS` | ### Example @@ -79,7 +82,7 @@ With `--funding`, each position also carries `fundingRate`, the current hourly m ### Syntax ```bash -mm perps positions [--venue ] [--network ] [--dex ] [--all-dexes] [--funding] +mm perps positions [--venue ] [--network ] [--dex ] [--all-dexes] [--funding] [--vault
] ``` ### Supported Flags @@ -91,6 +94,7 @@ mm perps positions [--venue ] [--network ] [--dex ] [--all- | `--dex` | No | HIP-3 DEX name. Omit to query only the main Hyperliquid DEX. Run `mm perps dexs` to see options | | `--all-dexes` | No | Aggregate positions across all DEXs. Mutually exclusive with `--dex` | | `--funding` | No | Also fetch the current market funding rate for each open position. Without it, the extra markets request is skipped | +| `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to read the vault's account instead of the connected wallet's. Malformed values return `INVALID_ADDRESS` | ### Example @@ -162,7 +166,7 @@ Estimate entry price, notional, fees, and liquidation price without placing an o ### Syntax ```bash -mm perps quote [--venue ] --symbol --side --size --leverage [--type ] [--limit-px ] [--network ] +mm perps quote [--venue ] --symbol --side --size --leverage [--type ] [--limit-px ] [--tif ] [--network ] ``` ### Supported Flags @@ -176,6 +180,7 @@ mm perps quote [--venue ] --symbol --side --size - | `--leverage` | Yes | Leverage multiplier as a positive integer such as 5 or 10 | | `--type` | No | Order type: `market` or `limit`. Defaults to `market` | | `--limit-px` | If `--type limit` | Limit price, human-readable such as 60000 for BTC | +| `--tif` | No | Time in force: `gtc`, `ioc`, or `alo`. `alo` is post-only. `gtc` and `alo` require `--type limit` and `--limit-px`; `ioc` works with any order type. Omit to keep the defaults: `ioc` for market and `gtc` for limit. Invalid values or combinations return `INVALID_TIF` | | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | ### Example @@ -183,6 +188,7 @@ mm perps quote [--venue ] --symbol --side --size - ```bash mm perps quote --venue hyperliquid --symbol BTC --side long --size 0.01 --leverage 5 mm perps quote --venue hyperliquid --symbol ETH --side short --size 1 --leverage 10 --type limit --limit-px 2500 +mm perps quote --venue hyperliquid --symbol ETH --side short --size 1 --leverage 10 --type limit --limit-px 2500 --tif alo ``` ## `perps open` Command @@ -192,7 +198,7 @@ Open a new perpetual position by placing an order. ### Syntax ```bash -mm perps open [--venue ] --symbol --side --size --leverage [--type ] [--limit-px ] [--max-slippage-bps ] [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] +mm perps open [--venue ] --symbol --side --size --leverage [--type ] [--limit-px ] [--tif ] [--max-slippage-bps ] [--reduce-only] [--network ] [--vault
] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### Supported Flags @@ -206,8 +212,11 @@ mm perps open [--venue ] --symbol --side --size -- | `--leverage` | Yes | Leverage multiplier as a positive integer such as 5 or 10 | | `--type` | No | Order type: `market` or `limit`. Defaults to `market` | | `--limit-px` | If `--type limit` | Limit price; required when `--type` is `limit` such as 60000 for BTC | +| `--tif` | No | Time in force: `gtc`, `ioc`, or `alo`. `alo` is post-only. `gtc` and `alo` require `--type limit` and `--limit-px`; `ioc` works with any order type. Omit to keep the defaults: `ioc` for market and `gtc` for limit. Invalid values or combinations return `INVALID_TIF` | | `--max-slippage-bps` | No | Slippage cap in basis points for IOC market pricing such as 50 | +| `--reduce-only` | No | Submit an order that can only reduce or close the existing position. If it would increase or flip the position, the venue rejects it with `REDUCE_ONLY_REJECTED` | | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | +| `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to trade on behalf of a vault you lead. Malformed values return `INVALID_ADDRESS` | | `--dry-run` | No | Validate and preview the order without signing or submitting | | `--yes` | No | Skip interactive confirmation | | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline | @@ -219,6 +228,8 @@ mm perps open [--venue ] --symbol --side --size -- mm perps open --venue hyperliquid --symbol BTC --side long --size 0.01 --leverage 5 mm perps open --venue hyperliquid --symbol ETH --side short --size 1 --leverage 10 --type limit --limit-px 2500 mm perps open --venue hyperliquid --symbol BTC --side long --size 0.05 --leverage 3 --dry-run +mm perps open --venue hyperliquid --symbol BTC --side short --size 0.01 --leverage 5 --reduce-only +mm perps open --venue hyperliquid --symbol ETH --side long --size 1 --leverage 5 --type limit --limit-px 2400 --tif alo ``` ## `perps orders` Command @@ -228,7 +239,7 @@ List resting orders for the connected wallet on a venue. ### Syntax ```bash -mm perps orders [--venue ] [--network ] [--dex ] +mm perps orders [--venue ] [--network ] [--dex ] [--vault
] ``` ### Supported Flags @@ -238,6 +249,7 @@ mm perps orders [--venue ] [--network ] [--dex ] | `--venue` | No | Perpetual venue. Defaults to `hyperliquid` | | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | | `--dex` | No | HIP-3 DEX name. Omit to query only the main Hyperliquid DEX. Run `mm perps dexs` to see options | +| `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to read the vault's account instead of the connected wallet's. Malformed values return `INVALID_ADDRESS` | ### Example @@ -254,7 +266,7 @@ Close one position, part of a position, or all open positions. ### Syntax ```bash -mm perps close [--venue ] [--symbol ] [--size ] [--all] [--max-slippage-bps ] [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] +mm perps close [--venue ] [--symbol ] [--size ] [--all] [--max-slippage-bps ] [--network ] [--vault
] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### Supported Flags @@ -267,6 +279,7 @@ mm perps close [--venue ] [--symbol ] [--size ] [--all] [-- | `--all` | No | Close all open positions; mutually exclusive with `--symbol` | | `--max-slippage-bps` | No | Slippage cap in basis points for IOC pricing such as 50 | | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | +| `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to trade on behalf of a vault you lead. Malformed values return `INVALID_ADDRESS` | | `--dry-run` | No | Preview the close action without signing or submitting | | `--yes` | No | Skip interactive confirmation | | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline | @@ -292,7 +305,7 @@ Modify leverage, take-profit, or stop-loss for an existing position. ### Syntax ```bash -mm perps modify [--venue ] --symbol [--leverage ] [--tp ] [--sl ] [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] +mm perps modify [--venue ] --symbol [--leverage ] [--tp ] [--sl ] [--network ] [--vault
] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### Supported Flags @@ -305,6 +318,7 @@ mm perps modify [--venue ] --symbol [--leverage ] [--t | `--tp` | No | Take-profit trigger price, human-readable such as 3000 or 2500.50 | | `--sl` | No | Stop-loss trigger price, human-readable such as 2000 or 1800.75 | | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | +| `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to trade on behalf of a vault you lead. Malformed values return `INVALID_ADDRESS` | | `--dry-run` | No | Preview the modify action without signing or submitting | | `--yes` | No | Skip interactive confirmation | | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline | @@ -329,7 +343,7 @@ Cancel a resting perps order. ### Syntax ```bash -mm perps cancel [--venue ] --order-id [--symbol ] [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] +mm perps cancel [--venue ] --order-id [--symbol ] [--network ] [--vault
] [--dry-run] [--yes] [--password ] [--wallet-timeout ] ``` ### Supported Flags @@ -340,6 +354,7 @@ mm perps cancel [--venue ] --order-id [--symbol ] [--network | `--order-id` | Yes | Venue order ID to cancel. Must be a positive integer | | `--symbol` | No | Market symbol, speeds up cancel by avoiding an open-order lookup. For example BTC or ETH | | `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | +| `--vault` | No | Hyperliquid vault address, 0x-prefixed hex, to trade on behalf of a vault you lead. Malformed values return `INVALID_ADDRESS` | | `--dry-run` | No | Preview the cancel action without signing or submitting | | `--yes` | No | Skip interactive confirmation | | `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline | @@ -492,6 +507,168 @@ mm perps dexs [--venue ] [--network ] mm perps dexs --venue hyperliquid ``` +## `perps vault list` Command + +List the connected wallet's equity in Hyperliquid vaults. + +### Syntax + +```bash +mm perps vault list [--venue ] [--network ] +``` + +### Supported Flags + +| Name | Required | Description | +| --- | --- | --- | +| `--venue` | No | Perpetual venue. Defaults to `hyperliquid` | +| `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | + +### Example + +```bash +mm perps vault list --venue hyperliquid +``` + +## `perps vault info` Command + +Show metadata for a Hyperliquid vault. + +### Syntax + +```bash +mm perps vault info [--venue ] --vault
[--network ] +``` + +### Supported Flags + +| Name | Required | Description | +| --- | --- | --- | +| `--venue` | No | Perpetual venue. Defaults to `hyperliquid` | +| `--vault` | Yes | Hyperliquid vault address, 0x-prefixed hex. Malformed values return `INVALID_ADDRESS`, and an address with no vault returns `INVALID_INPUT` | +| `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | + +### Example + +```bash +mm perps vault info --venue hyperliquid --vault 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303 +``` + +## `perps vault deposit` Command + +Deposit USDC from the connected wallet's perp balance into a Hyperliquid vault. Creating a vault is not supported. + +### Syntax + +```bash +mm perps vault deposit [--venue ] --vault
--amount [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] +``` + +### Supported Flags + +| Name | Required | Description | +| --- | --- | --- | +| `--venue` | No | Perpetual venue. Defaults to `hyperliquid` | +| `--vault` | Yes | Hyperliquid vault address, 0x-prefixed hex. Malformed values return `INVALID_ADDRESS` | +| `--amount` | Yes | Human-readable USDC amount such as 100. The minimum is 1 USDC. The amount must fit in the perp spendable balance, otherwise `INSUFFICIENT_BALANCE`. In standard account mode, move spot USDC to perp first with `mm perps transfer`; unified accounts already include free spot USDC | +| `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | +| `--dry-run` | No | Validate the flags and return a `prepared` status without signing. Balance, minimum, and vault checks only run on a live deposit | +| `--yes` | No | Skip interactive confirmation | +| `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline | +| `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` | + +### Example + +```bash +mm perps vault deposit --venue hyperliquid --vault 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303 --amount 100 --dry-run +mm perps vault deposit --venue hyperliquid --vault 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303 --amount 100 +``` + +## `perps vault withdraw` Command + +Withdraw USDC from a Hyperliquid vault back to the connected wallet's perp balance. + +### Syntax + +```bash +mm perps vault withdraw [--venue ] --vault
--amount [--network ] [--dry-run] [--yes] [--password ] [--wallet-timeout ] +``` + +### Supported Flags + +| Name | Required | Description | +| --- | --- | --- | +| `--venue` | No | Perpetual venue. Defaults to `hyperliquid` | +| `--vault` | Yes | Hyperliquid vault address, 0x-prefixed hex. Malformed values return `INVALID_ADDRESS` | +| `--amount` | Yes | Human-readable USDC amount such as 50. The minimum is 1 USDC, and the amount cannot exceed your equity in the vault, otherwise `INSUFFICIENT_BALANCE`. Equity still inside its lock period returns `UNSUPPORTED_ROUTE` with the unlock time | +| `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | +| `--dry-run` | No | Validate the flags and return a `prepared` status without signing. Equity, minimum, and lock checks only run on a live withdrawal | +| `--yes` | No | Skip interactive confirmation | +| `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline | +| `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` | + +### Example + +```bash +mm perps vault withdraw --venue hyperliquid --vault 0xdfc24b077bc1425ad1dea75bcb6f8158e10df303 --amount 50 +``` + +## `perps account mode get` Command + +Show the Hyperliquid account abstraction mode for the connected wallet. In `standard` mode spot and perp balances are separate; in `unified` mode they are pooled. + +### Syntax + +```bash +mm perps account mode get [--venue ] [--network ] +``` + +### Supported Flags + +| Name | Required | Description | +| --- | --- | --- | +| `--venue` | No | Perpetual venue. Defaults to `hyperliquid` | +| `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | + +### Example + +```bash +mm perps account mode get --venue hyperliquid +``` + +## `perps account mode set` Command + +Switch the Hyperliquid account abstraction mode for the connected wallet. This changes how spot and perp balances are pooled for the whole Hyperliquid account, not only for one command. + +### Syntax + +```bash +mm perps account mode set [--venue ] --mode [--network ] [--yes] [--password ] [--wallet-timeout ] +``` + +### Supported Flags + +| Name | Required | Description | +| --- | --- | --- | +| `--venue` | No | Perpetual venue. Defaults to `hyperliquid` | +| `--mode` | Yes | Target mode: `standard` for separate spot and perp balances, or `unified` for pooled balances. If the account is already in that mode, the command returns `ALREADY_SET_ACCOUNT_MODE` | +| `--network` | No | Target network: `mainnet` or `testnet`. Defaults to `mainnet` | +| `--yes` | No | Skip interactive confirmation | +| `--password` | No | Password to unlock the BYOK mnemonic. Only applies to BYOK mode. Set `MM_PASSWORD` env var instead of passing inline | +| `--wallet-timeout` | No | Seconds to wait per wallet job including MFA and signing, max 600. Overrides config `walletTimeoutSeconds` | + +There is no `--dry-run`. Run `mm perps account mode get` first to show the user the current mode. + +### Output + +`venue`, `network`, `previousRawState`, `rawState`, `mode`, and `changed`. The CLI reads the mode back after switching and returns `HYPERLIQUID_ERROR` if the change did not take effect. + +### Example + +```bash +mm perps account mode set --venue hyperliquid --mode unified +``` + ## Notes - If the user does not mention a token symbol, use `mm perps markets` to list available markets and confirm the symbol with the user before proceeding. diff --git a/skills/metamask-agent-wallet/workflows/perps-open-position.md b/skills/metamask-agent-wallet/workflows/perps-open-position.md index 8f0e8b8..ef2ea67 100644 --- a/skills/metamask-agent-wallet/workflows/perps-open-position.md +++ b/skills/metamask-agent-wallet/workflows/perps-open-position.md @@ -91,6 +91,10 @@ For limit orders, include `--type limit --limit-px `. `--max-slippage-bps` is the slippage cap in basis points for IOC market pricing. +For a post-only limit order that must rest on the book, add `--tif alo` to both the quote and the open. `gtc` and `alo` need `--type limit`. + +To only shrink or close an existing position, for example a take-profit style exit placed as a limit order, add `--reduce-only` and use the side opposite the position. + ## Open Remove `--dry-run` only after explicit user confirmation: diff --git a/skills/metamask-agent-wallet/workflows/troubleshooting.md b/skills/metamask-agent-wallet/workflows/troubleshooting.md index 5ac456c..a19ee9a 100644 --- a/skills/metamask-agent-wallet/workflows/troubleshooting.md +++ b/skills/metamask-agent-wallet/workflows/troubleshooting.md @@ -61,6 +61,10 @@ If `auth status` reports anything other than authenticated, fix authentication b | `AUTH_FAILED` after a working session | Session token expired during operation | Run `mm login` to re-authenticate | | `RELAY_TIMEOUT` on swap execute | Gasless relay MFA/signing timed out | Run `mm wallet requests watch ` — the job may still complete. Do not re-run execute while the job is pending | | `RATE_LIMITED` on perps commands | Hyperliquid rate limit (HTTP 429) | Wait briefly and retry | +| `INVALID_TIF` on `perps open` or `perps quote` | `--tif gtc` or `--tif alo` without a limit order | Add `--type limit --limit-px `, or use `--tif ioc` | +| `REDUCE_ONLY_REJECTED` on `perps open` | The reduce-only order would grow or flip the position | Check `mm perps positions` and match the opposite side and a size no larger than the position | +| `UNSUPPORTED_ROUTE` on `perps vault withdraw` | Deposited vault equity is still locked | Show the unlock time from `lockedUntilTimestamp` in `mm perps vault list` and retry after it | +| `INSUFFICIENT_BALANCE` on `perps vault deposit` | Perp spendable USDC is below the amount | In standard mode, move spot USDC to perp with `mm perps transfer`, or lower `--amount` | | `ALREADY_LOGGED_OUT` on logout | No active session to sign out of | Run `mm login` to authenticate | | `INVALID_EVM_ADDRESS` on transfer | Malformed recipient address | Check the `--to` address is a valid `0x`-prefixed 40-hex-char EVM address |