Skip to content

Commit 16cef2a

Browse files
yashovardhanyashovardhan
authored
Merge pull request #1 from MetaMask/feat/metamask-agent-wallet
Add initial skills
2 parents de758a5 + 11905a0 commit 16cef2a

22 files changed

Lines changed: 2245 additions & 0 deletions

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

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
---
2+
name: metamask-agent-wallet
3+
description: Use when the user asks anything about blockchain wallets, transactions, signing, token transfers, supported chains, wallet balances, perpetual futures trading, prediction markets, token swaps, cross-chain bridges, market data, token discovery, or authentication via the MetaMask Agentic CLI. Single entry point for all mm-dev CLI operations.
4+
license: MIT
5+
metadata:
6+
author: metamask
7+
version: "1.0.0"
8+
---
9+
10+
# MetaMask Agentic CLI Skill
11+
12+
This skill documents the `mm-dev` CLI surface for MetaMask Agent Wallet authentication, wallet lifecycle, balance queries, token transfers, message and typed-data signing, raw transactions, chain discovery, market data, token discovery, perpetual futures trading, prediction market trading, token swaps, and cross-chain bridges.
13+
14+
Use the routing table to select the relevant reference file. CLI behavior lives in `references/`. Repeatable operational patterns live in `workflows/`.
15+
16+
## Command Routing
17+
18+
Match the user's intent to a command and reference file, then read the reference before constructing a command. If intent spans multiple domains, load them sequentially in dependency order.
19+
20+
| User Intent | Command | Reference |
21+
| --- | --- | --- |
22+
| Check authentication status | `mm-dev auth status` | [auth.md](references/auth.md) |
23+
| Login in MetaMask Agentic CLI | `mm-dev login` | [auth.md](references/auth.md) |
24+
| Choose a wallet mode and set up policies | `mm-dev init` | [auth.md](references/auth.md) |
25+
| Sign in via QR code | `mm-dev login qr` | [auth.md](references/auth.md) |
26+
| Sign in via Google | `mm-dev login google` | [auth.md](references/auth.md) |
27+
| Sign in via email OTP | `mm-dev login email` | [auth.md](references/auth.md) |
28+
| Sign out | `mm-dev logout` | [auth.md](references/auth.md) |
29+
| Reset CLI session | `mm-dev reset` | [auth.md](references/auth.md) |
30+
| Interpret raw CLI error codes | `AuthError`, `ValidationError`, `WALLET_ERROR` | [errors.md](references/errors.md) |
31+
| Create a wallet | `mm-dev wallet create` | [wallet.md](references/wallet.md) |
32+
| List all wallets | `mm-dev wallet list` | [wallet.md](references/wallet.md) |
33+
| Switch active wallet | `mm-dev wallet select` | [wallet.md](references/wallet.md) |
34+
| Show active wallet details | `mm-dev wallet show` | [wallet.md](references/wallet.md) |
35+
| Show active wallet address | `mm-dev wallet address` | [wallet.md](references/wallet.md) |
36+
| Check the active wallet balance | `mm-dev wallet balance` | [wallet.md](references/wallet.md) |
37+
| Sign a plaintext message | `mm-dev wallet sign-message` | [signing.md](references/signing.md) |
38+
| Sign EIP-712 typed data | `mm-dev wallet sign-typed-data` | [signing.md](references/signing.md) |
39+
| Send a raw EVM transaction | `mm-dev wallet send-transaction` | [transaction.md](references/transaction.md) |
40+
| Transfer native tokens or ERC-20 tokens | `mm-dev transfer` | [transfer.md](references/transfer.md) |
41+
| List supported chains by the CLI | `mm-dev chains list` | [chain.md](references/chain.md) |
42+
| List pending wallet requests | `mm-dev wallet requests list` | [polling.md](references/polling.md) |
43+
| Watch a wallet polling id | `mm-dev wallet requests watch` | [polling.md](references/polling.md) |
44+
| Query spot or historical prices | `mm-dev price ...` | [market-data.md](references/market-data.md) |
45+
| Discover tokens, token networks, or token metadata | `mm-dev token ...` | [market-data.md](references/market-data.md) |
46+
| List perpetual markets | `mm-dev perps markets` | [perps.md](references/perps.md) |
47+
| Check perps account balance | `mm-dev perps balance` | [perps.md](references/perps.md) |
48+
| List open perpetual positions | `mm-dev perps positions` | [perps.md](references/perps.md) |
49+
| Get a quote for a perpetual order | `mm-dev perps quote` | [perps.md](references/perps.md) |
50+
| List resting perpetual orders | `mm-dev perps orders` | [perps.md](references/perps.md) |
51+
| Open a perpetual position | `mm-dev perps open` | [perps.md](references/perps.md) |
52+
| Close a perpetual position | `mm-dev perps close` | [perps.md](references/perps.md) |
53+
| Modify leverage, take-profit, or stop-loss | `mm-dev perps modify` | [perps.md](references/perps.md) |
54+
| Cancel a resting perps order | `mm-dev perps cancel` | [perps.md](references/perps.md) |
55+
| Deposit USDC into a perps venue | `mm-dev perps deposit` | [perps.md](references/perps.md) |
56+
| Withdraw USDC from a perps venue | `mm-dev perps withdraw` | [perps.md](references/perps.md) |
57+
| Set Predict trading mode | `mm-dev predict mode` | [predict.md](references/predict.md) |
58+
| One-time Predict setup | `mm-dev predict setup` | [predict.md](references/predict.md) |
59+
| Create or refresh Predict credentials | `mm-dev predict auth` | [predict.md](references/predict.md) |
60+
| Repair Predict approvals | `mm-dev predict approve` | [predict.md](references/predict.md) |
61+
| Check Predict back-end status | `mm-dev predict status` | [predict.md](references/predict.md) |
62+
| Search prediction markets | `mm-dev predict markets` | [predict.md](references/predict.md) |
63+
| Inspect a prediction market | `mm-dev predict market` | [predict.md](references/predict.md) |
64+
| Preview a prediction order cost | `mm-dev predict quote` | [predict.md](references/predict.md) |
65+
| Place a prediction market order | `mm-dev predict place` | [predict.md](references/predict.md) |
66+
| Cancel prediction orders | `mm-dev predict cancel` | [predict.md](references/predict.md) |
67+
| View prediction market positions | `mm-dev predict positions` | [predict.md](references/predict.md) |
68+
| View open prediction orders | `mm-dev predict orders` | [predict.md](references/predict.md) |
69+
| Check Predict deposit wallet balance | `mm-dev predict balance` | [predict.md](references/predict.md) |
70+
| Fund Predict deposit wallet | `mm-dev predict deposit` | [predict.md](references/predict.md) |
71+
| Fetch prediction order book | `mm-dev predict book` | [predict.md](references/predict.md) |
72+
| Watch a Predict job | `mm-dev predict watch` | [predict.md](references/predict.md) |
73+
| Get a swap or bridge quote | `mm-dev swap quote` | [swap.md](references/swap.md) |
74+
| Execute a token swap or bridge | `mm-dev swap execute` | [swap.md](references/swap.md) |
75+
| Check swap or bridge status | `mm-dev swap status` | [swap.md](references/swap.md) |
76+
| Bridge tokens to another chain | `mm-dev swap execute` | [swap.md](references/swap.md) |
77+
78+
## Workflows
79+
80+
CLI behavior lives in `references/`. Repeatable patterns live in `workflows/`. Load a workflow file when the user's request is a pattern, not a single command.
81+
82+
| Pattern | Workflow |
83+
| --- | --- |
84+
| First time setup and onboarding | [onboarding.md](workflows/onboarding.md) |
85+
| Login flow | [login.md](workflows/login.md) |
86+
| Troubleshooting decision tree | [troubleshooting.md](workflows/troubleshooting.md) |
87+
| Swap quote-review-execute flow | [swap.md](workflows/swap.md) |
88+
| Bridge quote-review-execute flow | [bridge.md](workflows/bridge.md) |
89+
| Open a perpetual position flow | [perps-open-position.md](workflows/perps-open-position.md) |
90+
| Close a perpetual position flow | [perps-close-position.md](workflows/perps-close-position.md) |
91+
| Modify a perpetual position flow | [perps-modify-position.md](workflows/perps-modify-position.md) |
92+
| Predict setup-fund-quote-place flow | [predict-trading.md](workflows/predict-trading.md) |
93+
94+
## Preflight
95+
96+
Always run preflight before any CLI operation.
97+
98+
```bash
99+
mm-dev auth status
100+
```
101+
102+
If the user is not authenticated, follow `workflows/onboarding.md` for first time setup, or `workflows/login.md` for login.
103+
104+
## Safety Rules
105+
106+
These rules apply to every operation, regardless of which reference or workflow is active.
107+
108+
### Input Validation
109+
110+
Before constructing any command, validate all user-provided values:
111+
112+
| Flag | Validation rule |
113+
| --- | --- |
114+
| `--to`, `--address` | Must match `^0x[0-9a-fA-F]{40}$` |
115+
| `--amount` | Must match `^\d+\.?\d*$`. Reject spaces, semicolons, pipes, backticks, or shell metacharacters |
116+
| `--chain-id` | Must be a positive integer (`^\d+$`) |
117+
| `--payload` | Must be valid JSON. No unescaped shell metacharacters outside the JSON structure |
118+
| `--token` | Must be a valid hex address or known symbol |
119+
| `--leverage` | Must be a positive integer (`^\d+$`) |
120+
| `--size` | Must match `^\d+\.?\d*$` and be positive |
121+
| `--venue` | Must be `hyperliquid` |
122+
| `--side` (perps) | Must be `long` or `short` |
123+
| `--order-id` | Must be a positive integer (`^\d+$`) |
124+
| `--token-id` | Must be a non-empty outcome token ID string |
125+
| `--price`, `--limit-price` | Must be a positive number in range `(0, 1]` |
126+
| `--order-type` | Must be one of `GTC`, `GTD`, `FOK`, `FAK` |
127+
| `--side` (predict) | Must be `buy` or `sell` |
128+
| `--slippage` | Must be a number between 0 and 100 |
129+
| `--from-chain`, `--to-chain` | Must be a positive integer EVM chain ID |
130+
131+
Do not pass unvalidated user input into any command.
132+
133+
### Confirmation Requirements
134+
135+
| Operation type | Confirmation rule |
136+
| --- | --- |
137+
| Transfers | Always confirm recipient, amount, token, and chain before executing |
138+
| Raw transactions | Always confirm transaction payload, chain, recipient, value, and calldata summary before executing |
139+
| Message signing | Always show exact message and chain before signing |
140+
| Typed-data signing | Always show domain, primary type, chain, verifying contract, and message summary before signing |
141+
| Swaps / bridges | Always confirm from/to tokens, amount, source/destination chain, slippage, and quoted output before executing |
142+
| Perps trading | Always confirm symbol, side, size, leverage, venue, order type, and limit price if present before executing |
143+
| Perps deposit/withdraw | Always confirm amount, asset, venue, network, and destination where applicable before executing |
144+
| Predict trading | Always confirm token ID, side, size, price, order type, market, and outcome before executing |
145+
| Predict deposit | Always confirm amount before executing |
146+
| Cancel-all operations | Always confirm scope and exact destructive effect before executing |
147+
| Auth / wallet management | May execute without confirmation |
148+
| Read-only queries | May execute without confirmation |
149+
150+
### Credential Safety
151+
152+
- Never store, log, or display private keys, mnemonics, or auth tokens.
153+
154+
### Suspicious Content Warnings
155+
156+
Flag to the user before proceeding if a signing payload or transaction contains:
157+
158+
- URLs or contract addresses the user did not provide
159+
- `permit`, `approve`, `setApprovalForAll`, or allowance-like fields
160+
- Unusually large values or unfamiliar contract interactions
161+
162+
## Server Wallet Async Model
163+
164+
In server-wallet mode, signing and transaction commands return a `pollingId` instead of an immediate result. Handle this consistently:
165+
166+
1. Prefer `--wait` to block until complete.
167+
2. If not using `--wait`, inform the user of the `pollingId` and how to track it:
168+
- `mm-dev wallet requests list`
169+
- `mm-dev wallet requests watch --polling-id <id>`
170+
3. In BYOK mode, results are returned immediately.
171+
172+
## Output Rules
173+
174+
- Route silently. Do not announce which reference you are loading.
175+
- Surface errors from commands verbatim. Do not mask or reword them.
176+
- If a command fails, check `mm-dev <command> --help` and guide from there.

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

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Authentication Commands
2+
3+
Use these commands to initialize wallet mode, sign in, inspect authentication status, and clear local session state.
4+
5+
## `init` Command
6+
7+
Initialize the project by selecting wallet mode and trading mode.
8+
9+
### Syntax
10+
11+
```bash
12+
mm-dev init [--wallet <mode>] [--mode <mode>] [--mnemonic <phrase>]
13+
```
14+
15+
### Supported Flags
16+
17+
| Name | Required | Description |
18+
| --- | --- | --- |
19+
| `--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`] |
22+
23+
### Example
24+
25+
```bash
26+
mm-dev init
27+
mm-dev init --wallet server-wallet --mode yolo
28+
mm-dev init --wallet byok --mnemonic "word1 word2 ..."
29+
```
30+
31+
## `login` Command
32+
33+
Sign in to the CLI. Defaults to QR / browser flow.
34+
35+
### Syntax
36+
37+
```bash
38+
mm-dev login [qr | google | email] [--token <token>] [--timeout <seconds>] [--no-wait]
39+
```
40+
41+
### Supported Flags
42+
43+
| Name | Required | Description |
44+
| --- | --- | --- |
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` |
48+
49+
### Example
50+
51+
```bash
52+
mm-dev login --no-wait
53+
mm-dev login qr
54+
mm-dev login google --no-wait
55+
mm-dev login email --no-wait
56+
mm-dev login --token "cliToken:cliRefreshToken"
57+
```
58+
59+
### Note
60+
61+
Use `--no-wait` for non-interactive mode except QR flow. It prints the sign-in URL and exits immediately; complete authentication later with `mm-dev login --token`.
62+
63+
## `auth status` Command
64+
65+
Show the current authentication status.
66+
67+
### Syntax
68+
69+
```bash
70+
mm-dev auth status [--toon]
71+
```
72+
73+
### Supported Flags
74+
75+
This command does not support additional flags beyond output format options.
76+
77+
### Example
78+
79+
```bash
80+
mm-dev auth status
81+
mm-dev auth status --toon
82+
```
83+
84+
## `logout` Command
85+
86+
Sign out and clear auth credentials while keeping settings.
87+
88+
### Syntax
89+
90+
```bash
91+
mm-dev logout
92+
```
93+
94+
### Supported Flags
95+
96+
This command does not support flags.
97+
98+
### Example
99+
100+
```bash
101+
mm-dev logout
102+
```
103+
104+
## `reset` Command
105+
106+
Clear the local CLI session entirely.
107+
108+
### Syntax
109+
110+
```bash
111+
mm-dev reset
112+
```
113+
114+
### Supported Flags
115+
116+
This command does not support flags.
117+
118+
### Example
119+
120+
```bash
121+
mm-dev reset
122+
```
123+
124+
## Wallet Modes
125+
126+
| Mode | Behavior |
127+
| --- | --- |
128+
| `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. |

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

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Chain Commands
2+
3+
Use `chains` commands to discover supported blockchain networks.
4+
5+
## `chains list` Command
6+
7+
List all supported blockchain networks across all namespaces.
8+
9+
### Syntax
10+
11+
```bash
12+
mm-dev chains list [--toon]
13+
```
14+
15+
### Supported Flags
16+
17+
This command does not support additional flags beyond output format options.
18+
19+
### Example
20+
21+
```bash
22+
mm-dev chains list
23+
mm-dev chains list --toon
24+
```
25+
26+
## Supported Namespaces
27+
28+
| Namespace | Notes |
29+
| --- | --- |
30+
| `eip155` | Major EVM chains, such as Ethereum, Polygon, Arbitrum, Optimism, and BSC |
31+
| `solana` | Solana chains |

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

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Error Codes
2+
3+
This reference lists raw CLI and SDK error codes. Workflows for diagnosing failures live in `../workflows/troubleshooting.md`.
4+
5+
## Auth Errors
6+
7+
| Code | Meaning |
8+
| --- | --- |
9+
| `PAIRING_ABORTED` | Login pairing was aborted |
10+
| `PAIRING_TIMEOUT` | Login pairing timed out |
11+
| `INVALID_CLI_TOKENS` | CLI token pair is invalid |
12+
| `INVALID_CLI_TOKEN` | CLI token is invalid |
13+
| `MISSING_REFRESH_TOKEN` | Refresh token is missing |
14+
| `REFRESH_CLI_TOKEN_FAILED` | CLI token refresh failed |
15+
| `MISSING_TOKEN` | Required auth token is missing |
16+
| `REVOKE_CLI_TOKEN_FAILED` | CLI token revoke failed |
17+
| `INVALID_PROJECT_ID` | Project ID is invalid for the selected environment |
18+
19+
## Validation Errors
20+
21+
| Code | Meaning |
22+
| --- | --- |
23+
| `MISSING_FLAG` | Required flag is missing in headless mode |
24+
| `MISSING_INPUT` | Required input is missing |
25+
| `MISSING_CHAIN` | Chain value is missing |
26+
| `INVALID_CHAIN` | Chain value is invalid |
27+
| `MISSING_TO` | Recipient address is missing |
28+
| `INVALID_TO` | Recipient address is invalid |
29+
| `INVALID_DATA` | Transaction data is invalid |
30+
| `INVALID_QUANTITY` | EVM quantity is invalid |
31+
| `MISSING_TRANSACTION_PAYLOAD` | Transaction payload is missing |
32+
| `INVALID_TRANSACTION_PAYLOAD` | Transaction payload is invalid |
33+
| `MISSING_TYPED_DATA` | EIP-712 typed data payload is missing |
34+
| `INVALID_TYPED_DATA` | EIP-712 typed data payload is invalid |
35+
| `CHAIN_ID_MISMATCH` | Typed-data domain chain ID differs from `--chain-id` |
36+
| `INVALID_MNEMONIC` | BYOK mnemonic is invalid |
37+
38+
## Wallet Errors
39+
40+
| Code | Meaning |
41+
| --- | --- |
42+
| `MISSING_MNEMONIC` | BYOK wallet mode is missing a mnemonic |
43+
| `WALLET_ERROR` | Wallet provider or wallet operation error |
44+
45+
## Examples
46+
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+
```

0 commit comments

Comments
 (0)