swap-execute-fast

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

KyberSwap Fast Execute Skill

KyberSwap快速执行Skill

⚠️ VIGILANT WARNING — EXTREME CAUTION REQUIRED ⚠️

⚠️ 重要警告 — 需极度谨慎操作 ⚠️

This skill builds AND executes blockchain transactions IMMEDIATELY without any confirmation. Once executed, transactions are IRREVERSIBLE and cannot be cancelled.

本Skill会立即构建并执行区块链交易，无任何确认环节。 交易一旦执行就不可逆转，无法取消。

Critical Risks:

核心风险：

NO CONFIRMATION — Transaction broadcasts the instant this skill runs
IRREVERSIBLE — Blockchain transactions cannot be undone
REAL MONEY AT STAKE — Gas fees are charged even if the swap fails
NO QUOTE VERIFICATION — You cannot review the swap rate before execution
NO SECOND CHANCE — Wrong parameters or bad rates will still execute

无确认环节 — Skill运行的瞬间就会广播交易
不可逆转 — 区块链交易无法撤销
涉及真实资产 — 即使兑换失败也会收取Gas费
无报价验证 — 执行前你无法查看兑换汇率
无二次修改机会 — 参数错误或汇率不佳也会照常执行

Before Using This Skill, Ensure:

使用本Skill前，请确认：

You have double-checked all swap parameters (amount, tokens, chain)
You understand this sends a real transaction immediately
You have sufficient gas fees in your wallet
You trust the current market conditions
You have used
```
/swap-build
```
before to understand typical swap outputs

你已反复核对所有兑换参数（金额、代币、链）
你明白该操作会立即发送真实交易
你的钱包中有足够的Gas费
你认可当前的市场行情
你此前使用过
```
/swap-build
```
，了解常规兑换的输出内容

When NOT to Use This Skill:

不应使用本Skill的场景：

High-value transactions (> $1,000 USD equivalent) — Use
```
/swap-build
```
+
```
/swap-execute
```
instead
First time using these skills
When you want to review the quote before executing
When you're unsure about any swap parameter
Volatile market conditions

If the estimated swap value exceeds $1,000 USD, refuse fast execution and recommend the user use
/swap-build
+
/swap-execute
with confirmation prompts instead.

高价值交易（等值1000美元以上） — 请改用
```
/swap-build
```
+
```
/swap-execute
```
流程
首次使用这类Skill
你希望在执行前查看报价
你对任意兑换参数有疑问
市场行情波动剧烈

如果预估兑换价值超过1000美元，请拒绝快速执行，建议用户使用带确认提示的
/swap-build
+
/swap-execute
流程。

Safer Alternatives:

更安全的替代方案：

Use /swap-build
to build (with confirmation), review, then /swap-execute
to execute (with confirmation)
Use /swap-build
for step-by-step quote verification before building

Build and execute a swap transaction in one step using the shell script at

${CLAUDE_PLUGIN_ROOT}/skills/swap-execute-fast/scripts/execute-swap.sh

. The script calls

fast-swap.sh

internally to build the swap, then immediately broadcasts it. No confirmation prompts.

使用**
```
/swap-build
```
构建交易（带确认）、核对信息，再用
```
/swap-execute
```
**执行交易（带确认）
使用**
```
/swap-build
```
**在构建前逐步验证报价

通过

${CLAUDE_PLUGIN_ROOT}/skills/swap-execute-fast/scripts/execute-swap.sh

这个shell脚本，一步完成兑换交易的构建和执行。脚本内部会调用

fast-swap.sh

构建兑换，然后立即广播交易，无确认提示。

Prerequisites

前置条件

Foundry installed:
```
cast
```
must be available in PATH
curl and jq installed: Required for API calls

Wallet configured: See

${CLAUDE_PLUGIN_ROOT}/skills/swap-execute/references/wallet-setup.md

Quick wallet setup:

bash

undefined

已安装Foundry：PATH中必须有
```
cast
```
命令
已安装curl和jq：调用API需要用到

已配置钱包：参考

${CLAUDE_PLUGIN_ROOT}/skills/swap-execute/references/wallet-setup.md

快速钱包设置：

bash

undefined

Import key to keystore

导入密钥到keystore

cast wallet import mykey --interactive

Create password file securely (prompts without echoing to terminal)

安全创建密码文件（输入时终端不会回显内容）

read -s -p "Password: " pw && echo "$pw" > ~/.foundry/.password && chmod 600 ~/.foundry/.password

undefined

read -s -p "Password: " pw && echo "$pw" > ~/.foundry/.password && chmod 600 ~/.foundry/.password

undefined

Input Parsing

输入解析

The user will provide input like:

```
1 ETH to USDC on base from 0xAbc123...
```

100 USDC to ETH on arbitrum from 0xAbc123... slippage 100

0.5 WBTC to DAI on polygon from 0xAbc123... keystore mykey

Extract these fields:

amount — the human-readable amount to swap
tokenIn — the input token symbol
tokenOut — the output token symbol
chain — the chain slug (default:
```
ethereum
```
)
sender — the address that will send the transaction (required)
recipient — the address to receive output tokens (default: same as sender)
slippageTolerance — slippage in basis points (default: 50)
walletMethod —
```
keystore
```
,
```
env
```
,
```
ledger
```
, or
```
trezor
```
(default:
```
keystore
```
)
keystoreName — keystore account name (default:
```
mykey
```
)

If the sender address is not provided, ask the user for it before proceeding. Do not guess or use a placeholder address.

Sender address validation — reject or warn before proceeding:

Must not be the zero address (
```
0x0000000000000000000000000000000000000000
```
) — this is an invalid sender and the transaction will fail. Ask the user for their actual wallet address.
Must not be the native token sentinel (
```
0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
```
) — this is a placeholder for native tokens, not a real account. Ask the user for their actual wallet address.
Warn if it matches a known contract address (e.g., a token address or the router address) — sending from a contract address is unusual and likely a mistake. Ask the user to confirm.

Recipient address warning: When the recipient address differs from the sender, display a prominent warning: "WARNING: Output tokens will be sent to a DIFFERENT address than the sender. Please verify the recipient address carefully before proceeding." Wait for the user to acknowledge before continuing.

用户的输入格式示例如下：

```
1 ETH to USDC on base from 0xAbc123...
```

100 USDC to ETH on arbitrum from 0xAbc123... slippage 100

0.5 WBTC to DAI on polygon from 0xAbc123... keystore mykey

提取以下字段：

amount — 人工可读的兑换金额
tokenIn — 输入代币符号
tokenOut — 输出代币符号
chain — 链标识（默认：
```
ethereum
```
）
sender — 发送交易的地址（必填）
recipient — 接收输出代币的地址（默认：和sender一致）
slippageTolerance — 滑点容忍度，单位为基点（默认：50）
walletMethod — 可选值
```
keystore
```
、
```
env
```
、
```
ledger
```
、
```
trezor
```
（默认：
```
keystore
```
）
keystoreName — keystore账户名称（默认：
```
mykey
```
）

如果未提供sender地址，请先向用户索要再继续操作， 不要猜测或使用占位地址。

sender地址验证 — 继续操作前需拒绝或发出警告：

不能是零地址（
```
0x0000000000000000000000000000000000000000
```
）—— 这是无效的发送方，交易会失败，请向用户索要真实的钱包地址。
不能是原生代币占位地址（
```
0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE
```
）—— 这是原生代币的占位符，不是真实账户，请向用户索要真实的钱包地址。
如果匹配已知合约地址（例如代币地址或路由地址）需发出警告 —— 从合约地址发送交易不符合常规操作，很可能是输入错误，请让用户确认。

recipient地址警告： 当recipient地址和sender不一致时，需显示醒目警告：「警告：输出代币将发送到与发送方不同的地址，请仔细核对接收地址后再继续。」 等待用户确认后再继续操作。

Slippage Defaults

滑点默认值

If the user does not specify slippage, choose based on the token pair:

Pair type	Default	Rationale
Stablecoin ↔ Stablecoin (e.g. USDC→USDT)	5 bps (0.05%)	Minimal price deviation between pegged assets
Common tokens (e.g. ETH→USDC, WBTC→ETH)	50 bps (0.50%)	Standard volatility buffer
All other / unknown pairs	100 bps (1.00%)	Conservative default for long-tail or volatile tokens

Note: The underlying
execute-swap.sh
script defaults to 50 bps if no slippage argument is passed. You must calculate and pass the correct slippage value from this table as argument 7 when calling the script.

Known stablecoins: USDC, USDT, DAI, BUSD, FRAX, LUSD, USDC.e, USDT.e, TUSD Known common tokens: ETH, WETH, WBTC, BTC, BNB, MATIC, POL, AVAX, MNT, S

如果用户未指定滑点，根据代币对类型选择默认值：

代币对类型	默认值	逻辑说明
稳定币 ↔ 稳定币（例如USDC→USDT）	5 bps（0.05%）	挂钩资产之间的价格波动极小
主流代币（例如ETH→USDC、WBTC→ETH）	50 bps（0.50%）	标准波动缓冲
其他/未知代币对	100 bps（1.00%）	长尾或波动代币的保守默认值

注意： 如果未传入滑点参数，底层
execute-swap.sh
脚本默认使用50 bps。你必须根据上表计算并传入正确的滑点值，作为调用脚本的第7个参数。

已知稳定币： USDC、USDT、DAI、BUSD、FRAX、LUSD、USDC.e、USDT.e、TUSD 已知主流代币： ETH、WETH、WBTC、BTC、BNB、MATIC、POL、AVAX、MNT、S

Workflow

工作流

Pre-Step: Verbal Confirmation Required

前置步骤：必须获得口头确认

CRITICAL: Before running any script or making any API call, you MUST confirm with the user:

You are about to execute a swap IMMEDIATELY with no confirmation step. The transaction will be broadcast as soon as the route is found. Proceed? (yes/no)

Wait for the user to explicitly respond with "yes", "proceed", "confirm", or a clear affirmative. If the user says "no", "cancel", "wait", or anything non-affirmative, abort and recommend they use

/swap-build

/swap-execute

instead for a safer flow with quote review.

Do NOT skip this confirmation. Do NOT assume consent. This is the only safety gate before an irreversible transaction.

关键要求：运行任何脚本或调用任何API之前，你必须向用户确认：

你即将立即执行兑换，无后续确认步骤。路由找到后交易就会立刻广播，是否继续？（是/否）

等待用户明确回复「yes」、「proceed」、「confirm」或其他明确的肯定答复。 如果用户回复「no」、「cancel」、「wait」或任何非肯定内容，终止操作，建议用户使用

/swap-build

/swap-execute

的更安全流程，支持报价核对。

不得跳过该确认步骤，不得默认用户同意，这是不可逆交易前唯一的安全闸门。

Step 0: Dust Amount Pre-Check

步骤0：小额 dust 金额预检查

Before running the script, sanity-check the swap amount. If the amount is obviously a dust amount (e.g.,

0.0000000001 ETH

), warn the user and abort — the script will reject dust amounts (< $0.10 USD or gas > swap value) anyway. Catching it early avoids unnecessary API calls.

"This swap amount is extremely small. Gas fees will far exceed the swap value. Use a larger amount."

运行脚本前，先检查兑换金额是否合理。如果金额明显是 dust 小额（例如

0.0000000001 ETH

），向用户发出警告并终止操作 —— 脚本本身也会拒绝低于0.1美元或Gas费高于兑换价值的小额交易，提前检查可以避免不必要的API调用。

「本次兑换金额极小，Gas费会远高于兑换价值，请使用更大的金额。」

Step 0.5: Resolve Token Addresses

步骤0.5：解析代币地址

Before running the script, resolve both token addresses. The script has a built-in registry and Token API fallback, but unregistered tokens (memecoins, new launches, etc.) may not be found by the script. Pre-resolving ensures all tokens work.

For each token (tokenIn and tokenOut):

Check

${CLAUDE_PLUGIN_ROOT}/references/token-registry.md

for the token on the specified chain

If found in registry → pass the symbol to the script (e.g.
```
ETH
```
,
```
USDC
```
). The script resolves it internally (fastest path).
If NOT found in registry → resolve the address using this fallback sequence: a. KyberSwap Token API (preferred) — search whitelisted tokens first:
```
https://token-api.kyberswap.com/api/v1/public/tokens?chainIds={chainId}&symbol={symbol}&isWhitelisted=true
```
via WebFetch. Pick the result whose
```
symbol
```
matches exactly (case-insensitive) with the highest
```
marketCap
```
. If no whitelisted match, retry without
```
isWhitelisted
```
(only trust verified or market-cap tokens). If still nothing, try by name:
```
?chainIds={chainId}&name={symbol}&isWhitelisted=true
```
. b. CoinGecko API (secondary fallback) — search CoinGecko for verified contract addresses if the Token API doesn't have it. c. Ask user (final fallback) — ask the user for the contract address and decimals. Never guess or fabricate addresses.

Pass resolved tokens as

address:decimals

format (e.g.

0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48:6

)

For any non-registry token, check honeypot/FOT before calling the script:

GET https://token-api.kyberswap.com/api/v1/public/tokens/honeypot-fot-info?chainId={chainId}&address={tokenAddress}

Via WebFetch, check both

tokenIn

and

tokenOut

If
```
isHoneypot: true
```
— refuse the swap and warn the user.
If
```
isFOT: true
```
— warn the user about fee-on-transfer tax. Proceed only if acknowledged.

运行脚本前，先解析两个代币的地址。脚本内置了注册表和代币API fallback，但未注册的代币（迷因币、新发行代币等）可能无法被脚本识别，预解析可以确保所有代币都能正常使用。

针对每个代币（tokenIn和tokenOut）：

在

${CLAUDE_PLUGIN_ROOT}/references/token-registry.md

中查询指定链上的对应代币

如果在注册表中找到 → 将符号传入脚本（例如
```
ETH
```
、
```
USDC
```
），脚本会内部解析（最快路径）。
如果在注册表中未找到 → 按以下 fallback 顺序解析地址： a. KyberSwap 代币API（优先）—— 先搜索白名单代币：通过WebFetch调用
```
https://token-api.kyberswap.com/api/v1/public/tokens?chainIds={chainId}&symbol={symbol}&isWhitelisted=true
```
，选择
```
symbol
```
完全匹配（不区分大小写）且
```
marketCap
```
最高的结果。如果没有白名单匹配结果，去掉
```
isWhitelisted
```
参数重试（仅信任已验证或高市值代币）。如果还是没有结果，按名称搜索：
```
?chainIds={chainId}&name={symbol}&isWhitelisted=true
```
。 b. CoinGecko API（次要 fallback）—— 如果代币API没有相关信息，从CoinGecko搜索已验证的合约地址。 c. 询问用户（最终 fallback）—— 向用户索要合约地址和精度，永远不要猜测或编造地址。

将解析后的代币以

address:decimals

格式传入（例如

0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48:6

）

针对任何非注册表代币，调用脚本前先检查是否是蜜罐/转账扣费代币：

GET https://token-api.kyberswap.com/api/v1/public/tokens/honeypot-fot-info?chainId={chainId}&address={tokenAddress}

通过WebFetch检查

tokenIn

和

tokenOut

：

如果
```
isHoneypot: true
```
—— 拒绝兑换并向用户发出警告。
如果
```
isFOT: true
```
—— 警告用户该代币存在转账扣费，用户确认后再继续操作。

Step 1: Run the Script

步骤1：运行脚本

Execute the script:

bash

bash ${CLAUDE_PLUGIN_ROOT}/skills/swap-execute-fast/scripts/execute-swap.sh <amount> <tokenIn> <tokenOut> <chain> <sender> [recipient] [slippage_bps] [wallet_method] [keystore_name]

Arguments (positional):


1
ETH
USDC
ethereum
sender
recipient
50
keystore
mykey

#	Name	Required	Description
1	`amount`	Yes	Human-readable amount (e.g. `1` , `0.5` , `100` )
2	`tokenIn`	Yes	Input token symbol (e.g. `ETH` , `USDC` ) or pre-resolved `address:decimals` (e.g. `0xA0b8...:6` )
3	`tokenOut`	Yes	Output token symbol (e.g. `USDC` , `ETH` ) or pre-resolved `address:decimals`
4	`chain`	Yes	Chain slug (e.g. `ethereum` , `arbitrum` , `base` )
5	`sender`	Yes	Sender wallet address
6	`recipient`	No	Recipient address (default: same as sender)
7	`slippage_bps`	No	Slippage in basis points (default: `50` )
8	`wallet_method`	No	`keystore` , `env` , `ledger` , `trezor` (default: `keystore` )
9	`keystore_name`	No	Keystore account name (default: `mykey` )

Note: Arguments 7-9 use snake_case (shell convention) for the script's positional parameters. When parsing user input, map from the camelCase names above (slippageTolerance → slippage_bps, walletMethod → wallet_method, keystoreName → keystore_name).

Examples:

bash

undefined

执行脚本：

bash

bash ${CLAUDE_PLUGIN_ROOT}/skills/swap-execute-fast/scripts/execute-swap.sh <amount> <tokenIn> <tokenOut> <chain> <sender> [recipient] [slippage_bps] [wallet_method] [keystore_name]

参数（按位置传递）：


1
ETH
USDC
ethereum
sender
recipient
50
keystore
mykey

序号	名称	必填	说明
1	`amount`	是	人工可读的金额（例如 `1` 、 `0.5` 、 `100` ）
2	`tokenIn`	是	输入代币符号（例如 `ETH` 、 `USDC` ）或预解析的 `address:decimals` 格式（例如 `0xA0b8...:6` ）
3	`tokenOut`	是	输出代币符号（例如 `USDC` 、 `ETH` ）或预解析的 `address:decimals` 格式
4	`chain`	是	链标识（例如 `ethereum` 、 `arbitrum` 、 `base` ）
5	`sender`	是	发送方钱包地址
6	`recipient`	否	接收方地址（默认：和sender一致）
7	`slippage_bps`	否	滑点，单位为基点（默认： `50` ）
8	`wallet_method`	否	`keystore` 、 `env` 、 `ledger` 、 `trezor` （默认： `keystore` ）
9	`keystore_name`	否	Keystore账户名称（默认： `mykey` ）

注意： 脚本的位置参数7-9遵循shell命名规范使用蛇形命名。解析用户输入时，需将上文的驼峰命名映射过来：slippageTolerance → slippage_bps、walletMethod → wallet_method、keystoreName → keystore_name。

示例：

bash

undefined

Known tokens (symbol) — script resolves internally

已知代币（符号）—— 脚本内部解析

bash execute-swap.sh 1 ETH USDC ethereum 0xYourAddress

Pre-resolved tokens (address:decimals) — skips script resolution

预解析代币（address:decimals）—— 跳过脚本解析步骤

bash execute-swap.sh 100 0xdefa4e8a7bcba345f687a2f1456f5edd9ce97202:18 ETH ethereum 0xYourAddress

Mix: one symbol, one pre-resolved

混合模式：一个用符号，一个用预解析地址

bash execute-swap.sh 0.5 ETH 0xdefa4e8a7bcba345f687a2f1456f5edd9ce97202:18 ethereum 0xYourAddress "" 100

Specify all options

指定所有选项

bash execute-swap.sh 100 USDC ETH arbitrum 0xYourAddress "" 50 keystore mykey

Different recipient

不同接收方

bash execute-swap.sh 0.5 WBTC DAI polygon 0xSender 0xRecipient 100 env

Using Ledger hardware wallet

使用Ledger硬件钱包

bash execute-swap.sh 1 ETH USDC base 0xYourAddress "" 50 ledger

undefined

bash execute-swap.sh 1 ETH USDC base 0xYourAddress "" 50 ledger

undefined

Step 2: Parse the Output

步骤2：解析输出

On success (

ok: true

json

{
  "ok": true,
  "chain": "base",
  "txHash": "0x1234567890abcdef...",
  "blockNumber": "12345678",
  "gasUsed": "285432",
  "status": "1",
  "explorerUrl": "https://basescan.org/tx/0x1234...",
  "swap": {
    "tokenIn": {"symbol": "ETH", "amount": "1"},
    "tokenOut": {"symbol": "USDC", "amount": "2345.67"},
    "slippageBps": "50"
  },
  "tx": {
    "sender": "0xYourAddress",
    "recipient": "0xYourAddress",
    "router": "0x6131B5fae19EA4f9D964eAc0408E4408b66337b5",
    "value": "1000000000000000000"
  },
  "walletMethod": "keystore"
}

On error (

ok: false

json

{
  "ok": false,
  "error": "Swap failed (pre-flight): Build failed — Route not found. No route available for this pair/amount. No transaction was submitted."
}

执行成功（

ok: true

）：

json

{
  "ok": true,
  "chain": "base",
  "txHash": "0x1234567890abcdef...",
  "blockNumber": "12345678",
  "gasUsed": "285432",
  "status": "1",
  "explorerUrl": "https://basescan.org/tx/0x1234...",
  "swap": {
    "tokenIn": {"symbol": "ETH", "amount": "1"},
    "tokenOut": {"symbol": "USDC", "amount": "2345.67"},
    "slippageBps": "50"
  },
  "tx": {
    "sender": "0xYourAddress",
    "recipient": "0xYourAddress",
    "router": "0x6131B5fae19EA4f9D964eAc0408E4408b66337b5",
    "value": "1000000000000000000"
  },
  "walletMethod": "keystore"
}

执行错误（

ok: false

）：

json

{
  "ok": false,
  "error": "Swap failed (pre-flight): Build failed — Route not found. No route available for this pair/amount. No transaction was submitted."
}

Step 3: Format the Output

步骤3：格式化输出

On success, present:

undefined

执行成功时，展示以下内容：

undefined

Transaction Executed ✅

交易已执行 ✅

{swap.tokenIn.amount} {swap.tokenIn.symbol} → {swap.tokenOut.amount} {swap.tokenOut.symbol} on {chain}

Field	Value
Transaction Hash	`{txHash}`
Block Number	{blockNumber}
Gas Used	{gasUsed}
Status	{status == "1" ? "Success" : "Failed"}
Slippage	{swap.slippageBps/100}%

Explorer: {explorerUrl}

⚠️ This transaction was executed immediately without confirmation. If this was a mistake, you cannot undo it.


**On error**, check the error prefix to determine what happened:

- **`"Swap failed (pre-flight): ..."`** — No transaction was submitted on-chain. No gas was spent. Fix the issue and retry.
- **`"Transaction was broadcast but ..."`** — A real transaction was sent. Gas fees were consumed. Check the block explorer for details.

{swap.tokenIn.amount} {swap.tokenIn.symbol} → {swap.tokenOut.amount} {swap.tokenOut.symbol} 于 {chain}

字段	值
交易哈希	`{txHash}`
区块号	{blockNumber}
Gas消耗	{gasUsed}
状态	{status == "1" ? "成功" : "失败"}
滑点	{swap.slippageBps/100}%

区块浏览器： {explorerUrl}

⚠️ 本次交易未经过确认直接执行，如果操作失误无法撤销。


**执行错误时，根据错误前缀判断问题类型：**

- **`"Swap failed (pre-flight): ..."`** —— 未上链提交交易，未消耗Gas费，修复问题后重试即可。
- **`"Transaction was broadcast but ..."`** —— 已发送真实交易，已消耗Gas费，请在区块浏览器查看详情。

Environment Variables

环境变量

Variable	Description
`PRIVATE_KEY`	Private key (required if `wallet_method=env` )
`KEYSTORE_PASSWORD_FILE`	Override default `~/.foundry/.password`
`RPC_URL_OVERRIDE`	Override chain RPC URL

变量	说明
`PRIVATE_KEY`	私钥（如果 `wallet_method=env` 则必填）
`KEYSTORE_PASSWORD_FILE`	覆盖默认的 `~/.foundry/.password` 路径
`RPC_URL_OVERRIDE`	覆盖链的RPC URL

Supported Chains

支持的链

ethereum, arbitrum, polygon, optimism, base, bsc, avalanche, linea, mantle, sonic, berachain, ronin, unichain, hyperevm, plasma, etherlink, monad, megaeth

Important Notes

重要说明

EXTREMELY DANGEROUS: This skill builds AND executes in one step with NO confirmation
Irreversible: Once sent, transactions cannot be cancelled
Gas fees: Charged even if the swap fails (e.g., slippage exceeded)
Ledger/Trezor: Still requires physical button press on the device
ERC-20 tokens: The script automatically checks allowance and token balance before executing. If insufficient, it aborts with an actionable error.
Balance pre-check: Native token balance is verified against tx.value + estimated gas cost before sending. ERC-20 balance is checked against amountInWei.
Gas buffer: A 20% buffer is applied to the API gas estimate to reduce out-of-gas failures.
Gas price: Current gas price is logged so you can see what you're paying.
For safer execution, use
```
/swap-build
```
then
```
/swap-execute
```
(both have confirmation steps)

极度危险：本Skill一步完成构建和执行，无任何确认环节
不可逆转：交易一旦发送无法取消
Gas费规则：即使兑换失败（例如滑点超出容忍范围）也会收取Gas费
Ledger/Trezor使用说明：仍需要在设备上按物理按钮确认
ERC-20代币支持：脚本执行前会自动检查授权和代币余额，不足时会终止并返回可操作的错误提示
余额预检查：发送交易前会验证原生代币余额是否足够覆盖交易金额+预估Gas费，ERC-20余额会和兑换金额比对
Gas缓冲：API预估的Gas值会增加20%的缓冲，降低Gas不足导致的失败
Gas价格：会记录当前Gas价格，你可以看到实际支付的费用
如需更安全的执行流程，请使用
```
/swap-build
```
+
```
/swap-execute
```
（两个步骤都有确认环节）

Common Errors

常见错误

Pre-Flight Errors (no transaction sent, no gas spent)

预检查错误（未发送交易，未消耗Gas）

These errors appear with the prefix

"Swap failed (pre-flight): ..."

in the script output.

Error	Cause	Quick Fix
Route not found (4008)	No liquidity for this pair/amount	Try a smaller amount, remove source filters, or try a different chain.
Token not found (4011)	Wrong token address or unsupported token	Verify the token symbol and chain are correct.
Gas estimation failed — return amount not enough (4227)	Price moved between route fetch and build	Retry — the script will fetch a fresh route. Increase slippage if it keeps failing.
Gas estimation failed — insufficient funds (4227)	Sender doesn't have enough native token for value + gas	Top up the wallet or reduce swap amount.
Gas estimation failed — TRANSFER_FROM_FAILED (4227)	Missing token approval or insufficient token balance	Approve the router to spend the input token first. Check balance.
Quoted amount smaller than estimated (4222)	RFQ quote came in lower than expected	Retry. The script will fetch a fresh route.
Insufficient allowance	ERC-20 approval too low	The script detects this and aborts. Approve the router address for at least `amountIn` .
Insufficient token balance	Sender doesn't hold enough of the input token	The script detects this and aborts. Check balance.
Dust amount detected	Swap value < $0.10 USD	Use a larger amount. Gas fees dwarf the swap value.
Uneconomical swap	Gas cost > swap value	Use a larger amount to make the trade worthwhile.

这类错误在脚本输出中带有

"Swap failed (pre-flight): ..."

前缀

错误	原因	快速修复方案
Route not found (4008)	该代币对/金额没有流动性	尝试减少金额、移除来源过滤，或换其他链。
Token not found (4011)	代币地址错误或不支持该代币	核对代币符号和链是否正确。
Gas estimation failed — return amount not enough (4227)	获取路由和构建交易之间价格发生变动	重试即可，脚本会获取最新路由。如果持续失败请调高滑点。
Gas estimation failed — insufficient funds (4227)	发送方原生代币余额不足以支付交易金额+Gas费	给钱包充值或减少兑换金额。
Gas estimation failed — TRANSFER_FROM_FAILED (4227)	缺少代币授权或代币余额不足	先授权路由地址消耗输入代币，核对余额。
Quoted amount smaller than estimated (4222)	RFQ报价低于预期	重试即可，脚本会获取最新路由。
Insufficient allowance	ERC-20授权额度不足	脚本会检测到该问题并终止，请给路由地址授权至少等于兑换金额的额度。
Insufficient token balance	发送方持有的输入代币不足	脚本会检测到该问题并终止，核对余额。
Dust amount detected	兑换价值低于0.1美元	使用更大的金额，Gas费会远高于兑换价值。
Uneconomical swap	Gas成本高于兑换价值	使用更大的金额让交易更划算。

On-Chain Errors (transaction sent, gas spent)

上链错误（已发送交易，已消耗Gas）

These errors appear with the prefix

"Transaction was broadcast but ..."

in the script output.

Error	Cause	Quick Fix
`TRANSFER_FROM_FAILED`	Approval revoked or race condition	Re-approve and retry.
`Return amount is not enough`	Price slipped beyond tolerance during execution	Increase slippage or retry quickly. For MEV protection, use a private RPC.
Out of gas	Gas limit insufficient for the route	The script adds a 20% buffer, but complex routes may need more. Set `RPC_URL_OVERRIDE` to a faster RPC and retry.

这类错误在脚本输出中带有

"Transaction was broadcast but ..."

前缀

错误	原因	快速修复方案
`TRANSFER_FROM_FAILED`	授权被撤销或出现竞态条件	重新授权后重试。
`Return amount is not enough`	执行期间价格波动超出滑点容忍范围	调高滑点或快速重试。如需MEV保护请使用私有RPC。
Out of gas	Gas限制不足以支撑该路由	脚本已添加20%缓冲，但复杂路由可能需要更高额度。设置 `RPC_URL_OVERRIDE` 为更快的RPC后重试。

Troubleshooting

问题排查

For errors not covered above (full API error catalog, PMM/RFQ error details, advanced debugging), refer to ${CLAUDE_PLUGIN_ROOT}/skills/error-handling/SKILL.md
.

Common script-level errors:

Error	Solution
`cast not found`	Install Foundry: `curl -L https://foundry.paradigm.xyz \| bash && foundryup`
`Password file not found`	Create `~/.foundry/.password` with your keystore password
`PRIVATE_KEY not set`	Export `PRIVATE_KEY=0x...` or use keystore method
`Unknown chain`	Set `RPC_URL_OVERRIDE` environment variable

上文未覆盖的错误（完整API错误目录、PMM/RFQ错误详情、高级调试）请参考**

${CLAUDE_PLUGIN_ROOT}/skills/error-handling/SKILL.md

**。

常见脚本层面错误：

错误	解决方案
`cast not found`	安装Foundry： `curl -L https://foundry.paradigm.xyz \| bash && foundryup`
`Password file not found`	创建 `~/.foundry/.password` 文件，写入你的keystore密码
`PRIVATE_KEY not set`	导出 `PRIVATE_KEY=0x...` 或使用keystore模式
`Unknown chain`	设置 `RPC_URL_OVERRIDE` 环境变量