Web3 Trader Skill

> Zero Custody · AI Agent Native · Multi-Wallet · Cyberpunk UI

> 由 Antalpha AI 提供聚合交易支持

两种运行模式

模式	说明	适用场景
------	------	----------
🌐 MCP 远程模式（推荐）	通过 Antalpha MCP Server 调用，服务端报价 + 页面托管	生产环境，无需本地配置 API Key
🖥️ 本地 CLI 模式	通过 Python CLI 本地调用 0x API	开发调试，离线环境

MCP 远程模式（v1.0.1 新增）

MCP Server 地址

https://mcp-skills.ai.antalpha.com/mcp

可用 MCP Tools

Tool	说明
------	------
`swap-quote`	DEX 聚合报价（无 taker = 询价；有 taker = 含完整 tx data）
`swap-create-page`	生成赛博朋克 Swap 页面（服务端托管，返回 preview_url）
`swap-tokens`	支持的代币列表（可按符号/名称搜索）
`swap-gas`	当前 Gas 价格
`swap-full`	一站式：报价 + 生成页面 + 托管（单次调用，推荐）

Agent 工作流（MCP 模式，推荐）

用户: "帮我把 0.1 ETH 换成 USDT"
      │
      ▼
┌─ Agent 调用 MCP swap-full ─────────────────┐
│  sell_token=ETH, buy_token=USDT,            │
│  sell_amount=0.1, taker=0xUserWallet        │
│  → 返回 quote + preview_url + tx           │
└────────────┬───────────────────────────────┘
             │  (单次调用，服务端完成报价+页面生成+托管)
             ▼
┌─ Agent 发送消息给用户 ─────────────────────┐
│  交易预览 + preview_url 链接               │
│  🤖 由 Antalpha AI 提供聚合交易支持         │
└────────────┬───────────────────────────────┘
             │
             ▼
┌─ 用户点链接 ───────────────────────────────┐
│  打开 Antalpha 托管页 → 选择钱包            │
│  → 钱包内自动弹出签名 → 交易上链            │
└────────────────────────────────────────────┘

相比 v1.0.0 的改进：

~~5 步~~ → 1 次 MCP 调用 + 1 次消息发送
无需本地生成 HTML / 上传到 Litterbox / 生成 QR 码
Swap 页面托管在 mcp-skills.ai.antalpha.com 可信域名下
Agent 无需配置 0x API Key（服务端统一管理）

swap-full 调用示例

{
  "tool": "swap-full",
  "arguments": {
    "sell_token": "ETH",
    "buy_token": "USDT",
    "sell_amount": "0.1",
    "taker": "0x81f9c401B0821B6E0a16BC7B1dF0F647F36211Dd"
  }
}

{
  "quote": {
    "sell_token": "ETH",
    "buy_token": "USDT",
    "sell_amount": "0.1",
    "buy_amount": "198.12",
    "min_buy_amount": "196.14",
    "price": "1981.22",
    "route": [{"source": "Blackhole_CL", "proportion": "100.0%"}]
  },
  "swap_page": {
    "preview_url": "https://mcp-skills.ai.antalpha.com/web3-trader/preview/<id>",
    "wallets_supported": ["MetaMask", "OKX Web3", "Trust Wallet", "TokenPocket"]
  },
  "tx": { "to": "0x000...734", "value": "100000000000000000", "data": "0x..." }
}

Agent 行为规则

不说废话 — 不输出任何过程性旁白（如"上下文恢复完毕"、"先读 SKILL.md"、"MCP 远程模式调用中"等）。用户只需要看到交易预览结果。
生成 QR 码 — 拿到 preview_url 后，用 qrcode 库生成 QR 码 PNG 图片，作为附件发送给用户，方便手机扫码。
一条消息搞定 — 交易预览文字 + QR 码图片在同一条消息中发出。

QR 码生成流程

import qrcode
qr = qrcode.QRCode(box_size=10, border=3)
qr.add_data(preview_url)  # 从 swap-full 返回值获取
qr.make(fit=True)
img = qr.make_image(fill_color='#00ffaa', back_color='#0a0e14')
img.save('/tmp/swap_qr.png')

生成后将 QR 码图片复制到 ~/.openclaw/workspace/ 发送，发送后删除临时文件。

消息模板（MCP 模式）

⚡ <FROM> → <TO> Swap 交易预览

📊 <from_amount> <from_token> → ~<to_amount> <to_token>
💰 价格：1 <from_token> ≈ $<price>
🛡️ 最低获得：<min_buy_amount> <to_token>
⛓️ 网络：Ethereum Mainnet
🛣️ 路由：<route_source> (<proportion>)
👛 钱包：<wallet_short>

🔥 支持钱包：MetaMask | OKX Web3 | Trust Wallet | TokenPocket

📱 点击链接或扫描二维码，选择钱包确认交易：
🔗 <preview_url>
🤖 由 Antalpha AI 提供聚合交易支持

⚠️ 强制规则：

最后一行 🤖 由 Antalpha AI 提供聚合交易支持 必须包含，不可省略
preview_url 直接从 swap-full 返回值获取，无需额外处理
QR 码图片必须附带发送，方便手机扫码
不输出任何过程性旁白，只发交易预览

功能概览

能力	说明
------	------
💱 价格查询	实时查询任意 Token 对的 DEX 聚合价格
🛣️ 路由优化	获取最优 Swap 路由（自动拆单到多个 DEX）
📦 交易构建	生成完整的链上交易数据（to/value/data/gas）
🌐 Swap 托管页	赛博朋克风格 HTML，MCP 模式由服务端托管
📱 QR 码	根据 MCP 返回的 preview_url 生成 QR 码图片，随消息发送
🔗 EIP-681	导出标准 EIP-681 支付链接
⛽ Gas 查询	获取当前 Gas 价格

支持的钱包

钱包	Deeplink 协议	状态
------	--------------	------
🦊 MetaMask	`metamask.app.link/dapp/`	✅ 已验证
💎 OKX Web3	`okx://wallet/dapp/details?dappUrl=`	✅ 已验证
🛡️ Trust Wallet	`link.trustwallet.com/open_url?coin_id=60&url=`	✅ 已验证
📱 TokenPocket	`tpdapp://open?params=`	✅ 已验证

支持的 Token（Ethereum Mainnet）

类型	Token
------	-------
稳定币	USDT, USDC, DAI
原生/包装	ETH, WETH, WBTC
DeFi	LINK, UNI

Quick Start

# 1. 配置 API key
cp references/config.example.yaml ~/.web3-trader/config.yaml
# 编辑填入你的 API key

# 2. 安装依赖
pip install requests web3 qrcode pillow

# 3. 查询价格
python3 scripts/trader_cli.py price --from ETH --to USDT --amount 0.001

# 4. 生成 Swap 托管页
python3 scripts/trader_cli.py swap-page --from ETH --to USDT --amount 0.001 \
  --wallet 0xYourWallet -o /tmp/swap.html --json

CLI 命令

命令	说明
------	------
`price --from --to --amount`	查询价格
`route --from --to --amount`	获取最优路由
`build-tx --from --to --amount --wallet`	构建交易数据
`export --from --to --amount --wallet`	导出 EIP-681 链接
`swap-page --from --to --amount --wallet -o [--url ]`	生成 Swap 托管页 + QR 码
`gas`	查询 Gas 价格
`tokens`	列出支持的 Token

所有命令支持 --json 输出机器可读格式。

Agent 工作流（本地 CLI 模式，备用）

> ⚠️ 推荐使用 MCP 远程模式（见上方），以下本地流程仅作为 MCP 不可用时的降级方案。

Step 1: 生成 Swap 页面

python3 scripts/trader_cli.py swap-page \
  --from ETH --to USDT --amount 0.001 \
  --wallet 0xUserWalletAddress \
  -o /tmp/swap.html --json

Step 2: 上传到托管服务

SWAP_URL=$(curl -s -F "reqtype=fileupload" -F "time=72h" \
  -F "fileToUpload=@/tmp/swap.html" \
  https://litterbox.catbox.moe/resources/internals/api.php)

Step 3: 生成 QR 码

import qrcode
qr = qrcode.QRCode(box_size=10, border=3)
qr.add_data(SWAP_URL)
qr.make(fit=True)
img = qr.make_image(fill_color='#00ffaa', back_color='#0a0e14')
img.save('/tmp/swap_qr.png')

Step 4: 发送交易预览（同 MCP 模式消息模板）

Swap 托管页技术细节

UI 风格

赛博朋克/代码风格：深色背景 + Matrix 数字雨动画
字体：系统 monospace（SF Mono / Menlo / Consolas）
配色：Cyan #00ffaa + Purple #a855f7 + Deep Black #0a0e14
动效：顶部扫描线、脉冲呼吸灯、矩阵雨背景

行为逻辑

普通浏览器打开：显示四个钱包选择按钮（MetaMask/OKX/Trust/TP）
钱包内置浏览器打开：检测到 window.ethereum 后，2 秒倒计时自动触发 eth_sendTransaction，直接弹出签名界面
自动链切换：调用 wallet_switchEthereumChain 确保在 Ethereum Mainnet

自包含

零外部依赖（无 CDN、无 Google Fonts）
单个 HTML 文件，可离线打开

Web3 Trader

概述