From b5d5469602a0a6b29af7ddcee88882472efc1104 Mon Sep 17 00:00:00 2001 From: Sam Walker Date: Mon, 22 Jun 2026 16:08:52 -0400 Subject: [PATCH] docs(swap): document the --refuel flag for cross-chain bridges Add the --refuel flag to the swap command reference (quote + execute), a dedicated Refuel section, the bridge workflows, and the SKILL.md validation and confirmation tables. Key caveats documented: refuel is opt-in and cross-chain only, is best-effort across aggregators, and must not be used when the destination token is the destination chain's native gas asset (the backend returns 0 quotes / NO_QUOTES in that case). --- skills/metamask-agent-wallet/SKILL.md | 3 ++- .../metamask-agent-wallet/references/swap.md | 23 +++++++++++++++++-- .../metamask-agent-wallet/workflows/bridge.md | 9 +++++++- .../workflows/bridge.md | 9 +++++++- 4 files changed, 39 insertions(+), 5 deletions(-) diff --git a/skills/metamask-agent-wallet/SKILL.md b/skills/metamask-agent-wallet/SKILL.md index b4fa409..f8aa0c4 100644 --- a/skills/metamask-agent-wallet/SKILL.md +++ b/skills/metamask-agent-wallet/SKILL.md @@ -217,6 +217,7 @@ Before constructing any command, validate all user-provided values: | `--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 | +| `--refuel` | Boolean flag (no value). Only meaningful for cross-chain swaps (`--to-chain` differs from `--from-chain`); no effect on 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. @@ -229,7 +230,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, quoted output, and recipient address (if `--to-address` is set) before executing | +| Swaps / bridges | Always confirm from/to tokens, amount, source/destination chain, slippage, quoted output, recipient address (if `--to-address` is set), and the destination gas top-up (if `--refuel` is set) before executing | | 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/swap.md b/skills/metamask-agent-wallet/references/swap.md index c9a942e..0520e35 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 ] [--to-address
] [--slippage ] +mm swap quote --from --to --amount --from-chain [--to-chain ] [--to-address
] [--slippage ] [--refuel] ``` ### Supported Flags @@ -23,6 +23,7 @@ mm swap quote --from --to --amount --from-chain [--password ] -mm swap execute --from --to --amount --from-chain [--to-chain ] [--to-address
] [--slippage ] [--password ] +mm swap execute --from --to --amount --from-chain [--to-chain ] [--to-address
] [--slippage ] [--refuel] [--password ] ``` ### Supported Flags @@ -57,6 +59,7 @@ mm swap execute --from --to --amount --from-chain mm swap status --quote-id --tx-hash 0xabc...123 ``` +## Refuel + +Refuel bundles a small amount of the **destination chain's native gas token** into a cross-chain quote, so the recipient lands with gas to spend even if they arrive with a zero native balance. This is useful when bridging to a chain where the recipient holds none of the gas token (e.g. bridging USDC to Arbitrum with no ETH there). + +- **Opt-in only.** Refuel is never enabled automatically — pass `--refuel` to request it. +- **Cross-chain only.** `--refuel` is only meaningful when `--to-chain` differs from `--from-chain`. It has no effect on same-chain swaps. +- **Not for native-asset destinations.** Do not use `--refuel` when the destination token is the destination chain's native gas asset (e.g. bridging ETH from Base into ETH on Arbitrum). There is nothing to top up, and the backend returns **0 quotes** for the route — surfaced as a `NO_QUOTES` error. Only use `--refuel` when bridging into a non-native token (e.g. USDC). +- **Best-effort.** Only some bridge aggregators offer a gas top-up. When `--refuel` is set, the CLI prefers a quote that includes the top-up; if no aggregator offers one for that route, it falls back to the best regular quote (no error). +- **Output.** When a refuel-bearing quote is selected, the quote includes a `refuel` step describing the native-gas top-up (source amount spent and destination native amount received), and the resolved request shows `refuel: true`. + +```bash +# Bridge USDC to Arbitrum and top up ETH for gas on arrival +mm swap quote --from USDC --to USDC --amount 50 --from-chain 1 --to-chain 42161 --refuel +``` + ## Notes - If the chain is not mentioned by the user, ask for the chain. @@ -106,4 +124,5 @@ mm swap status --quote-id --tx-hash 0xabc...123 - You can skip the quote step by passing all swap parameters directly to `mm swap execute`. - Use `mm swap status --quote-id ` to track progress after execution. - If the user asks to "bridge" tokens, use the `swap` commands with different `--from-chain` and `--to-chain` values. +- If the user is bridging to a chain where they hold no native gas token, suggest `--refuel` to top up gas on the destination (cross-chain only). See [Refuel](#refuel). - After execution, track swap progress with `mm swap status --quote-id `. diff --git a/skills/metamask-agent-wallet/workflows/bridge.md b/skills/metamask-agent-wallet/workflows/bridge.md index 868d223..857583f 100644 --- a/skills/metamask-agent-wallet/workflows/bridge.md +++ b/skills/metamask-agent-wallet/workflows/bridge.md @@ -26,8 +26,14 @@ If the user wants the bridged tokens sent to a different wallet on the destinati mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 --to-chain 137 --to-address 0x742d...f2bD18 ``` +If the recipient may have no native gas on the destination chain, add `--refuel` to bundle a destination gas top-up into the quote (cross-chain only, opt-in, best-effort — see `references/swap.md`). Do **not** add `--refuel` when the destination token is the destination chain's native gas asset (e.g. bridging into ETH on Arbitrum) — the backend returns 0 quotes in that case: + +```bash +mm swap quote --from USDC --to USDC --amount 50 --from-chain 1 --to-chain 42161 --refuel +``` + 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, route, and recipient address (if `--to-address` was set). +Confirm source token, destination token, amount, source chain, destination chain, slippage, expected output, fees, route, recipient address (if `--to-address` was set), and the destination gas top-up (if `--refuel` was set). ## Execute @@ -53,3 +59,4 @@ Use status polling for bridges where the destination side can lag behind the sou - Slippage exceeded: only increase `--slippage` if the user explicitly accepts more slippage. Always warn the user if slippage is increased above 1% that it will affect the minimum received. - Missing chain: use `mm chains list` before guessing a chain ID. +- Refuel into a native asset: if `--refuel` is set and the destination token is the destination chain's native gas asset, the backend returns 0 quotes (`NO_QUOTES`). Re-quote without `--refuel`. diff --git a/skills/metamask-agent-workflows/workflows/bridge.md b/skills/metamask-agent-workflows/workflows/bridge.md index 868d223..857583f 100644 --- a/skills/metamask-agent-workflows/workflows/bridge.md +++ b/skills/metamask-agent-workflows/workflows/bridge.md @@ -26,8 +26,14 @@ If the user wants the bridged tokens sent to a different wallet on the destinati mm swap quote --from ETH --to USDC --amount 1 --from-chain 1 --to-chain 137 --to-address 0x742d...f2bD18 ``` +If the recipient may have no native gas on the destination chain, add `--refuel` to bundle a destination gas top-up into the quote (cross-chain only, opt-in, best-effort — see `references/swap.md`). Do **not** add `--refuel` when the destination token is the destination chain's native gas asset (e.g. bridging into ETH on Arbitrum) — the backend returns 0 quotes in that case: + +```bash +mm swap quote --from USDC --to USDC --amount 50 --from-chain 1 --to-chain 42161 --refuel +``` + 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, route, and recipient address (if `--to-address` was set). +Confirm source token, destination token, amount, source chain, destination chain, slippage, expected output, fees, route, recipient address (if `--to-address` was set), and the destination gas top-up (if `--refuel` was set). ## Execute @@ -53,3 +59,4 @@ Use status polling for bridges where the destination side can lag behind the sou - Slippage exceeded: only increase `--slippage` if the user explicitly accepts more slippage. Always warn the user if slippage is increased above 1% that it will affect the minimum received. - Missing chain: use `mm chains list` before guessing a chain ID. +- Refuel into a native asset: if `--refuel` is set and the destination token is the destination chain's native gas asset, the backend returns 0 quotes (`NO_QUOTES`). Re-quote without `--refuel`.