diff --git a/skills/metamask-agent-wallet/SKILL.md b/skills/metamask-agent-wallet/SKILL.md index 4f646cb..01fc91f 100644 --- a/skills/metamask-agent-wallet/SKILL.md +++ b/skills/metamask-agent-wallet/SKILL.md @@ -42,6 +42,8 @@ Match the user's intent to a command and reference file, then read the reference | Show active wallet details | `mm wallet show` | [wallet.md](references/wallet.md) | | Show active wallet address | `mm wallet address` | [wallet.md](references/wallet.md) | | Check the active wallet balance | `mm wallet balance` | [wallet.md](references/wallet.md) | +| Show current trading mode and policies | `mm wallet trading-mode get` | [wallet.md](references/wallet.md) | +| Set trading mode (guard or beast) | `mm wallet trading-mode set` | [wallet.md](references/wallet.md) | | Sign a plaintext message | `mm wallet sign-message` | [signing.md](references/signing.md) | | Sign EIP-712 typed data | `mm wallet sign-typed-data` | [signing.md](references/signing.md) | | Send a raw EVM transaction | `mm wallet send-transaction` | [transaction.md](references/transaction.md) | @@ -69,7 +71,7 @@ Match the user's intent to a command and reference file, then read the reference | 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) | | Repair Predict approvals | `mm predict approve` | [predict.md](references/predict.md) | -| Check Predict back-end status | `mm predict status` | [predict.md](references/predict.md) | +| Check Predict back-end status and account setup | `mm predict status` | [predict.md](references/predict.md) | | Check if Polymarket is geoblocked for your IP | `mm predict geoblock` | [predict.md](references/predict.md) | | List prediction markets | `mm predict markets list` | [predict.md](references/predict.md) | | Search prediction markets | `mm predict markets search` | [predict.md](references/predict.md) | @@ -112,7 +114,12 @@ CLI behavior lives in `references/`. Repeatable patterns live in `workflows/`. L | Open a perpetual position flow | [perps-open-position.md](workflows/perps-open-position.md) | | Close a perpetual position flow | [perps-close-position.md](workflows/perps-close-position.md) | | Modify a perpetual position flow | [perps-modify-position.md](workflows/perps-modify-position.md) | -| Predict setup-fund-quote-place flow | [predict-trading.md](workflows/predict-trading.md) | +| Predict first-time setup and credentials | [predict-setup.md](workflows/predict-setup.md) | +| Deposit or withdraw pUSD from Predict wallet | [predict-funding.md](workflows/predict-funding.md) | +| Search and browse prediction markets | [predict-markets.md](workflows/predict-markets.md) | +| Quote and place a prediction order | [predict-place-order.md](workflows/predict-place-order.md) | +| View or cancel Predict orders and positions | [predict-manage-orders.md](workflows/predict-manage-orders.md) | +| View Predict portfolio and redeem winnings | [predict-portfolio.md](workflows/predict-portfolio.md) | | Token discovery, prices, and market data | [market-data.md](workflows/market-data.md) | ## Global Flags @@ -187,6 +194,7 @@ Before constructing any command, validate all user-provided values: | `--side` (predict) | Must be `buy` or `sell` | | `--slippage` | Must be a number between 0 and 100 | | `--from-chain`, `--to-chain` | Must be a positive integer EVM chain ID | +| `--to-address` | Must match `^0x[0-9a-fA-F]{40}$`. Only valid for cross-chain swaps (`--to-chain` differs from `--from-chain`); rejected for same-chain swaps | | `--password` | Must be a non-empty string. Never log, display, or store the value. | Do not pass unvalidated user input into any command. @@ -199,7 +207,7 @@ Do not pass unvalidated user input into any command. | Raw transactions | Always confirm transaction payload, chain, recipient, value, and calldata summary before executing | | Message signing | Always show exact message and chain before signing | | 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, and quoted output before executing | +| Swaps / bridges | Always confirm from/to tokens, amount, source/destination chain, slippage, quoted output, and recipient address (if `--to-address` is set) before executing | | Perps trading | Always confirm symbol, side, size, leverage, venue, order type, and limit price if present before executing | | Perps deposit/withdraw | Always confirm amount, asset, venue, network, and destination where applicable before executing | | Predict trading | Always confirm token ID, side, size, price, order type, market, and outcome before executing | diff --git a/skills/metamask-agent-wallet/references/decode.md b/skills/metamask-agent-wallet/references/decode.md index f4da733..5a36084 100644 --- a/skills/metamask-agent-wallet/references/decode.md +++ b/skills/metamask-agent-wallet/references/decode.md @@ -12,13 +12,11 @@ Decode hex-encoded EVM calldata into its function name, parameters, and a plain- mm decode --payload <0x-calldata> [--toon] ``` -The payload can also be passed positionally: `mm decode <0x-calldata>`. - ### Supported Flags | Name | Required | Description | | --- | --- | --- | -| `--payload` | Yes | Hex-encoded EVM calldata to decode (e.g. `0x095ea7b3...`). Positional index 0 | +| `--payload` | Yes | Hex-encoded EVM calldata to decode (e.g. `0x095ea7b3...`). | ### Output @@ -31,8 +29,7 @@ The payload can also be passed positionally: `mm decode <0x-calldata>`. ### Example ```bash -mm decode --payload 0x095ea7b3000000000000000000000000... -mm decode 0x095ea7b3000000000000000000000000... --toon +mm decode --payload 0x095ea7b3000000000000000000000000... --toon ``` ## Notes diff --git a/skills/metamask-agent-wallet/references/errors.md b/skills/metamask-agent-wallet/references/errors.md index 93e68e4..5e6b890 100644 --- a/skills/metamask-agent-wallet/references/errors.md +++ b/skills/metamask-agent-wallet/references/errors.md @@ -66,6 +66,8 @@ This reference lists error codes the CLI actually emits. SDK-only or remapped co | `NO_AUTH_TOKEN` | Missing authentication token for wallet operations | | `NO_PROJECT_ID` | Project ID not configured for wallet | | `MISSING_PROJECT_ID` | Project ID is not configured | +| `INVALID_TRADING_MODE` | Invalid trading mode; use `guard` or `beast` | +| `ALREADY_SET_TRADING_MODE` | Trading mode is already set to the requested value | ## Command Errors diff --git a/skills/metamask-agent-wallet/references/predict.md b/skills/metamask-agent-wallet/references/predict.md index 2c88d16..9f57f50 100644 --- a/skills/metamask-agent-wallet/references/predict.md +++ b/skills/metamask-agent-wallet/references/predict.md @@ -92,7 +92,7 @@ mm predict approve --wait ## `predict status` Command -Probe Predict back-end reachability (Gamma + CLOB). +Probe Predict back-end reachability (Gamma + CLOB) and report account setup status: deposit wallet address, on-chain deployment, stored CLOB credentials, and a `setupComplete` flag. ### Syntax diff --git a/skills/metamask-agent-wallet/references/swap.md b/skills/metamask-agent-wallet/references/swap.md index 402f527..c9a942e 100644 --- a/skills/metamask-agent-wallet/references/swap.md +++ b/skills/metamask-agent-wallet/references/swap.md @@ -9,7 +9,7 @@ Get a swap or bridge quote showing expected output, fees, and route. ### Syntax ```bash -mm swap quote --from --to --amount --from-chain [--to-chain ] [--slippage ] +mm swap quote --from --to --amount --from-chain [--to-chain ] [--to-address
] [--slippage ] ``` ### Supported Flags @@ -20,7 +20,8 @@ mm swap quote --from --to --amount --from-chain [--password ] -mm swap execute --from --to --amount --from-chain [--to-chain ] [--slippage ] [--password ] +mm swap execute --from --to --amount --from-chain [--to-chain ] [--to-address
] [--slippage ] [--password ] ``` ### Supported Flags @@ -52,7 +54,8 @@ mm swap execute --from --to --amount --from-chain [--tx-hash ] | Name | Required | Description | | --- | --- | --- | | `--quote-id` | Yes | Quote ID returned by `mm swap quote` | -| `--tx-hash` | No | Source transaction hash; overrides the stored hash from execute | +| `--tx-hash` | No | Source transaction hash. Overrides the stored hash from execute | ### Example diff --git a/skills/metamask-agent-wallet/references/wallet.md b/skills/metamask-agent-wallet/references/wallet.md index 276faae..e882c1e 100644 --- a/skills/metamask-agent-wallet/references/wallet.md +++ b/skills/metamask-agent-wallet/references/wallet.md @@ -18,7 +18,7 @@ mm wallet create [--chain-namespace ] [--name ] [--trading-mode | --- | --- | --- | | `--chain-namespace` | No | Wallet chain namespace: `evm` (EIP-155) (allowed: `evm`) | | `--name` | No | Display name for the wallet | -| `--trading-mode` | No | Trading mode for server wallets: `guard` (enforces outflow/whitelist policies) or `beast` (skips policy checks). Only applies to server-wallet mode (allowed: `guard`, `beast`) | +| `--trading-mode` | No | `guard` enforces outflow/whitelist policies and blocks malicious transactions. `beast` skips policy checks but still blocks malicious transactions. Only applies to server-wallet mode (allowed: `guard`, `beast`) | | `--password` | No | Password to unlock the BYOK mnemonic (BYOK mode only) [env: `MM_PASSWORD`] | ### Example @@ -127,6 +127,45 @@ mm wallet address mm wallet address --chain-namespace evm ``` +## `wallet trading-mode get` Command + +Show the current trading mode, active server-wallet address, and policies for the selected wallet. Server-wallet mode only. + +### Syntax + +```bash +mm wallet trading-mode get +``` + +### Example + +```bash +mm wallet trading-mode get +``` + +## `wallet trading-mode set` Command + +Set the trading mode for the active server wallet. Prompts for confirmation when switching to Beast mode. Rejects if the mode is already set or the session isn't in server-wallet mode. + +### Syntax + +```bash +mm wallet trading-mode set +``` + +### Supported Flags + +| Name | Required | Description | +| --- | --- | --- | +| `` | Yes | `guard` enforces outflow/whitelist policies and blocks malicious transactions. `beast` skips policy checks but still blocks malicious transactions | + +### Example + +```bash +mm wallet trading-mode set guard +mm wallet trading-mode set beast +``` + ## `wallet balance` Command Show native and token balances for the active wallet. diff --git a/skills/metamask-agent-wallet/workflows/bridge.md b/skills/metamask-agent-wallet/workflows/bridge.md index 3172d2d..a21133c 100644 --- a/skills/metamask-agent-wallet/workflows/bridge.md +++ b/skills/metamask-agent-wallet/workflows/bridge.md @@ -1,4 +1,4 @@ -# Bridge Workflow +# Bridge workflow Use this workflow when the user wants to bridge tokens across chains. @@ -10,7 +10,7 @@ Reference command syntax in `references/swap.md`. The CLI uses the same `swap` c 2. Confirm with the user. 3. Execute and track status. -Do not skip the quote review step. It is where the user sees output amount, fees, route, and slippage. +Don't skip the quote review step. The user needs to see output amount, fees, route, and slippage before executing. ## Quote @@ -20,8 +20,14 @@ mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 --to-chain 137 --sl Required flags: `--from`, `--to`, `--amount`, `--from-chain`, and `--to-chain`. +If the user wants the bridged tokens sent to a different wallet on the destination chain, add `--to-address`: + +```bash +mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 --to-chain 137 --to-address 0x742d...f2bD18 +``` + Persist the quote id for execution. Show the quote to the user before execution. -Confirm source token, destination token, amount, source chain, destination chain, slippage, expected output, fees, and route. +Confirm source token, destination token, amount, source chain, destination chain, slippage, expected output, fees, route, and recipient address (if `--to-address` was set). ## Execute @@ -40,7 +46,7 @@ mm swap status --quote-id "QUOTE_ID" --tx-hash 0xabc123 Use status polling for bridges where the destination side can lag behind the source transaction. -## Edge Cases +## Edge cases - Quote expired: re-quote and ask the user to review the new quote. - Insufficient balance: surface the error verbatim. diff --git a/skills/metamask-agent-wallet/workflows/login.md b/skills/metamask-agent-wallet/workflows/login.md index 1ae13ec..fcf689a 100644 --- a/skills/metamask-agent-wallet/workflows/login.md +++ b/skills/metamask-agent-wallet/workflows/login.md @@ -6,10 +6,9 @@ Reference command syntax in `references/auth.md`. ## Flow -1. Confirm the target environment with `mm config get env` (set with `mm config set env` before login if not `prod`). -2. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email. -3. Execute login. -4. Verify with token. +1. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email. +2. Execute login. +3. Verify with token. ## Login diff --git a/skills/metamask-agent-wallet/workflows/onboarding.md b/skills/metamask-agent-wallet/workflows/onboarding.md index f2b3f44..e479be5 100644 --- a/skills/metamask-agent-wallet/workflows/onboarding.md +++ b/skills/metamask-agent-wallet/workflows/onboarding.md @@ -7,11 +7,10 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`. ## Flow 1. Check CLI installation. -2. Configure environment (if not using production). -3. Login. -4. Initialize wallet mode. -5. Verify auth status. -6. Show wallet address. +2. Login. +3. Initialize wallet mode. +4. Verify auth status. +5. Show wallet address. ## Check CLI Installation @@ -23,19 +22,6 @@ If this fails, the CLI is not installed. Guide the user to install it with `npm Then run the version compatibility check from the skill `Preflight` section: compare the installed `major.minor` against the pinned `cliVersion` and the latest published release, and warn the user if they are out of sync. -## Configure Environment - -Production (`prod`) is the default. Set the target environment **before** login if the user needs dev or uat: - -```bash -mm config get env -mm config set env dev -``` - -For a one-off override without persisting, use `MM_ENV=dev mm login` (or `uat`). - -To switch environments, run `mm config set env `. - ## Login Flow Ask the user which login method they want to use: MetaMask Mobile QR, Google, or Email. QR (`mm login qr`) is available on non-production builds (dev/uat); on production it returns `COMING_SOON`, so fall back to Google or email there. diff --git a/skills/metamask-agent-wallet/workflows/perps-open-position.md b/skills/metamask-agent-wallet/workflows/perps-open-position.md index a315631..2712341 100644 --- a/skills/metamask-agent-wallet/workflows/perps-open-position.md +++ b/skills/metamask-agent-wallet/workflows/perps-open-position.md @@ -1,4 +1,4 @@ -# Perps Open Position Workflow +# Perps open position workflow Use this workflow when the user wants to open a new perpetual position. @@ -11,17 +11,17 @@ Reference command syntax in `references/perps.md`. 3. Dry run. 4. Confirm with the user and open. -## Confirm Symbol +## Confirm symbol -If the user does not mention a token symbol, list available markets and confirm with the user: +If the user doesn't mention a token symbol, list available markets and confirm with the user: ```bash mm perps markets ``` -## Check Balance +## Check balance -`--venue` defaults to `hyperliquid`. It can be omitted. +`--venue` defaults to `hyperliquid`. You can omit it. ```bash mm perps balance @@ -29,11 +29,45 @@ mm perps balance If available margin is zero or insufficient, deposit USDC before proceeding. Hyperliquid only supports deposits from Arbitrum mainnet (`eip155:42161`). +Check the user's Arbitrum balance for USDC and ETH (for gas). + +```bash +mm wallet balance --chain 42161 +``` + +### No ETH and no USDC on Arbitrum + +Inform the user that ETH on Arbitrum is required for gas. Without ETH, no on-chain transaction is possible. Bridge from another chain. + +```bash +mm swap quote --from --to ETH --amount 0.001 --from-chain --to-chain 42161 +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +Once the user has ETH for gas, swap or bridge to get USDC on Arbitrum. + +```bash +mm swap quote --from --to USDC --amount --from-chain --to-chain 42161 +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +### Has ETH or another token on Arbitrum (but no USDC) + +Swap to USDC on Arbitrum. + +```bash +mm swap quote --from --to USDC --amount --from-chain 42161 +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +### Has ETH and USDC on Arbitrum + +Deposit USDC directly into Hyperliquid. + ```bash -mm perps deposit --amount --asset USDC +mm perps deposit --amount --asset USDC ``` -To confirm a deposit, wait briefly and poll `mm perps balance`. ## Quote @@ -45,7 +79,7 @@ mm perps quote --symbol BTC --side long --size 0.01 --leverage 5 Show the user estimated entry, notional, fees, liquidation price, side, size, leverage, and venue before proceeding. -## Dry Run +## Dry run Preview the order before signing: @@ -65,4 +99,4 @@ Remove `--dry-run` only after explicit user confirmation: mm perps open --symbol BTC --side long --size 0.01 --leverage 5 ``` -Do not add `--yes` unless the user explicitly asked for unattended execution. +Don't add `--yes` unless the user explicitly asked for unattended execution. diff --git a/skills/metamask-agent-wallet/workflows/predict-funding.md b/skills/metamask-agent-wallet/workflows/predict-funding.md new file mode 100644 index 0000000..2236e80 --- /dev/null +++ b/skills/metamask-agent-wallet/workflows/predict-funding.md @@ -0,0 +1,90 @@ +# Predict funding workflow + +Use this workflow to deposit or withdraw pUSD from the Predict deposit wallet. + +Reference command syntax in `references/predict.md`. + +## Flow + +1. Check deposit wallet balance. +2. Deposit or withdraw. + +## Check deposit wallet balance + +```bash +mm predict balance --sync +``` + +## Deposit + +If the user doesn't specify an amount, ask how much they want to deposit. Get the deposit wallet address from `mm predict status`, then check the user's Polygon balance. + +```bash +mm wallet balance --chain 137 +``` + +### Has POL and pUSD on Polygon + +Use `mm transfer` to send pUSD directly to the deposit wallet address. No conversion needed. Get the pUSD contract address from `mm wallet balance --chain 137` output. + +```bash +mm transfer --to --amount --chain-id 137 --token --wait +``` + +Get the deposit wallet address from the `mm predict status` output. + +### Has POL and USDC.e on Polygon + +Run `mm predict deposit`. The CLI converts USDC.e to pUSD in the deposit wallet. + +```bash +mm predict deposit --amount --wait +``` + +`--amount` is in USDC.e. The owner EOA needs enough USDC.e and POL for gas on Polygon. + +### Has POL or another token on Polygon (but no USDC.e or pUSD) + +Swap to pUSD on Polygon, then transfer directly to the deposit wallet. The owner EOA needs POL for gas. + +```bash +mm swap quote --from --to pUSD --amount --from-chain 137 +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +After the swap completes, check the balance to verify pUSD arrived + +```bash +mm wallet balance --chain 137 +``` + +Get the pUSD contract address from the balance output, then transfer to the deposit wallet: + +```bash +mm transfer --to --amount --chain-id 137 --token --wait +``` + +Get the deposit wallet address from the `mm predict status` output. + +### Has assets on another chain + +Bridge to send pUSD directly to the deposit wallet address on Polygon. + +```bash +mm swap quote --from --to pUSD --amount --from-chain --to-chain 137 --to-address +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +Get the deposit wallet address from the `mm predict status` output. This avoids the extra deposit step. + + +## Withdraw + +Withdraw pUSD from the deposit wallet to the owner EOA (default) or a specified address. + +```bash +mm predict withdraw --amount --wait +mm predict withdraw --amount --to --wait +``` + +Confirm the amount and recipient with the user before executing. The CLI validates the amount against the on-chain deposit wallet balance before signing. diff --git a/skills/metamask-agent-wallet/workflows/predict-manage-orders.md b/skills/metamask-agent-wallet/workflows/predict-manage-orders.md new file mode 100644 index 0000000..5fd10d7 --- /dev/null +++ b/skills/metamask-agent-wallet/workflows/predict-manage-orders.md @@ -0,0 +1,50 @@ +# Predict manage orders workflow + +Use this workflow to view, cancel, or manage open Predict orders and positions. + +Reference command syntax in `references/predict.md`. + +## View orders + +```bash +mm predict orders +mm predict orders --market +``` + +## View positions + +```bash +mm predict positions +mm predict positions --market +``` + +## Cancel orders + +Cancel a single order: + +```bash +mm predict cancel --order-id +``` + +Cancel by market or asset: + +```bash +mm predict cancel --market +mm predict cancel --asset +``` + +Cancel all open orders: + +```bash +mm predict cancel --all +``` + +`predict cancel --all` cancels every open order. Require explicit confirmation from the user before executing. + +## Watch async jobs + +```bash +mm predict watch --id --wait +``` + +Use this for setup, approve, deposit, withdraw, redeem, and order jobs that haven't reached a terminal state. diff --git a/skills/metamask-agent-wallet/workflows/predict-markets.md b/skills/metamask-agent-wallet/workflows/predict-markets.md new file mode 100644 index 0000000..64d37e0 --- /dev/null +++ b/skills/metamask-agent-wallet/workflows/predict-markets.md @@ -0,0 +1,45 @@ +# Predict markets workflow + +Use this workflow to search, browse, and inspect prediction markets on Polymarket. + +Reference command syntax in `references/predict.md`. + +## Flow + +1. Search or browse markets. +2. Inspect the selected market to get outcome token IDs. + +## Search markets + +```bash +mm predict markets search "Knicks NBA Finals" --limit 5 --toon +``` + +Search can return loosely related markets, so always inspect the selected market before quoting. + +If search is noisy, list active markets and filter manually: + +```bash +mm predict markets list --active --limit 50 --toon +``` + +## Browse by topic + +Use events, series, and tags to browse by topic. Resolve a tag slug or ID first, then filter: + +```bash +mm predict tags list --limit 50 --toon +mm predict events list --tag-slug sports --active --limit 10 --toon +mm predict events get --toon +mm predict series list --recurrence weekly --limit 10 --toon +``` + +These browse commands don't return outcome token IDs. Drill into a specific market with `mm predict markets get` before quoting or placing. + +## Inspect a market + +```bash +mm predict markets get --toon +``` + +The market detail prints outcome token IDs. Outcome token IDs aren't market IDs. Use the token ID for `quote`, `place`, `book`, and `balance --token-id`. diff --git a/skills/metamask-agent-wallet/workflows/predict-place-order.md b/skills/metamask-agent-wallet/workflows/predict-place-order.md new file mode 100644 index 0000000..c5372a8 --- /dev/null +++ b/skills/metamask-agent-wallet/workflows/predict-place-order.md @@ -0,0 +1,72 @@ +# Predict place order workflow + +Use this workflow to quote and place a prediction market order. + +Reference command syntax in `references/predict.md`. + +## Flow + +1. Check setup and balance. +2. Inspect the market to get the outcome token ID. +3. Quote the order. +4. Confirm with the user and place. + +## Check setup and balance + +Verify that Predict is fully set up and get the deposit wallet address: + +```bash +mm predict status +``` + +Check `setupComplete` is `true`. If not, follow `predict-setup.md` to run first-time setup. + +Then check the deposit wallet balance: + +```bash +mm predict balance --sync +``` + +If the balance is zero or insufficient for the order, follow `predict-funding.md` to deposit funds. Use the deposit wallet address from `mm predict status` when funding. + +## Get outcome token ID + +If the user hasn't already identified the market, follow `predict-markets.md` to find and inspect it. + +```bash +mm predict markets get --toon +``` + +Map the user's intended outcome to the correct token ID from the market detail. + +## Quote + +Preview the order cost and fill before placing: + +```bash +mm predict quote \ + --token-id \ + --side buy --size 100 --limit-price 0.55 +``` + +Show the user the estimated cost and fill. + +## Place + +After the user confirms token ID, outcome, side, size, price, and order type: + +```bash +mm predict place \ + --token-id \ + --side buy --size 100 --price 0.55 \ + --order-type GTC +``` + +`--order-type` is one of `GTC`, `GTD`, `FOK`, or `FAK`. `--post-only` only applies to GTC/GTD. `--expiration` is unix seconds for GTD. + +## Safety notes + +- Placing orders between a market's end date and its final UMA resolution carries major financial risk. Prices during this window don't reflect true odds and arbitrage strategies can fail if UMA resolves unexpectedly. If the order creation time is after the market end date but before UMA resolution, warn the user about potential financial loss and get explicit confirmation before proceeding. +- Prices are 0-1 floats. Treat `--price 1` as suspicious unless the user explicitly confirms. +- Trades are signed by the deposit wallet address from `mm predict status`, not the connected owner EOA. +- Always inspect the market to map the user's intended outcome to the correct token ID. diff --git a/skills/metamask-agent-wallet/workflows/predict-portfolio.md b/skills/metamask-agent-wallet/workflows/predict-portfolio.md new file mode 100644 index 0000000..05357a2 --- /dev/null +++ b/skills/metamask-agent-wallet/workflows/predict-portfolio.md @@ -0,0 +1,35 @@ +# Predict portfolio workflow + +Use this workflow to view the Predict portfolio or redeem winning positions. + +Reference command syntax in `references/predict.md`. + +## View portfolio + +Get a single snapshot of balance, open positions, and redeemable winnings: + +```bash +mm predict portfolio --toon +``` + +## Redeem winnings + +After a market resolves, list and claim winning positions: + +```bash +mm predict redeem list --toon +``` + +Redeem a single position: + +```bash +mm predict redeem --wait +``` + +Redeem all winning positions: + +```bash +mm predict redeem --all --wait +``` + +`predict redeem --all` redeems every winning position. Confirm the target (condition ID or `--all`) with the user before executing. With `--wait`, the CLI polls for the redemption transaction receipt. diff --git a/skills/metamask-agent-wallet/workflows/predict-setup.md b/skills/metamask-agent-wallet/workflows/predict-setup.md new file mode 100644 index 0000000..3aa2985 --- /dev/null +++ b/skills/metamask-agent-wallet/workflows/predict-setup.md @@ -0,0 +1,54 @@ +# Predict setup workflow + +Use this workflow for first-time Predict setup, refreshing credentials, or repairing approvals. + +Reference command syntax in `references/predict.md`. + +## Flow + +1. Choose Predict mode. +2. Run one-time setup. +3. Verify status. + +## Choose mode + +```bash +mm predict mode mainnet +``` + +Replace `mainnet` with `testnet` if the user wants to paper trade. + +## Run setup + +```bash +mm predict setup --wait +``` + +This blocks until credential, deposit-wallet, and approval jobs complete. Without `--wait`, track returned jobs with `mm predict watch --id --wait`. + +The owner EOA needs POL on Polygon for gas to complete the setup transactions. + +Polymarket is geoblocked in some regions. `predict setup` checks the caller's IP first and aborts with `PREDICT_GEOBLOCKED` before any wallet interaction if the region is restricted. To check region status independently: + +```bash +mm predict geoblock +``` + +## Verify status + +Confirm `setupComplete` is `true` and note the deposit wallet address: + +```bash +mm predict status +``` + +## Refresh credentials or approvals + +If credentials or approvals look stale later: + +```bash +mm predict auth --refresh +mm predict approve --wait +``` + +Then verify with `mm predict status`. diff --git a/skills/metamask-agent-wallet/workflows/predict-trading.md b/skills/metamask-agent-wallet/workflows/predict-trading.md deleted file mode 100644 index fd5d5ad..0000000 --- a/skills/metamask-agent-wallet/workflows/predict-trading.md +++ /dev/null @@ -1,162 +0,0 @@ -# Predict Trading Workflow - -Use this workflow when the user wants to set up prediction market trading, fund the deposit wallet, quote/place orders, or manage Predict orders and positions. - -Reference command syntax in `../references/predict.md`. - -## One-Time Setup - -Choose the Predict mode, run setup, and check backend status: - -```bash -mm predict mode mainnet -mm predict setup --wait -mm predict status -``` - -`predict setup --wait` blocks until credential, deposit-wallet, and approval jobs complete. Without `--wait`, watch returned jobs with `mm predict watch`. - -Polymarket is geoblocked in some regions. `mm predict setup` checks the caller's IP first and aborts with `PREDICT_GEOBLOCKED` before any wallet interaction if the region is restricted. To check region status independently, run: - -```bash -mm predict geoblock -``` - -If setup or approvals look stale later: - -```bash -mm predict auth --refresh -mm predict approve --wait -mm predict balance --sync -``` - -`predict setup` and `predict deposit` use `--wait`; do not add `--yes` to those commands. - -## Fund the Deposit Wallet - -Check deposit wallet status: - -```bash -mm predict balance --sync -``` - -Fund pUSD: - -```bash -mm predict deposit --amount 100 --wait --json -``` - -`--amount` is in pUSD. The owner EOA needs enough Polygon USDC and POL for gas to complete the deposit transaction. - -## Withdraw from the Deposit Wallet - -Check balance first: - -```bash -mm predict balance --sync -``` - -Withdraw pUSD to the owner EOA (default) or a specified address: - -```bash -mm predict withdraw --amount 50 --wait -mm predict withdraw --amount 10 --to 0xRecipient... --wait -``` - -The CLI validates the amount against the on-chain deposit wallet balance before signing. Confirm amount and recipient with the user before executing. - -## Find the Right Market - -Search can return loosely related markets, so inspect the selected market before quoting: - -```bash -mm predict markets search "Knicks NBA Finals" --limit 5 --json -mm predict markets get will-the-new-york-knicks-win-the-2026-nba-finals --json -``` - -The market detail prints outcome token IDs. Outcome token IDs are not market IDs; use the token ID for `quote`, `place`, `book`, and `balance --token-id`. - -If search is noisy, list active markets and filter manually: - -```bash -mm predict markets list --active --limit 50 --json -``` - -To browse by topic, use events, series, and tags. Resolve a tag slug or ID first, then filter: - -```bash -mm predict tags list --limit 50 --json -mm predict events list --tag-slug sports --active --limit 10 --json -mm predict events get --json -mm predict series list --recurrence weekly --limit 10 --json -``` - -These browse-only commands do not return outcome token IDs. Drill into a specific market with `mm predict markets get ` before quoting or placing. - -## Quote, Then Place - -Preview the order cost and fill before placing: - -```bash -mm predict quote \ - --token-id \ - --side buy --size 100 --limit-price 0.55 -``` - -After the user confirms token ID, outcome, side, size, price, and order type: - -```bash -mm predict place \ - --token-id \ - --side buy --size 100 --price 0.55 \ - --order-type GTC -``` - -`--order-type` is one of `GTC`, `GTD`, `FOK`, or `FAK`. `--post-only` only applies to GTC/GTD. `--expiration` is unix seconds for GTD. - -## Manage Orders and Positions - -```bash -mm predict orders -mm predict orders --market -mm predict positions -mm predict positions --market -mm predict cancel --order-id -mm predict cancel --market -mm predict cancel --asset -mm predict cancel --all -``` - -`predict cancel --all` cancels every open order. Require explicit confirmation. - -## Portfolio and Redeeming Winnings - -Get a single snapshot of balance, open positions, and redeemable winnings: - -```bash -mm predict portfolio --json -``` - -After a market resolves, list and claim winning positions: - -```bash -mm predict redeem list --json -mm predict redeem --wait -mm predict redeem --all --wait -``` - -`predict redeem --all` redeems every winning position. Confirm the target (condition ID or `--all`) with the user before executing. With `--wait`, the CLI polls for the redemption transaction receipt. - -## Watch Async Jobs - -```bash -mm predict watch --id --wait -``` - -Use this for setup, approve, deposit, withdraw, redeem, and order jobs that have not reached a terminal state. - -## Safety Notes - -- Prices are 0-1 floats. Treat `--price 1` as suspicious unless the user explicitly confirms. -- Trades are signed by the deposit wallet address shown by `mm predict balance`, not necessarily the connected owner EOA. -- Always inspect the market to map the user's intended outcome to the correct token ID. diff --git a/skills/metamask-agent-wallet/workflows/swap.md b/skills/metamask-agent-wallet/workflows/swap.md index 7eb1bba..dad35c4 100644 --- a/skills/metamask-agent-wallet/workflows/swap.md +++ b/skills/metamask-agent-wallet/workflows/swap.md @@ -1,4 +1,4 @@ -# Swap Workflow +# Swap workflow Use this workflow when the user wants to swap tokens on the same chain. @@ -10,7 +10,7 @@ Reference command syntax in `references/swap.md`. 2. Confirm with the user. 3. Execute and track status. -Do not skip the quote review step. It is where the user sees output amount, fees, route, and slippage. +Don't skip the quote review step. The user needs to see output amount, fees, route, and slippage before executing. ## Quote @@ -20,6 +20,8 @@ mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 Required flags: `--from`, `--to`, `--amount`, and `--from-chain`. +`--to-address` isn't supported for same-chain swaps. Output always goes to the signer's wallet. + Persist the quote id for execution. Show the quote to the user before execution. Confirm source token, destination token, amount, chain, slippage, expected output, fees, and route. @@ -37,7 +39,7 @@ Prefer executing by quote ID. Re-quote-and-execute flags exist, but quote ID exe mm swap status --quote-id "$QUOTE_ID" ``` -## Edge Cases +## Edge cases - Quote expired: re-quote and ask the user to review the new quote. - Insufficient balance: surface the error verbatim. diff --git a/skills/metamask-agent-wallet/workflows/troubleshooting.md b/skills/metamask-agent-wallet/workflows/troubleshooting.md index c709871..b0f09b7 100644 --- a/skills/metamask-agent-wallet/workflows/troubleshooting.md +++ b/skills/metamask-agent-wallet/workflows/troubleshooting.md @@ -8,7 +8,6 @@ Run or suggest these in order: ```bash mm --version -mm config get env mm auth status mm --help ``` @@ -21,7 +20,7 @@ If `auth status` reports anything other than authenticated, fix authentication b | --- | --- | --- | | `mm: command not found` | Binary not installed or not on `PATH` | Check install and PATH | | Async command returns a polling id and appears stuck | Request was dispatched without `--wait` | Use `mm wallet requests list` or `mm wallet requests watch --polling-id ` | -| Auth errors after previously working | Expired token or wrong environment | Check `mm config get env`, `mm auth status`, and the env-scoped session file under `~/.metamask/` | +| Auth errors after previously working | Expired token | Check `mm auth status` and session file under `~/.metamask/` | | `CHAIN_ID_MISMATCH` on typed data | Payload `domain.chainId` differs from `--chain-id` | Align the two chain IDs | | `MNEMONIC_LOCKED` or `WRONG_PASSWORD` | BYOK mnemonic is encrypted and password was wrong or missing | Set the correct `MM_PASSWORD` environment variable and re-run | | `ALREADY_ENCRYPTED` on `wallet password set` | Mnemonic already has a password | Use `mm wallet password change` instead | @@ -43,4 +42,4 @@ For raw error-code meanings, load `../references/errors.md`. Relay CLI errors ve ## Reset Last -Use `mm reset` only after checking version, auth status, current environment, and the failing command's help output. Reset clears local session state and should not be the first troubleshooting step. Always ask the user for explicit confirmation before running reset. +Use `mm reset` only after checking version, auth status, and the failing command's help output. Reset clears local session state and should not be the first troubleshooting step. Always ask the user for explicit confirmation before running reset. diff --git a/skills/metamask-agent-workflows/SKILL.md b/skills/metamask-agent-workflows/SKILL.md index 76f791f..0f40f25 100644 --- a/skills/metamask-agent-workflows/SKILL.md +++ b/skills/metamask-agent-workflows/SKILL.md @@ -24,7 +24,12 @@ Repeatable multi-step patterns for the `mm` CLI. Load a workflow file when the u | Open a perpetual position flow | [perps-open-position.md](workflows/perps-open-position.md) | | Close a perpetual position flow | [perps-close-position.md](workflows/perps-close-position.md) | | Modify a perpetual position flow | [perps-modify-position.md](workflows/perps-modify-position.md) | -| Predict setup-fund-quote-place flow | [predict-trading.md](workflows/predict-trading.md) | +| Predict first-time setup and credentials | [predict-setup.md](workflows/predict-setup.md) | +| Deposit or withdraw pUSD from Predict wallet | [predict-funding.md](workflows/predict-funding.md) | +| Search and browse prediction markets | [predict-markets.md](workflows/predict-markets.md) | +| Quote and place a prediction order | [predict-place-order.md](workflows/predict-place-order.md) | +| View or cancel Predict orders and positions | [predict-manage-orders.md](workflows/predict-manage-orders.md) | +| View Predict portfolio and redeem winnings | [predict-portfolio.md](workflows/predict-portfolio.md) | | Token discovery, prices, and market data | [market-data.md](workflows/market-data.md) | Always use `--toon` for command output unless the user explicitly requests a different format. diff --git a/skills/metamask-agent-workflows/workflows/bridge.md b/skills/metamask-agent-workflows/workflows/bridge.md index 3172d2d..a21133c 100644 --- a/skills/metamask-agent-workflows/workflows/bridge.md +++ b/skills/metamask-agent-workflows/workflows/bridge.md @@ -1,4 +1,4 @@ -# Bridge Workflow +# Bridge workflow Use this workflow when the user wants to bridge tokens across chains. @@ -10,7 +10,7 @@ Reference command syntax in `references/swap.md`. The CLI uses the same `swap` c 2. Confirm with the user. 3. Execute and track status. -Do not skip the quote review step. It is where the user sees output amount, fees, route, and slippage. +Don't skip the quote review step. The user needs to see output amount, fees, route, and slippage before executing. ## Quote @@ -20,8 +20,14 @@ mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 --to-chain 137 --sl Required flags: `--from`, `--to`, `--amount`, `--from-chain`, and `--to-chain`. +If the user wants the bridged tokens sent to a different wallet on the destination chain, add `--to-address`: + +```bash +mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 --to-chain 137 --to-address 0x742d...f2bD18 +``` + Persist the quote id for execution. Show the quote to the user before execution. -Confirm source token, destination token, amount, source chain, destination chain, slippage, expected output, fees, and route. +Confirm source token, destination token, amount, source chain, destination chain, slippage, expected output, fees, route, and recipient address (if `--to-address` was set). ## Execute @@ -40,7 +46,7 @@ mm swap status --quote-id "QUOTE_ID" --tx-hash 0xabc123 Use status polling for bridges where the destination side can lag behind the source transaction. -## Edge Cases +## Edge cases - Quote expired: re-quote and ask the user to review the new quote. - Insufficient balance: surface the error verbatim. diff --git a/skills/metamask-agent-workflows/workflows/login.md b/skills/metamask-agent-workflows/workflows/login.md index 1ae13ec..fcf689a 100644 --- a/skills/metamask-agent-workflows/workflows/login.md +++ b/skills/metamask-agent-workflows/workflows/login.md @@ -6,10 +6,9 @@ Reference command syntax in `references/auth.md`. ## Flow -1. Confirm the target environment with `mm config get env` (set with `mm config set env` before login if not `prod`). -2. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email. -3. Execute login. -4. Verify with token. +1. Ask the user which login method they want: MetaMask Mobile QR, Google, or Email. +2. Execute login. +3. Verify with token. ## Login diff --git a/skills/metamask-agent-workflows/workflows/onboarding.md b/skills/metamask-agent-workflows/workflows/onboarding.md index f2b3f44..e479be5 100644 --- a/skills/metamask-agent-workflows/workflows/onboarding.md +++ b/skills/metamask-agent-workflows/workflows/onboarding.md @@ -7,11 +7,10 @@ Reference command syntax in `references/auth.md` and `references/wallet.md`. ## Flow 1. Check CLI installation. -2. Configure environment (if not using production). -3. Login. -4. Initialize wallet mode. -5. Verify auth status. -6. Show wallet address. +2. Login. +3. Initialize wallet mode. +4. Verify auth status. +5. Show wallet address. ## Check CLI Installation @@ -23,19 +22,6 @@ If this fails, the CLI is not installed. Guide the user to install it with `npm Then run the version compatibility check from the skill `Preflight` section: compare the installed `major.minor` against the pinned `cliVersion` and the latest published release, and warn the user if they are out of sync. -## Configure Environment - -Production (`prod`) is the default. Set the target environment **before** login if the user needs dev or uat: - -```bash -mm config get env -mm config set env dev -``` - -For a one-off override without persisting, use `MM_ENV=dev mm login` (or `uat`). - -To switch environments, run `mm config set env `. - ## Login Flow Ask the user which login method they want to use: MetaMask Mobile QR, Google, or Email. QR (`mm login qr`) is available on non-production builds (dev/uat); on production it returns `COMING_SOON`, so fall back to Google or email there. diff --git a/skills/metamask-agent-workflows/workflows/perps-open-position.md b/skills/metamask-agent-workflows/workflows/perps-open-position.md index a315631..d470331 100644 --- a/skills/metamask-agent-workflows/workflows/perps-open-position.md +++ b/skills/metamask-agent-workflows/workflows/perps-open-position.md @@ -1,4 +1,4 @@ -# Perps Open Position Workflow +# Perps open position workflow Use this workflow when the user wants to open a new perpetual position. @@ -11,17 +11,17 @@ Reference command syntax in `references/perps.md`. 3. Dry run. 4. Confirm with the user and open. -## Confirm Symbol +## Confirm symbol -If the user does not mention a token symbol, list available markets and confirm with the user: +If the user doesn't mention a token symbol, list available markets and confirm with the user: ```bash mm perps markets ``` -## Check Balance +## Check balance -`--venue` defaults to `hyperliquid`. It can be omitted. +`--venue` defaults to `hyperliquid`. You can omit it. ```bash mm perps balance @@ -29,11 +29,45 @@ mm perps balance If available margin is zero or insufficient, deposit USDC before proceeding. Hyperliquid only supports deposits from Arbitrum mainnet (`eip155:42161`). +Check the user's Arbitrum balance for USDC and ETH (for gas). + +```bash +mm wallet balance --chain 42161 +``` + +### No ETH and no USDC on Arbitrum + +Inform the user that ETH on Arbitrum is required for gas. Without ETH, no on-chain transaction is possible. Bridge from another chain. + +```bash +mm swap quote --from --to ETH --amount 0.001 --from-chain --to-chain 42161 +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +Once the user has ETH for gas, swap or bridge to get USDC on Arbitrum. + +```bash +mm swap quote --from --to USDC --amount --from-chain --to-chain 42161 +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +### Has ETH or another token on Arbitrum (but no USDC) + +Swap to USDC on Arbitrum. + +```bash +mm swap quote --from --to USDC --amount --from-chain 42161 +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +### Has USDC on Arbitrum + +Deposit USDC directly into Hyperliquid. + ```bash -mm perps deposit --amount --asset USDC +mm perps deposit --amount --asset USDC ``` -To confirm a deposit, wait briefly and poll `mm perps balance`. ## Quote @@ -45,7 +79,7 @@ mm perps quote --symbol BTC --side long --size 0.01 --leverage 5 Show the user estimated entry, notional, fees, liquidation price, side, size, leverage, and venue before proceeding. -## Dry Run +## Dry run Preview the order before signing: @@ -65,4 +99,4 @@ Remove `--dry-run` only after explicit user confirmation: mm perps open --symbol BTC --side long --size 0.01 --leverage 5 ``` -Do not add `--yes` unless the user explicitly asked for unattended execution. +Don't add `--yes` unless the user explicitly asked for unattended execution. diff --git a/skills/metamask-agent-workflows/workflows/predict-funding.md b/skills/metamask-agent-workflows/workflows/predict-funding.md new file mode 100644 index 0000000..37991f5 --- /dev/null +++ b/skills/metamask-agent-workflows/workflows/predict-funding.md @@ -0,0 +1,90 @@ +# Predict funding workflow + +Use this workflow to deposit or withdraw pUSD from the Predict deposit wallet. + +Reference command syntax in `references/predict.md`. + +## Flow + +1. Check deposit wallet balance. +2. Deposit or withdraw. + +## Check deposit wallet balance + +```bash +mm predict balance --sync +``` + +## Deposit + +If the user doesn't specify an amount, ask how much they want to deposit. Get the deposit wallet address from `mm predict status`, then check the user's Polygon balance. + +```bash +mm wallet balance --chain 137 +``` + +### Has POL and pUSD on Polygon + +Use `mm transfer` to send pUSD directly to the deposit wallet address. No conversion needed. Get the pUSD contract address from `mm wallet balance --chain 137` output. + +```bash +mm transfer --to --amount --chain-id 137 --token --wait +``` + +Get the deposit wallet address from the `mm predict status` output. + +### Has POL and USDC.e on Polygon + +Run `mm predict deposit`. The CLI converts USDC.e to pUSD in the deposit wallet. + +```bash +mm predict deposit --amount --wait +``` + +`--amount` is in USDC.e. The owner EOA needs enough USDC.e and POL for gas on Polygon. + +### Has POL or another token on Polygon (but no USDC.e or pUSD) + +Swap to pUSD on Polygon, then transfer directly to the deposit wallet. The owner EOA needs POL for gas. + +```bash +mm swap quote --from --to pUSD --amount --from-chain 137 +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +After the swap completes, check the balance to verify pUSD arrived: + +```bash +mm wallet balance --chain 137 +``` + +Get the pUSD contract address from the balance output, then transfer to the deposit wallet: + +```bash +mm transfer --to --amount --chain-id 137 --token --wait +``` + +Get the deposit wallet address from the `mm predict status` output. + +### Has assets on another chain + +Bridge to send pUSD directly to the deposit wallet address on Polygon. + +```bash +mm swap quote --from --to pUSD --amount --from-chain --to-chain 137 --to-address +mm swap execute --quote-id "$QUOTE_ID" # quote ID from the swap quote command +``` + +Get the deposit wallet address from the `mm predict status` output. This avoids the extra deposit step. + + +## Withdraw + +Withdraw pUSD from the deposit wallet to the owner EOA (default) or a specified address. + +```bash +mm predict withdraw --amount --wait +mm predict withdraw --amount --to --wait +``` + +Confirm the amount and recipient with the user before executing. The CLI validates the amount against the on-chain deposit wallet balance before signing. diff --git a/skills/metamask-agent-workflows/workflows/predict-manage-orders.md b/skills/metamask-agent-workflows/workflows/predict-manage-orders.md new file mode 100644 index 0000000..5fd10d7 --- /dev/null +++ b/skills/metamask-agent-workflows/workflows/predict-manage-orders.md @@ -0,0 +1,50 @@ +# Predict manage orders workflow + +Use this workflow to view, cancel, or manage open Predict orders and positions. + +Reference command syntax in `references/predict.md`. + +## View orders + +```bash +mm predict orders +mm predict orders --market +``` + +## View positions + +```bash +mm predict positions +mm predict positions --market +``` + +## Cancel orders + +Cancel a single order: + +```bash +mm predict cancel --order-id +``` + +Cancel by market or asset: + +```bash +mm predict cancel --market +mm predict cancel --asset +``` + +Cancel all open orders: + +```bash +mm predict cancel --all +``` + +`predict cancel --all` cancels every open order. Require explicit confirmation from the user before executing. + +## Watch async jobs + +```bash +mm predict watch --id --wait +``` + +Use this for setup, approve, deposit, withdraw, redeem, and order jobs that haven't reached a terminal state. diff --git a/skills/metamask-agent-workflows/workflows/predict-markets.md b/skills/metamask-agent-workflows/workflows/predict-markets.md new file mode 100644 index 0000000..64d37e0 --- /dev/null +++ b/skills/metamask-agent-workflows/workflows/predict-markets.md @@ -0,0 +1,45 @@ +# Predict markets workflow + +Use this workflow to search, browse, and inspect prediction markets on Polymarket. + +Reference command syntax in `references/predict.md`. + +## Flow + +1. Search or browse markets. +2. Inspect the selected market to get outcome token IDs. + +## Search markets + +```bash +mm predict markets search "Knicks NBA Finals" --limit 5 --toon +``` + +Search can return loosely related markets, so always inspect the selected market before quoting. + +If search is noisy, list active markets and filter manually: + +```bash +mm predict markets list --active --limit 50 --toon +``` + +## Browse by topic + +Use events, series, and tags to browse by topic. Resolve a tag slug or ID first, then filter: + +```bash +mm predict tags list --limit 50 --toon +mm predict events list --tag-slug sports --active --limit 10 --toon +mm predict events get --toon +mm predict series list --recurrence weekly --limit 10 --toon +``` + +These browse commands don't return outcome token IDs. Drill into a specific market with `mm predict markets get` before quoting or placing. + +## Inspect a market + +```bash +mm predict markets get --toon +``` + +The market detail prints outcome token IDs. Outcome token IDs aren't market IDs. Use the token ID for `quote`, `place`, `book`, and `balance --token-id`. diff --git a/skills/metamask-agent-workflows/workflows/predict-place-order.md b/skills/metamask-agent-workflows/workflows/predict-place-order.md new file mode 100644 index 0000000..c5372a8 --- /dev/null +++ b/skills/metamask-agent-workflows/workflows/predict-place-order.md @@ -0,0 +1,72 @@ +# Predict place order workflow + +Use this workflow to quote and place a prediction market order. + +Reference command syntax in `references/predict.md`. + +## Flow + +1. Check setup and balance. +2. Inspect the market to get the outcome token ID. +3. Quote the order. +4. Confirm with the user and place. + +## Check setup and balance + +Verify that Predict is fully set up and get the deposit wallet address: + +```bash +mm predict status +``` + +Check `setupComplete` is `true`. If not, follow `predict-setup.md` to run first-time setup. + +Then check the deposit wallet balance: + +```bash +mm predict balance --sync +``` + +If the balance is zero or insufficient for the order, follow `predict-funding.md` to deposit funds. Use the deposit wallet address from `mm predict status` when funding. + +## Get outcome token ID + +If the user hasn't already identified the market, follow `predict-markets.md` to find and inspect it. + +```bash +mm predict markets get --toon +``` + +Map the user's intended outcome to the correct token ID from the market detail. + +## Quote + +Preview the order cost and fill before placing: + +```bash +mm predict quote \ + --token-id \ + --side buy --size 100 --limit-price 0.55 +``` + +Show the user the estimated cost and fill. + +## Place + +After the user confirms token ID, outcome, side, size, price, and order type: + +```bash +mm predict place \ + --token-id \ + --side buy --size 100 --price 0.55 \ + --order-type GTC +``` + +`--order-type` is one of `GTC`, `GTD`, `FOK`, or `FAK`. `--post-only` only applies to GTC/GTD. `--expiration` is unix seconds for GTD. + +## Safety notes + +- Placing orders between a market's end date and its final UMA resolution carries major financial risk. Prices during this window don't reflect true odds and arbitrage strategies can fail if UMA resolves unexpectedly. If the order creation time is after the market end date but before UMA resolution, warn the user about potential financial loss and get explicit confirmation before proceeding. +- Prices are 0-1 floats. Treat `--price 1` as suspicious unless the user explicitly confirms. +- Trades are signed by the deposit wallet address from `mm predict status`, not the connected owner EOA. +- Always inspect the market to map the user's intended outcome to the correct token ID. diff --git a/skills/metamask-agent-workflows/workflows/predict-portfolio.md b/skills/metamask-agent-workflows/workflows/predict-portfolio.md new file mode 100644 index 0000000..05357a2 --- /dev/null +++ b/skills/metamask-agent-workflows/workflows/predict-portfolio.md @@ -0,0 +1,35 @@ +# Predict portfolio workflow + +Use this workflow to view the Predict portfolio or redeem winning positions. + +Reference command syntax in `references/predict.md`. + +## View portfolio + +Get a single snapshot of balance, open positions, and redeemable winnings: + +```bash +mm predict portfolio --toon +``` + +## Redeem winnings + +After a market resolves, list and claim winning positions: + +```bash +mm predict redeem list --toon +``` + +Redeem a single position: + +```bash +mm predict redeem --wait +``` + +Redeem all winning positions: + +```bash +mm predict redeem --all --wait +``` + +`predict redeem --all` redeems every winning position. Confirm the target (condition ID or `--all`) with the user before executing. With `--wait`, the CLI polls for the redemption transaction receipt. diff --git a/skills/metamask-agent-workflows/workflows/predict-setup.md b/skills/metamask-agent-workflows/workflows/predict-setup.md new file mode 100644 index 0000000..3aa2985 --- /dev/null +++ b/skills/metamask-agent-workflows/workflows/predict-setup.md @@ -0,0 +1,54 @@ +# Predict setup workflow + +Use this workflow for first-time Predict setup, refreshing credentials, or repairing approvals. + +Reference command syntax in `references/predict.md`. + +## Flow + +1. Choose Predict mode. +2. Run one-time setup. +3. Verify status. + +## Choose mode + +```bash +mm predict mode mainnet +``` + +Replace `mainnet` with `testnet` if the user wants to paper trade. + +## Run setup + +```bash +mm predict setup --wait +``` + +This blocks until credential, deposit-wallet, and approval jobs complete. Without `--wait`, track returned jobs with `mm predict watch --id --wait`. + +The owner EOA needs POL on Polygon for gas to complete the setup transactions. + +Polymarket is geoblocked in some regions. `predict setup` checks the caller's IP first and aborts with `PREDICT_GEOBLOCKED` before any wallet interaction if the region is restricted. To check region status independently: + +```bash +mm predict geoblock +``` + +## Verify status + +Confirm `setupComplete` is `true` and note the deposit wallet address: + +```bash +mm predict status +``` + +## Refresh credentials or approvals + +If credentials or approvals look stale later: + +```bash +mm predict auth --refresh +mm predict approve --wait +``` + +Then verify with `mm predict status`. diff --git a/skills/metamask-agent-workflows/workflows/predict-trading.md b/skills/metamask-agent-workflows/workflows/predict-trading.md deleted file mode 100644 index fd5d5ad..0000000 --- a/skills/metamask-agent-workflows/workflows/predict-trading.md +++ /dev/null @@ -1,162 +0,0 @@ -# Predict Trading Workflow - -Use this workflow when the user wants to set up prediction market trading, fund the deposit wallet, quote/place orders, or manage Predict orders and positions. - -Reference command syntax in `../references/predict.md`. - -## One-Time Setup - -Choose the Predict mode, run setup, and check backend status: - -```bash -mm predict mode mainnet -mm predict setup --wait -mm predict status -``` - -`predict setup --wait` blocks until credential, deposit-wallet, and approval jobs complete. Without `--wait`, watch returned jobs with `mm predict watch`. - -Polymarket is geoblocked in some regions. `mm predict setup` checks the caller's IP first and aborts with `PREDICT_GEOBLOCKED` before any wallet interaction if the region is restricted. To check region status independently, run: - -```bash -mm predict geoblock -``` - -If setup or approvals look stale later: - -```bash -mm predict auth --refresh -mm predict approve --wait -mm predict balance --sync -``` - -`predict setup` and `predict deposit` use `--wait`; do not add `--yes` to those commands. - -## Fund the Deposit Wallet - -Check deposit wallet status: - -```bash -mm predict balance --sync -``` - -Fund pUSD: - -```bash -mm predict deposit --amount 100 --wait --json -``` - -`--amount` is in pUSD. The owner EOA needs enough Polygon USDC and POL for gas to complete the deposit transaction. - -## Withdraw from the Deposit Wallet - -Check balance first: - -```bash -mm predict balance --sync -``` - -Withdraw pUSD to the owner EOA (default) or a specified address: - -```bash -mm predict withdraw --amount 50 --wait -mm predict withdraw --amount 10 --to 0xRecipient... --wait -``` - -The CLI validates the amount against the on-chain deposit wallet balance before signing. Confirm amount and recipient with the user before executing. - -## Find the Right Market - -Search can return loosely related markets, so inspect the selected market before quoting: - -```bash -mm predict markets search "Knicks NBA Finals" --limit 5 --json -mm predict markets get will-the-new-york-knicks-win-the-2026-nba-finals --json -``` - -The market detail prints outcome token IDs. Outcome token IDs are not market IDs; use the token ID for `quote`, `place`, `book`, and `balance --token-id`. - -If search is noisy, list active markets and filter manually: - -```bash -mm predict markets list --active --limit 50 --json -``` - -To browse by topic, use events, series, and tags. Resolve a tag slug or ID first, then filter: - -```bash -mm predict tags list --limit 50 --json -mm predict events list --tag-slug sports --active --limit 10 --json -mm predict events get --json -mm predict series list --recurrence weekly --limit 10 --json -``` - -These browse-only commands do not return outcome token IDs. Drill into a specific market with `mm predict markets get ` before quoting or placing. - -## Quote, Then Place - -Preview the order cost and fill before placing: - -```bash -mm predict quote \ - --token-id \ - --side buy --size 100 --limit-price 0.55 -``` - -After the user confirms token ID, outcome, side, size, price, and order type: - -```bash -mm predict place \ - --token-id \ - --side buy --size 100 --price 0.55 \ - --order-type GTC -``` - -`--order-type` is one of `GTC`, `GTD`, `FOK`, or `FAK`. `--post-only` only applies to GTC/GTD. `--expiration` is unix seconds for GTD. - -## Manage Orders and Positions - -```bash -mm predict orders -mm predict orders --market -mm predict positions -mm predict positions --market -mm predict cancel --order-id -mm predict cancel --market -mm predict cancel --asset -mm predict cancel --all -``` - -`predict cancel --all` cancels every open order. Require explicit confirmation. - -## Portfolio and Redeeming Winnings - -Get a single snapshot of balance, open positions, and redeemable winnings: - -```bash -mm predict portfolio --json -``` - -After a market resolves, list and claim winning positions: - -```bash -mm predict redeem list --json -mm predict redeem --wait -mm predict redeem --all --wait -``` - -`predict redeem --all` redeems every winning position. Confirm the target (condition ID or `--all`) with the user before executing. With `--wait`, the CLI polls for the redemption transaction receipt. - -## Watch Async Jobs - -```bash -mm predict watch --id --wait -``` - -Use this for setup, approve, deposit, withdraw, redeem, and order jobs that have not reached a terminal state. - -## Safety Notes - -- Prices are 0-1 floats. Treat `--price 1` as suspicious unless the user explicitly confirms. -- Trades are signed by the deposit wallet address shown by `mm predict balance`, not necessarily the connected owner EOA. -- Always inspect the market to map the user's intended outcome to the correct token ID. diff --git a/skills/metamask-agent-workflows/workflows/swap.md b/skills/metamask-agent-workflows/workflows/swap.md index 7eb1bba..dad35c4 100644 --- a/skills/metamask-agent-workflows/workflows/swap.md +++ b/skills/metamask-agent-workflows/workflows/swap.md @@ -1,4 +1,4 @@ -# Swap Workflow +# Swap workflow Use this workflow when the user wants to swap tokens on the same chain. @@ -10,7 +10,7 @@ Reference command syntax in `references/swap.md`. 2. Confirm with the user. 3. Execute and track status. -Do not skip the quote review step. It is where the user sees output amount, fees, route, and slippage. +Don't skip the quote review step. The user needs to see output amount, fees, route, and slippage before executing. ## Quote @@ -20,6 +20,8 @@ mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 Required flags: `--from`, `--to`, `--amount`, and `--from-chain`. +`--to-address` isn't supported for same-chain swaps. Output always goes to the signer's wallet. + Persist the quote id for execution. Show the quote to the user before execution. Confirm source token, destination token, amount, chain, slippage, expected output, fees, and route. @@ -37,7 +39,7 @@ Prefer executing by quote ID. Re-quote-and-execute flags exist, but quote ID exe mm swap status --quote-id "$QUOTE_ID" ``` -## Edge Cases +## Edge cases - Quote expired: re-quote and ask the user to review the new quote. - Insufficient balance: surface the error verbatim. diff --git a/skills/metamask-agent-workflows/workflows/troubleshooting.md b/skills/metamask-agent-workflows/workflows/troubleshooting.md index c709871..b0f09b7 100644 --- a/skills/metamask-agent-workflows/workflows/troubleshooting.md +++ b/skills/metamask-agent-workflows/workflows/troubleshooting.md @@ -8,7 +8,6 @@ Run or suggest these in order: ```bash mm --version -mm config get env mm auth status mm --help ``` @@ -21,7 +20,7 @@ If `auth status` reports anything other than authenticated, fix authentication b | --- | --- | --- | | `mm: command not found` | Binary not installed or not on `PATH` | Check install and PATH | | Async command returns a polling id and appears stuck | Request was dispatched without `--wait` | Use `mm wallet requests list` or `mm wallet requests watch --polling-id ` | -| Auth errors after previously working | Expired token or wrong environment | Check `mm config get env`, `mm auth status`, and the env-scoped session file under `~/.metamask/` | +| Auth errors after previously working | Expired token | Check `mm auth status` and session file under `~/.metamask/` | | `CHAIN_ID_MISMATCH` on typed data | Payload `domain.chainId` differs from `--chain-id` | Align the two chain IDs | | `MNEMONIC_LOCKED` or `WRONG_PASSWORD` | BYOK mnemonic is encrypted and password was wrong or missing | Set the correct `MM_PASSWORD` environment variable and re-run | | `ALREADY_ENCRYPTED` on `wallet password set` | Mnemonic already has a password | Use `mm wallet password change` instead | @@ -43,4 +42,4 @@ For raw error-code meanings, load `../references/errors.md`. Relay CLI errors ve ## Reset Last -Use `mm reset` only after checking version, auth status, current environment, and the failing command's help output. Reset clears local session state and should not be the first troubleshooting step. Always ask the user for explicit confirmation before running reset. +Use `mm reset` only after checking version, auth status, and the failing command's help output. Reset clears local session state and should not be the first troubleshooting step. Always ask the user for explicit confirmation before running reset.