diff --git a/agent-wallet/guides/check-balances-and-prices.md b/agent-wallet/guides/check-balances-and-prices.md index 20a53f3a424..77a05d64817 100644 --- a/agent-wallet/guides/check-balances-and-prices.md +++ b/agent-wallet/guides/check-balances-and-prices.md @@ -42,7 +42,7 @@ mm wallet balance --token USDC ``` If `--token` with a symbol returns no balance or an error, pass the ERC-20 contract address for that -chain. Run `mm token list search --query --chain-ids ` to look up the address. +chain. Run `mm token list search --chain-ids ` to look up the address. ## Spot prices @@ -58,7 +58,7 @@ Use `mm token assets` to resolve asset identifiers for tokens you care about. ```bash mm token list popular --chain-id ethereum -mm token list search --query uniswap --chain-ids ethereum +mm token list search uniswap --chain-ids ethereum mm token list trending --chain-id base mm token networks ``` diff --git a/agent-wallet/guides/lend-and-borrow-aave.md b/agent-wallet/guides/lend-and-borrow-aave.md index ea6b657c1ba..13ec3a6f173 100644 --- a/agent-wallet/guides/lend-and-borrow-aave.md +++ b/agent-wallet/guides/lend-and-borrow-aave.md @@ -57,7 +57,7 @@ confirms with you, then submits transactions with `mm wallet send-transaction`. | Avalanche | 43114 | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` | | Base | 8453 | `0x794a61358D6845594F94dc1DB02A252b5b4814aD` | -Resolve token contract addresses with `mm token list search --query --chain-ids `. +Resolve token contract addresses with `mm token list search --chain-ids `. ## Common pattern diff --git a/agent-wallet/guides/send-tokens.md b/agent-wallet/guides/send-tokens.md index 9cc61338617..eca8dffc00c 100644 --- a/agent-wallet/guides/send-tokens.md +++ b/agent-wallet/guides/send-tokens.md @@ -43,7 +43,7 @@ Your agent confirms the recipient, amount, token, and chain before executing. - `--to`: recipient hex address (`0x…`). ENS names are not supported. - `--amount`: human-readable amount (for example, `0.5`). - `--token`: `native`, a token symbol, or an ERC-20 contract address. If a symbol fails to - resolve, run `mm token list search --query --chain-ids ` and pass the contract + resolve, run `mm token list search --chain-ids ` and pass the contract address instead. - `--chain-id`: EVM chain ID (for example, `8453` for Base). Run `mm chains list` for options. diff --git a/agent-wallet/reference/commands.md b/agent-wallet/reference/commands.md index e952746085b..5e288b008bd 100644 --- a/agent-wallet/reference/commands.md +++ b/agent-wallet/reference/commands.md @@ -173,9 +173,13 @@ mm wallet list [--chain-namespace ] ### `mm wallet select` ```bash -mm wallet select
[--chain-namespace ] +mm wallet select [
] [--chain-namespace ] ``` +Pass the wallet address as a positional argument, such as `mm wallet select 0x1234…`. +In an interactive terminal, run `mm wallet select` with no address to choose from your wallets. +Headless runs require the address; omitting it returns `MISSING_WALLET_REF`. + ### `mm wallet show` ```bash @@ -215,6 +219,10 @@ mm wallet balance [--currency ] [--chain-ids ] [--token ] [ | `--testnet-chain-ids` | No | Comma-separated testnet chain IDs for onchain RPC balance reads, such as `421614` | | `--token-contracts` | No | Comma-separated ERC-20 contract addresses to read on testnet RPC chains. Use with `--testnet-chain-ids` | +Balances are returned even when the Price API cannot price every asset. +Assets without a price are listed under `unpricedAssetIds` in structured output and shown as +`unpriced` in the terminal, instead of failing the whole command. + ### `mm wallet trading-mode get` Show the current trading mode and active server-wallet address. @@ -241,9 +249,12 @@ Show the policy YAML for the active server wallet. Server-wallet mode only. ```bash -mm wallet policy get [--chain-namespace ] [--address
] +mm wallet policy get ``` +This command always reads the policy of the active server wallet and takes no target flags. +To read another wallet's policy, switch to it with `mm wallet select` first. + ### `mm wallet policy set` Set the policy for the active server wallet. @@ -578,6 +589,9 @@ Supported `--interval` values include `5m`, `15m`, `30m`, `hourly`, and `daily`. The Price API accepts `5m`, `hourly`, and `daily` directly; `15m` and `30m` are downsampled from 5m data client-side. +When the Price API returns an empty or malformed response, the command returns `INVALID_DATA` with a +hint to retry or verify the asset and chain with `mm price spot`. + ## `mm token` | Command | Usage | @@ -586,9 +600,18 @@ The Price API accepts `5m`, `hourly`, and `daily` directly; `15m` and `30m` are | `mm token networks` | List token networks | | `mm token list popular` | `[--chain-id ]` | | `mm token list trending` | `[--chain-id ]` | -| `mm token list search` | `--query [--chain-ids ] [--limit ] [--after ]` | +| `mm token list search` | ` [--chain-ids ] [--limit ] [--after ]` | | `mm token list top-gainer` | `[--chain-id ]` | +`mm token list search` takes the search term as a positional argument: + +```bash +mm token list search USDC --chain-ids 1,137 +``` + +The `--query` flag still works for backward compatibility. +Passing neither returns `MISSING_QUERY`. + `--chain-id` and `--chain-ids` accept a chain ID, a CAIP-2 ID, or a configured chain key. They default to the active wallet's chain, or `eip155:1` when no wallet is selected. On `mm token list search`, `--limit` defaults to 10 and accepts 1–500. diff --git a/agent-wallet/reference/error-codes.md b/agent-wallet/reference/error-codes.md index e6aa2f4d235..dfd253cf919 100644 --- a/agent-wallet/reference/error-codes.md +++ b/agent-wallet/reference/error-codes.md @@ -44,12 +44,14 @@ Run `mm --help` for command-specific validation rules. | `CHAIN_ID_MISMATCH` | Typed-data domain chain ID differs from `--chain-id` | | `INVALID_MNEMONIC` | Bring your own wallet mnemonic is invalid | | `NOT_INITIALIZED` | Project not initialized; run `mm init` | -| `INVALID_LIMIT` | Invalid `--limit` value for `mm tx history` (must be 1–50) | +| `INVALID_LIMIT` | Invalid `--limit` value; `mm tx history` accepts 1–50 and `mm token list search` accepts 1–500 | +| `INVALID_DATA` | The Price API returned an empty or malformed response for `mm price history`; retry, or verify the asset and chain with `mm price spot` | +| `MISSING_QUERY` | No search term passed to `mm token list search`; pass it as a positional argument | | `INVALID_POLICY_YAML` | Policy YAML passed to `mm wallet policy set` is not a valid policy object; use `mm wallet policy get` or `mm wallet policy template` as a starting point | | `INVALID_CONFIG_KEY` | Unknown CLI config key | | `INVALID_NETWORK` | Unsupported or unknown network | | `UNKNOWN_FLAG` | Unrecognized CLI flag | -| `MISSING_WALLET_REF` | Missing wallet address for `mm wallet select` | +| `MISSING_WALLET_REF` | Missing wallet address for `mm wallet select` in a non-interactive run; pass the address as a positional argument | | `INVALID_EVM_ADDRESS` | Malformed EVM address input | | `INVALID_SORT_BY` | Invalid `--sort-by` field | | `INVALID_SORT_DIRECTION` | Invalid `--sort-direction` value; use `asc` or `desc` | @@ -79,22 +81,24 @@ Run `mm --help` for command-specific validation rules. ## Swap errors (`SwapCommandError`) -| Code | Meaning | -| --------------------- | ------------------------------------------------------ | -| `NO_QUOTES` | No swap quotes returned for the request | -| `INVALID_SWAP_PARAMS` | Missing or invalid swap parameters | -| `TOKEN_NOT_FOUND` | Token not found for the selected chain | -| `QUOTE_NOT_FOUND` | Quote ID not found | -| `NO_TRADE_DATA` | Selected quote has no trade transaction | -| `EXECUTE_FAILED` | Swap execution failed | -| `STATUS_UNAVAILABLE` | Swap status unavailable | -| `INSUFFICIENT_FUNDS` | Source token balance insufficient | -| `INSUFFICIENT_GAS` | Native balance cannot cover gas fees | -| `AMOUNT_TOO_LOW` | Swap amount below minimum threshold | -| `SLIPPAGE_TOO_HIGH` | Slippage exceeds acceptable range | -| `QUOTE_RETRY` | Transient bridge quote-stream retry signal (retryable) | -| `FEES_LOOKUP_FAILED` | Wallet fee lookup failed unexpectedly | -| `SWAP_ERROR` | Generic swap error | +| Code | Meaning | +| ---------------------- | ------------------------------------------------------- | +| `NO_QUOTES` | No swap quotes returned for the request | +| `INVALID_SWAP_PARAMS` | Missing or invalid swap parameters | +| `TOKEN_NOT_FOUND` | Token not found for the selected chain | +| `QUOTE_NOT_FOUND` | Quote ID not found | +| `QUOTE_PERSIST_FAILED` | Quote could not be written to `~/.metamask/swap-quotes` | +| `GASLESS_UNSUPPORTED` | Gasless relay unavailable on this chain | +| `NO_TRADE_DATA` | Selected quote has no trade transaction | +| `EXECUTE_FAILED` | Swap execution failed | +| `STATUS_UNAVAILABLE` | Swap status unavailable | +| `INSUFFICIENT_FUNDS` | Source token balance insufficient | +| `INSUFFICIENT_GAS` | Native balance cannot cover gas fees | +| `AMOUNT_TOO_LOW` | Swap amount below minimum threshold | +| `SLIPPAGE_TOO_HIGH` | Slippage exceeds acceptable range | +| `QUOTE_RETRY` | Transient bridge quote-stream retry signal (retryable) | +| `FEES_LOOKUP_FAILED` | Wallet fee lookup failed unexpectedly | +| `SWAP_ERROR` | Generic swap error | ## Perpetuals errors diff --git a/agent-wallet/troubleshooting.md b/agent-wallet/troubleshooting.md index 4fcccc4666d..93ac6602164 100644 --- a/agent-wallet/troubleshooting.md +++ b/agent-wallet/troubleshooting.md @@ -263,6 +263,16 @@ is gas-included. Re-run `mm swap quote` and execute immediately. Quotes expire and are auto-pruned after 24 hours. +### `QUOTE_PERSIST_FAILED` on the first swap quote + +The CLI could not create `~/.metamask/swap-quotes` to store the quote. It retries once, then returns +this code. Create the directory yourself and re-run the quote: + +```bash +mkdir -p ~/.metamask/swap-quotes && chmod 700 ~/.metamask/swap-quotes +mm swap quote --from --to --amount --from-chain-id +``` + ## Earn ### Withdraw reverts on full withdrawal @@ -297,6 +307,43 @@ In server-wallet mode with Guard Mode, this may require 2FA approval. ENS is not supported for `--to`. Use a hex address. +### `UNSUPPORTED_CHAIN` on a chain that `mm chains list` shows + +Transfers on Monad (`143`), HyperEVM (`999`), Sei (`1329`), and MegaETH (`4326`) failed on CLI +versions before 6.1.2, even though the chains appeared in `mm chains list`. Upgrade and retry: + +```bash +npm install -g @metamask/agent-wallet@latest +mm doctor +``` + +If the code persists on an up-to-date CLI, the chain isn't supported for that operation. Confirm with +`mm chains list --json` and check the `features` field for the chain. + +## Balances and prices + +### `mm wallet balance` shows 0 for a funded wallet + +Bring your own wallet balances returned empty on CLI versions before 6.1.3 even when funds were +onchain. Upgrade with `npm install -g @metamask/agent-wallet@latest`, then re-run +`mm wallet balance --chain-ids `. + +### Assets listed as `unpriced` in `mm wallet balance` + +The Price API rejected or had no price for those assets. Balances are still accurate; only the fiat +value is missing. The affected asset IDs appear under `unpricedAssetIds` in `--json` output. This is +not an error and the command exits 0. + +### `INVALID_DATA` on `mm price history` + +The Price API returned an empty or malformed response. Retry, and verify the asset and chain are +supported: + +```bash +mm price spot --asset-ids +mm price networks +``` + ## Server-wallet polling ### Command returned a `pollingId` but no hash