Skip to content

Commit bd6828e

Browse files
chaitanyapottichaitanyapotti
authored
Merge pull request #3 from MetaMask/feat/improvements
Improve SKILLs
2 parents e7df71e + 0d72acd commit bd6828e

26 files changed

Lines changed: 860 additions & 289 deletions

‎skills/metamask-agent-wallet/SKILL.md‎

Lines changed: 28 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,11 +22,15 @@ Match the user's intent to a command and reference file, then read the reference
2222
| Check authentication status | `mm-dev auth status` | [auth.md](references/auth.md) |
2323
| Login in MetaMask Agentic CLI | `mm-dev login` | [auth.md](references/auth.md) |
2424
| Choose a wallet mode and set up policies | `mm-dev init` | [auth.md](references/auth.md) |
25+
| Show current init settings | `mm-dev init show` | [auth.md](references/auth.md) |
2526
| Sign in via QR code | `mm-dev login qr` | [auth.md](references/auth.md) |
2627
| Sign in via Google | `mm-dev login google` | [auth.md](references/auth.md) |
2728
| Sign in via email OTP | `mm-dev login email` | [auth.md](references/auth.md) |
2829
| Sign out | `mm-dev logout` | [auth.md](references/auth.md) |
2930
| Reset CLI session | `mm-dev reset` | [auth.md](references/auth.md) |
31+
| Set BYOK mnemonic encryption password | `mm-dev wallet password set` | [auth.md](references/auth.md) |
32+
| Change BYOK mnemonic encryption password | `mm-dev wallet password change` | [auth.md](references/auth.md) |
33+
| Remove BYOK mnemonic encryption password | `mm-dev wallet password remove` | [auth.md](references/auth.md) |
3034
| Interpret raw CLI error codes | `AuthError`, `ValidationError`, `WALLET_ERROR` | [errors.md](references/errors.md) |
3135
| Create a wallet | `mm-dev wallet create` | [wallet.md](references/wallet.md) |
3236
| List all wallets | `mm-dev wallet list` | [wallet.md](references/wallet.md) |
@@ -54,6 +58,9 @@ Match the user's intent to a command and reference file, then read the reference
5458
| Cancel a resting perps order | `mm-dev perps cancel` | [perps.md](references/perps.md) |
5559
| Deposit USDC into a perps venue | `mm-dev perps deposit` | [perps.md](references/perps.md) |
5660
| Withdraw USDC from a perps venue | `mm-dev perps withdraw` | [perps.md](references/perps.md) |
61+
| Transfer USDC between spot and perp accounts | `mm-dev perps transfer` | [perps.md](references/perps.md) |
62+
| List perpetual futures venues | `mm-dev perps list-venues` | [perps.md](references/perps.md) |
63+
| List available DEXs for a venue | `mm-dev perps dexs` | [perps.md](references/perps.md) |
5764
| Set Predict trading mode | `mm-dev predict mode` | [predict.md](references/predict.md) |
5865
| One-time Predict setup | `mm-dev predict setup` | [predict.md](references/predict.md) |
5966
| Create or refresh Predict credentials | `mm-dev predict auth` | [predict.md](references/predict.md) |
@@ -90,6 +97,20 @@ CLI behavior lives in `references/`. Repeatable patterns live in `workflows/`. L
9097
| Close a perpetual position flow | [perps-close-position.md](workflows/perps-close-position.md) |
9198
| Modify a perpetual position flow | [perps-modify-position.md](workflows/perps-modify-position.md) |
9299
| Predict setup-fund-quote-place flow | [predict-trading.md](workflows/predict-trading.md) |
100+
| Token discovery, prices, and market data | [market-data.md](workflows/market-data.md) |
101+
102+
## Global Flags
103+
104+
Every `mm-dev` command accepts these flags:
105+
106+
| Flag | Short | Description |
107+
| --- | --- | --- |
108+
| `--format` | `-f` | Output format: `text`, `json`, `yaml`, `toml`, or `toon` (defaults to `text` in TTY, `json` when piped) |
109+
| `--json` | | Shorthand for `--format=json` |
110+
| `--toon` | | Shorthand for `--format=toon` |
111+
| `--verbose` | `-v` | Show debug logs on stderr. Use for troubleshooting |
112+
113+
Always use `--toon` for command output unless the user explicitly requests a different format.
93114

94115
## Preflight
95116

@@ -112,12 +133,12 @@ Before constructing any command, validate all user-provided values:
112133
| Flag | Validation rule |
113134
| --- | --- |
114135
| `--to`, `--address` | Must match `^0x[0-9a-fA-F]{40}$` |
115-
| `--amount` | Must match `^\d+\.?\d*$`. Reject spaces, semicolons, pipes, backticks, or shell metacharacters |
136+
| `--amount` | Human-readable decimal (e.g. 0.5, 100). Must match `^\d+\.?\d*$`. Reject spaces, semicolons, pipes, backticks, or shell metacharacters |
116137
| `--chain-id` | Must be a positive integer (`^\d+$`) |
117138
| `--payload` | Must be valid JSON. No unescaped shell metacharacters outside the JSON structure |
118139
| `--token` | Must be a valid hex address or known symbol |
119140
| `--leverage` | Must be a positive integer (`^\d+$`) |
120-
| `--size` | Must match `^\d+\.?\d*$` and be positive |
141+
| `--size` | Human-readable decimal (e.g. 0.01, 1). Must match `^\d+\.?\d*$` and be positive |
121142
| `--venue` | Must be `hyperliquid` |
122143
| `--side` (perps) | Must be `long` or `short` |
123144
| `--order-id` | Must be a positive integer (`^\d+$`) |
@@ -127,6 +148,7 @@ Before constructing any command, validate all user-provided values:
127148
| `--side` (predict) | Must be `buy` or `sell` |
128149
| `--slippage` | Must be a number between 0 and 100 |
129150
| `--from-chain`, `--to-chain` | Must be a positive integer EVM chain ID |
151+
| `--password` | Must be a non-empty string. Never log, display, or store the value. |
130152

131153
Do not pass unvalidated user input into any command.
132154

@@ -144,12 +166,13 @@ Do not pass unvalidated user input into any command.
144166
| Predict trading | Always confirm token ID, side, size, price, order type, market, and outcome before executing |
145167
| Predict deposit | Always confirm amount before executing |
146168
| Cancel-all operations | Always confirm scope and exact destructive effect before executing |
147-
| Auth / wallet management | May execute without confirmation |
169+
| Auth / wallet management | May execute without confirmation, except `reset` which requires explicit user confirmation |
148170
| Read-only queries | May execute without confirmation |
149171

150172
### Credential Safety
151173

152-
- Never store, log, or display private keys, mnemonics, or auth tokens.
174+
- Never store, log, or display private keys, mnemonics, passwords, or auth tokens.
175+
- Never pass `--password` or `--mnemonic` as inline flags. Always instruct the user to set the `MM_PASSWORD` and `MM_MNEMONIC` environment variables instead to avoid exposing secrets in shell history.
153176

154177
### Suspicious Content Warnings
155178

@@ -167,7 +190,7 @@ In server-wallet mode, signing and transaction commands return a `pollingId` ins
167190
2. If not using `--wait`, inform the user of the `pollingId` and how to track it:
168191
- `mm-dev wallet requests list`
169192
- `mm-dev wallet requests watch --polling-id <id>`
170-
3. In BYOK mode, results are returned immediately.
193+
3. In BYOK mode, results are returned immediately. If the mnemonic is password-encrypted, the user must set `MM_PASSWORD` environment variable to unlock it for the operation.
171194

172195
## Output Rules
173196

‎skills/metamask-agent-wallet/references/auth.md‎

Lines changed: 105 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,23 +9,49 @@ Initialize the project by selecting wallet mode and trading mode.
99
### Syntax
1010

1111
```bash
12-
mm-dev init [--wallet <mode>] [--mode <mode>] [--mnemonic <phrase>]
12+
mm-dev init [--wallet <mode>] [--mode <mode>] [--mnemonic <phrase>] [--password <password>]
1313
```
1414

1515
### Supported Flags
1616

1717
| Name | Required | Description |
1818
| --- | --- | --- |
1919
| `--wallet` | No | Wallet mode: `server-wallet` or `byok` |
20-
| `--mode` | No | Trading mode: `safe` or `yolo` |
21-
| `--mnemonic` | No | Mnemonic for BYOK wallet [env: `MM_MNEMONIC`] |
20+
| `--mode` | No | Trading mode: `guard` or `beast` (server-wallet only) |
21+
| `--mnemonic` | No | BIP-39 mnemonic phrase for BYOK wallet. Never pass inline — set `MM_MNEMONIC` env var instead. |
22+
| `--password` | No | Password to encrypt the BYOK mnemonic at rest. Never pass inline — set `MM_PASSWORD` env var instead. If omitted in interactive mode, the CLI prompts. If omitted in non-interactive mode, mnemonic is stored unencrypted. |
2223

2324
### Example
2425

2526
```bash
2627
mm-dev init
27-
mm-dev init --wallet server-wallet --mode yolo
28-
mm-dev init --wallet byok --mnemonic "word1 word2 ..."
28+
mm-dev init --wallet server-wallet --mode beast
29+
export MM_MNEMONIC="word1 word2 ..."
30+
mm-dev init --wallet byok
31+
32+
export MM_MNEMONIC="word1 word2 ..."
33+
export MM_PASSWORD="mypassword"
34+
mm-dev init --wallet byok
35+
```
36+
37+
## `init show` Command
38+
39+
Display the current initialization settings (wallet mode, trading mode, policies).
40+
41+
### Syntax
42+
43+
```bash
44+
mm-dev init show
45+
```
46+
47+
### Supported Flags
48+
49+
This command does not support additional flags beyond output format options.
50+
51+
### Example
52+
53+
```bash
54+
mm-dev init show
2955
```
3056

3157
## `login` Command
@@ -42,9 +68,9 @@ mm-dev login [qr | google | email] [--token <token>] [--timeout <seconds>] [--no
4268

4369
| Name | Required | Description |
4470
| --- | --- | --- |
45-
| `--token` | No | Pre-minted CLI token (`cliToken:cliRefreshToken`) [env: `MM_CLI_TOKEN`] |
46-
| `--timeout` | No | How long to wait for QR / browser callback, in seconds |
47-
| `--no-wait` | No | Print sign-in URL and exit; finish later with `mm-dev login --token` |
71+
| `--token` | No | Pre-minted CLI token in `cliToken:cliRefreshToken` format [env: `MM_CLI_TOKEN`] |
72+
| `--timeout` | No | Seconds to wait for QR or browser callback |
73+
| `--no-wait` | No | Print the sign-in URL and exit without waiting (for non-interactive/CI use). Not supported with QR login. Complete later with `mm-dev login --token` |
4874

4975
### Example
5076

@@ -121,9 +147,79 @@ This command does not support flags.
121147
mm-dev reset
122148
```
123149

150+
## `wallet password set` Command
151+
152+
Set a password to encrypt the BYOK mnemonic at rest. Only available in BYOK mode when the mnemonic is currently unencrypted.
153+
154+
### Syntax
155+
156+
```bash
157+
mm-dev wallet password set [--new <password>]
158+
```
159+
160+
### Supported Flags
161+
162+
| Name | Required | Description |
163+
| --- | --- | --- |
164+
| `--new` | No | New password. If omitted, the CLI prompts interactively. |
165+
166+
### Example
167+
168+
```bash
169+
mm-dev wallet password set
170+
mm-dev wallet password set --new "mypassword"
171+
```
172+
173+
## `wallet password change` Command
174+
175+
Change the BYOK mnemonic encryption password. Only available when the mnemonic is currently encrypted.
176+
177+
### Syntax
178+
179+
```bash
180+
mm-dev wallet password change [--current <password>] [--new <password>]
181+
```
182+
183+
### Supported Flags
184+
185+
| Name | Required | Description |
186+
| --- | --- | --- |
187+
| `--current` | No | Current password. If omitted, the CLI prompts interactively. |
188+
| `--new` | No | New password. If omitted, the CLI prompts interactively. |
189+
190+
### Example
191+
192+
```bash
193+
mm-dev wallet password change
194+
mm-dev wallet password change --current "oldpassword" --new "newpassword"
195+
```
196+
197+
## `wallet password remove` Command
198+
199+
Remove the BYOK mnemonic encryption password, storing the mnemonic as plaintext. Only available when the mnemonic is currently encrypted.
200+
201+
### Syntax
202+
203+
```bash
204+
mm-dev wallet password remove [--current <password>]
205+
```
206+
207+
### Supported Flags
208+
209+
| Name | Required | Description |
210+
| --- | --- | --- |
211+
| `--current` | No | Current password. If omitted, the CLI prompts interactively. |
212+
213+
### Example
214+
215+
```bash
216+
mm-dev wallet password remove
217+
mm-dev wallet password remove --current "mypassword"
218+
```
219+
124220
## Wallet Modes
125221

126222
| Mode | Behavior |
127223
| --- | --- |
128224
| `server-wallet` | Keys hosted by MetaMask infrastructure. Signing and transaction operations may return async job handles. |
129-
| `byok` | Bring your own local mnemonic. Operation results are returned immediately. |
225+
| `byok` | Bring your own local mnemonic. Operation results are returned immediately. If the mnemonic is encrypted with a password, the CLI requires `--password` or interactive prompt to unlock before any operation that needs the private key. |

‎skills/metamask-agent-wallet/references/errors.md‎

Lines changed: 113 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,25 @@ This reference lists raw CLI and SDK error codes. Workflows for diagnosing failu
66

77
| Code | Meaning |
88
| --- | --- |
9+
| `AUTH_FAILED` | Authentication failed |
10+
| `AUTH_ERROR` | Generic authentication error |
11+
| `TOKEN_INVALID` | Invalid CLI token |
12+
| `TOKEN_REFRESH_FAILED` | Failed to refresh token |
913
| `PAIRING_ABORTED` | Login pairing was aborted |
1014
| `PAIRING_TIMEOUT` | Login pairing timed out |
15+
| `PAIRING_EXPIRED` | Pairing session expired |
1116
| `INVALID_CLI_TOKENS` | CLI token pair is invalid |
1217
| `INVALID_CLI_TOKEN` | CLI token is invalid |
1318
| `MISSING_REFRESH_TOKEN` | Refresh token is missing |
1419
| `REFRESH_CLI_TOKEN_FAILED` | CLI token refresh failed |
1520
| `MISSING_TOKEN` | Required auth token is missing |
1621
| `REVOKE_CLI_TOKEN_FAILED` | CLI token revoke failed |
1722
| `INVALID_PROJECT_ID` | Project ID is invalid for the selected environment |
23+
| `MISSING_PROJECT_ID` | Project ID is not configured |
24+
| `INVALID_OTP` | Invalid one-time password |
25+
| `MWP_TIMEOUT` | Mobile Wallet Protocol timeout |
26+
| `MWP_CANCELLED` | Mobile Wallet Protocol cancelled |
27+
| `LOGOUT_FAILED` | Logout operation failed |
1828

1929
## Validation Errors
2030

@@ -23,11 +33,21 @@ This reference lists raw CLI and SDK error codes. Workflows for diagnosing failu
2333
| `MISSING_FLAG` | Required flag is missing in headless mode |
2434
| `MISSING_INPUT` | Required input is missing |
2535
| `MISSING_CHAIN` | Chain value is missing |
36+
| `MISSING_CHAIN_ID` | Chain ID is missing |
2637
| `INVALID_CHAIN` | Chain value is invalid |
2738
| `MISSING_TO` | Recipient address is missing |
2839
| `INVALID_TO` | Recipient address is invalid |
2940
| `INVALID_DATA` | Transaction data is invalid |
41+
| `INVALID_INPUT` | Invalid user input |
3042
| `INVALID_QUANTITY` | EVM quantity is invalid |
43+
| `INVALID_LIMIT` | Invalid limit value |
44+
| `INVALID_INTERVAL` | Invalid time interval |
45+
| `INVALID_TIMESTAMP` | Invalid timestamp |
46+
| `INVALID_ASSET_ID` | Invalid asset identifier |
47+
| `MISSING_ASSET_IDS` | Missing asset IDs |
48+
| `MISSING_ASSET_TYPE` | Missing asset type |
49+
| `MISSING_QUERY` | Missing search query |
50+
| `MISSING_WALLET_REF` | Missing wallet reference |
3151
| `MISSING_TRANSACTION_PAYLOAD` | Transaction payload is missing |
3252
| `INVALID_TRANSACTION_PAYLOAD` | Transaction payload is invalid |
3353
| `MISSING_TYPED_DATA` | EIP-712 typed data payload is missing |
@@ -40,11 +60,99 @@ This reference lists raw CLI and SDK error codes. Workflows for diagnosing failu
4060
| Code | Meaning |
4161
| --- | --- |
4262
| `MISSING_MNEMONIC` | BYOK wallet mode is missing a mnemonic |
63+
| `MNEMONIC_LOCKED` | Mnemonic unlock failed after maximum attempts |
64+
| `WRONG_PASSWORD` | Current password is incorrect |
65+
| `ALREADY_ENCRYPTED` | Mnemonic is already password-encrypted (use `wallet password change` instead) |
66+
| `NOT_ENCRYPTED` | Mnemonic is not encrypted (use `wallet password set` instead) |
67+
| `PASSWORD_MISMATCH` | Password confirmation does not match |
68+
| `EMPTY_PASSWORD` | Empty password provided |
69+
| `WALLET_NOT_FOUND` | Wallet not found |
4370
| `WALLET_ERROR` | Wallet provider or wallet operation error |
71+
| `WALLET_METADATA` | Wallet metadata error |
72+
| `WRONG_NAMESPACE` | Wrong namespace for wallet |
73+
| `UNSUPPORTED_NAMESPACE` | Unsupported wallet namespace |
74+
| `NO_AUTH_TOKEN` | Missing authentication token for wallet operations |
75+
| `NO_PROJECT_ID` | Project ID not configured for wallet |
4476

45-
## Examples
77+
## Command Errors
4678

47-
```bash
48-
mm-dev auth status --json
49-
mm-dev wallet sign-typed-data --chain-id 1 --payload '{"types":{},"primaryType":"Permit","domain":{"chainId":137},"message":{}}'
50-
```
79+
| Code | Meaning |
80+
| --- | --- |
81+
| `ABORTED` | Operation aborted by user |
82+
| `NOT_INITIALIZED` | Project not initialized — run `mm-dev init` |
83+
| `NO_MNEMONIC` | Mnemonic not stored |
84+
| `NO_TTY` | No TTY available for interactive prompts |
85+
| `MISSING_ID` | Missing ID parameter |
86+
| `MISSING_QUOTE_ID` | Missing quote ID |
87+
| `MISSING_SWAP_PARAMS` | Missing swap parameters |
88+
89+
## Swap & Bridge Errors
90+
91+
| Code | Meaning |
92+
| --- | --- |
93+
| `NO_QUOTES` | No swap or bridge quotes available |
94+
| `BRIDGE_API_ERROR` | Bridge API error |
95+
| `TOKEN_NOT_FOUND` | Token not found |
96+
| `INVALID_SWAP_PARAMS` | Invalid swap parameters |
97+
| `NATIVE_ASSET_UNSUPPORTED` | Native asset not supported for this swap route |
98+
| `QUOTE_PERSIST_FAILED` | Failed to persist quote |
99+
| `QUOTE_NOT_FOUND` | Quote not found |
100+
| `EXECUTE_FAILED` | Swap execution failed |
101+
| `NO_TRADE_DATA` | No trade data available |
102+
| `STATUS_UNAVAILABLE` | Swap status unavailable |
103+
| `SWAP_ERROR` | Generic swap error |
104+
105+
## Perps Errors
106+
107+
| Code | Meaning |
108+
| --- | --- |
109+
| `UNSUPPORTED_VENUE` | Unsupported perpetual venue |
110+
| `UNSUPPORTED_NETWORK` | Unsupported network for perps |
111+
| `UNSUPPORTED_ROUTE` | Unsupported deposit or withdraw route |
112+
| `UNSUPPORTED_ASSET` | Unsupported asset |
113+
| `UNSUPPORTED_SOURCE_CHAIN` | Unsupported source chain |
114+
| `INVALID_SYMBOL` | Unknown perpetual market symbol |
115+
| `INVALID_AMOUNT` | Invalid amount |
116+
| `INVALID_SIZE` | Invalid position size |
117+
| `INVALID_LEVERAGE` | Invalid leverage value |
118+
| `INVALID_PRICE` | Invalid price |
119+
| `INVALID_SLIPPAGE` | Invalid slippage value |
120+
| `INVALID_ADDRESS` | Invalid address |
121+
| `INSUFFICIENT_BALANCE` | Insufficient balance |
122+
| `POSITION_NOT_FOUND` | Position not found |
123+
| `QUOTE_FAILED` | Quote generation failed |
124+
| `ORDER_REJECTED` | Order rejected |
125+
| `CANCEL_FAILED` | Order cancellation failed |
126+
| `SIGNING_FAILED` | Signing operation failed |
127+
| `WITHDRAW_FAILED` | Withdrawal failed |
128+
| `DEPOSIT_FAILED` | Deposit failed |
129+
| `HYPERLIQUID_ERROR` | Hyperliquid protocol error |
130+
| `PERPS_ERROR` | Generic perpetuals error |
131+
132+
## Predict Errors
133+
134+
| Code | Meaning |
135+
| --- | --- |
136+
| `PREDICT_SETUP_REQUIRED` | Predict setup required before operation |
137+
| `PREDICT_AUTH_REQUIRED` | Predict authentication required |
138+
| `PREDICT_AUTH_INVALID` | Predict credentials invalid or incomplete |
139+
| `PREDICT_RELAYER_CONFIG_REQUIRED` | Relayer configuration required |
140+
| `PREDICT_INVALID_DEPOSIT_AMOUNT` | Invalid deposit amount |
141+
| `PREDICT_FUNDING_CHAIN_UNSUPPORTED` | Funding chain not supported |
142+
| `PREDICT_INSUFFICIENT_BALANCE` | Insufficient Predict balance |
143+
| `PREDICT_INSUFFICIENT_ALLOWANCE` | Insufficient Predict allowance |
144+
| `PREDICT_CANCEL_TARGET_REQUIRED` | Cancel target not specified |
145+
| `PREDICT_WALLET_STATE_REQUIRED` | Wallet state required for Predict |
146+
| `PREDICT_METHOD_UNAVAILABLE` | Predict method not available |
147+
148+
## Network & Filesystem Errors
149+
150+
| Code | Meaning |
151+
| --- | --- |
152+
| `NETWORK_UNREACHABLE` | Network unreachable |
153+
| `NETWORK_TIMEOUT` | Network timeout |
154+
| `NETWORK_ERROR` | Generic network error |
155+
| `RESET_FAILED` | Failed to reset CLI session |
156+
| `MNEMONIC_STORE_FAILED` | Failed to store mnemonic |
157+
| `FILESYSTEM_ERROR` | Generic filesystem error |
158+
| `TX_REVERTED` | Transaction reverted on-chain |

0 commit comments

Comments
 (0)