1inch

1inch（脚本优先，安装即用）

此技能专为你的架构设计：不要依赖平台注入的工具。

• ✅ 仅使用 skills/1inch/scripts/ 下技能专属的脚本
• ✅ Agent 通过 bash（python3 ...）执行脚本
• ✅ 无需调用 oneinch_* 工具

---

为什么此版本能解决“找不到工具”的问题

旧设计依赖运行时工具注册（oneinch_quote、oneinch_swap 等）。 如果工具注入失败，Agent 就会受阻。

新设计使用确定性的本地脚本：

1. 直接调用 1inch HTTP API
2. 直接调用钱包服务（通过 /.fly/api 使用 OIDC）
3. 输出 JSON 结果

因此，安装后，Agent 始终有可运行的路径。

---

文件

• scripts/_oneinch_lib.py — 共享客户端与钱包/OIDC 辅助工具
• scripts/tokens.py — 搜索/列出代币
• scripts/quote.py — 仅报价
• scripts/check_allowance.py — 检查授权额度
• scripts/approve.py — 广播授权交易
• scripts/swap.py — 执行兑换（可选自动授权）
• scripts/run_swap_flow.py — 一条命令完成全流程（报价 + 可选授权 + 兑换 + 交易后余额验证）

---

环境

必需：

• ONEINCH_API_KEY
• WALLET_SERVICE_URL（存在默认回退值）
• 连接 sc-proxy，以访问 1inch API（必需）

假设：

• 在 Fly Machine 上运行，并通过 /.fly/api Unix 套接字签发 OIDC 令牌。

sc-proxy 要求（关键）

此技能强制通过 sc-proxy 调用 1inch。

• 首先读取 HTTP_PROXY/HTTPS_PROXY 中的代理；若未设置，则回退使用 PROXY_HOST + PROXY_PORT。
• 如果找不到代理环境变量，脚本会立即失败并给出明确错误，而不会静默地直接连接。

---

支持的链

ethereum, arbitrum, base, optimism, polygon, bsc, avalanche, gnosis

---

Agent 执行规则（重要）

当用户请求执行 1inch 操作时，请严格遵循以下模式：

1. 绝不调用 oneinch_* 工具
2. 使用 bash + python3 skills/1inch/scripts/<script>.py ... 运行本地脚本
3. 解析 JSON 输出，并简洁地总结结果
4. 对于写入操作，务必使用钱包余额工具（如可用）进行后置检查，或重新运行基于脚本的检查

标准映射

• “查 token 地址 / 列 token” → tokens.py
• “先报价 / 看能换多少” → quote.py
• “检查授权” → check_allowance.py
• “授权” → approve.py
• “执行兑换” → swap.py

---

命令示例

1）搜索代币

python3 skills/1inch/scripts/tokens.py --chain polygon --search POL --limit 10

2）报价：1 USDC → POL

python3 skills/1inch/scripts/quote.py --chain polygon --from USDC --to POL --amount 1

3）检查授权额度（USDC）

python3 skills/1inch/scripts/check_allowance.py --chain polygon --token USDC

4）授权 USDC（无限额度）

python3 skills/1inch/scripts/approve.py --chain polygon --token USDC

5）兑换：1 USDC → POL（如有需要则自动授权）

python3 skills/1inch/scripts/swap.py --chain polygon --from USDC --to POL --amount 1 --slippage 1.0 --auto-approve

6）一条命令完成全流程（推荐）

python3 skills/1inch/scripts/run_swap_flow.py --chain polygon --from USDC --to POL --amount 1 --slippage 1.0 --auto-approve

需要时调整重试设置：

python3 skills/1inch/scripts/run_swap_flow.py --chain polygon --from USDC --to POL --amount 1 --slippage 1.0 --auto-approve --swap-retries 3 --swap-retry-backoff 2

---

“买 X USDC 的 POL”的默认工作流

首选的确定性流程：

1. run_swap_flow.py --auto-approve
2. 读取 JSON 结果，并报告报价、交易提交结果和验证差值

手动回退流程（如果用户要求逐步操作）：

1. quote.py（确认预期输出）
2. swap.py --auto-approve
3. 使用最新余额进行验证（前后对比）

如果兑换返回钱包策略拒绝：

• 加载 wallet-policy 技能
• 提议通配符基准策略（DENY exportPrivateKey, ALLOW *）
• 用户确认后，重新运行兑换命令

---

错误处理

• Unknown chain → 请用户选择受支持的链
• 1inch API 4xx/5xx → 显示原始错误；run_swap_flow.py 会自动重试临时的 /swap 5xx 错误（默认：采用指数退避，重试 2 次）
• 1inch 返回 Not enough <token> balance → 代币符号可能映射到了不同的代币变体（例如 USDC.e 与 USDC）；使用 tokens.py 获取的明确代币地址重新运行
• Wallet API 4xx/5xx → 显示原始错误，不要捏造交易哈希
• insufficient allowance（未启用自动授权）→ 使用 --auto-approve 重新运行，或运行 approve.py
• policy 拒绝 → 提议更新策略后重试

---

备注

• 金额输入使用人类单位（例如，--amount 1 = 1 USDC），脚本会处理小数换算。
• 代币符号通过所选链上的 1inch /tokens 接口解析。
• 如果某个符号在一条链上有多个变体（例如，USDC / USDC.e），建议明确传入代币合约地址以避免歧义。
• 输入原生代币时，请使用 native / ETH。

---

快速冒烟测试

python3 skills/1inch/scripts/quote.py --chain polygon --from USDC --to POL --amount 1

如果此测试成功，说明该技能已在脚本模式下正常运行。

---

脚本参考（CLI 参数）

此技能提供的是脚本（而非 Python 函数）。使用 bash + python3 skills/1inch/scripts/<name>.py <args> 运行。所有脚本都会将 JSON 输出到 stdout — 使用 json.loads(...) 解析，或直接打印输出。

常用参数

参数	必需	备注
--chain	是	ethereum、arbitrum、base、optimism、polygon、bsc、avalanche、gnosis 之一
--from、--to	是（swap/quote）	代币符号（USDC、POL 等）或合约地址。原生 Gas 代币请使用 native / ETH。
--amount	是（swap/quote）	人类单位（例如，1 = 1 USDC，小数换算由内部处理）
--slippage	可选	百分比（默认 1.0）
--token	是（allowance/approve）	代币符号或地址
--auto-approve	可选标志	仅用于 swap/run_swap_flow — 如果授权额度不足，则自动广播 approve
--swap-retries	可选	仅用于 run_swap_flow — 在 /swap 返回 5xx 时重试（默认 2）
--swap-retry-backoff	可选	仅用于 run_swap_flow — 重试等待秒数（默认 1）

脚本

脚本	用途	必需参数
tokens.py	列出或搜索某条链上的代币	--chain + --search SYM 和／或 --limit N
quote.py	获取报价（不广播）	--chain --from --to --amount
check_allowance.py	检查 1inch 路由器的 ERC-20 授权额度	--chain --token
approve.py	广播 approve 交易（无限额度）	--chain --token
swap.py	执行兑换	--chain --from --to --amount（+ 可选的 --slippage、--auto-approve）
run_swap_flow.py	一条命令完成报价 +（自动授权）+ 兑换 + 交易后余额检查	与 swap.py 相同（+ 可选的重试参数）

推荐流程

对于任何用户提出的“将 X 兑换为 Y”请求，默认使用 run_swap_flow.py --auto-approve。它会端到端处理整个流程，并在广播后读取钱包余额进行验证。

如果用户要求“只报价，不执行”→ 仅使用 quote.py。

输出架构（run_swap_flow.py）

JSON 包含以下顶层键：

• quote — {fromToken, toToken, fromAmount, toAmount, estimatedGas, ...}
• approve — {required, txHash, success}（仅在使用 --auto-approve 时）
• swap — {txHash, success, error?}
• verification — {from_balance_before, from_balance_after, to_balance_before, to_balance_after, delta_in, delta_out}

如果钱包返回策略拒绝，swap.success = false，且 swap.error 会提及 policy。加载 wallet-policy 技能， 提出一个通配符基线，然后重新运行。