Broadcast Sign Transfer

支持 EVM 多链的原生代币和 ERC20 转账，自动构造交易、本地签名并通过 OKX API 广播上链

Broadcast Sign Transfer Skill

什么是这个 Skill？

这个 Skill 实现了完整的 EVM 链转账流程：

用户输入（私钥/地址/金额）
    ↓
构造交易（自动获取 nonce、gas）
    ↓
本地签名（私钥不离开本机）
    ↓
通过 OKX API 广播到链上
    ↓
返回 tx_hash 和区块浏览器链接

支持两种转账类型：

• 原生代币转账：ETH、BNB、MATIC 等
• ERC20 Token 转账：USDT、USDC 等任意 ERC20

---

什么时候该用这个 Skill？

满足以下条件时使用：

1. 用户想发起一笔链上转账
2. 用户提供了接收方地址和转账金额
3. 私钥已通过环境变量配置好

不适用的情况：

• 用户想做 Swap（代币兑换）→ 使用 Swap Skill
• 用户只想查询余额或交易状态 → 使用查询工具
• 用户没有配置私钥环境变量 → 先引导配置环境变量

---

执行流程（Step by Step）

Step 1: 检查输入参数
        ├── chain_index 是否在支持列表？
        ├── to_address 是否以 0x 开头？
        └── amount 是否大于 0？

Step 2: 获取链上数据
        ├── 获取当前 nonce
        └── 获取当前 gas price（Legacy 或 EIP-1559）

Step 3: 构造交易
        ├── 原生代币：直接构造 tx，gas 固定 21000
        └── ERC20：调用 transfer()，动态估算 gas × 1.2 安全系数

Step 4: 本地签名
        └── 使用私钥对交易签名，私钥不离开本机

Step 5: 广播到链上
        └── 调用 OKX Broadcast API 发送签名交易

Step 6: 返回结果
        ├── 成功 → 返回 tx_hash 和 explorer_url
        └── 失败 → 返回具体错误原因

---

输入参数

chain_index（必填）

• 类型：字符串 string

• 说明：区块链链 ID

• 当前支持：

  chain_index	链名	Gas 类型	支持 MEV
  "56"	BSC	Legacy	✅

• 示例："56"

• 注意：必须是字符串，56 ❌ "56" ✅

---

to_address（必填）

• 类型：字符串 string
• 说明：接收方钱包地址
• 格式：0x 开头，42 位十六进制字符
• 示例："0xaF3e6407073b2793271dA3d45A393397517ee3d9"

---

amount（必填）

• 类型：浮点数 float
• 说明：转账金额，人类可读单位
• 示例：0.01（表示 0.01 BNB），100.0（表示 100 USDT）
• 注意：脚本内部自动转换为链上精度（wei / raw units）

---

token_address（ERC20 转账时必填）

• 类型：字符串 string
• 说明：ERC20 Token 的合约地址
• 格式：0x 开头
• 示例："0x55d398326f99059fF775485246999027B3197955"（BSC 上的 USDT）

---

enable_mev_protection（选填）

• 类型：布尔值 boolean
• 默认值：false
• 说明：是否开启 MEV 保护，防止三明治攻击
• 注意：仅支持 MEV 的链才能开启，否则报错

---

输出结果

成功时

字段	类型	说明
order_id	string	OKX 平台订单 ID
tx_hash	string	链上交易哈希
explorer_url	string	区块浏览器链接

成功输出示例：

✅ BSC 广播成功
Order ID: 1234567890
Tx Hash:  0xabc123...
浏览器:   https://bscscan.com/tx/0xabc123...

失败时

返回具体错误原因，见下方错误处理章节。

---

环境变量（必须配置）

变量名	说明
WALLET_PRIVATE_KEY	钱包私钥（0x 开头）
OKX_ACCESS_KEY	OKX Web3 API Key
OKX_SECRET_KEY	OKX Secret Key
OKX_PASSPHRASE	OKX Passphrase

⚠️ 必须使用 OKX Web3 API Key，普通交易 API Key 会返回 401 错误。

配置方式（写入 ~/.zshrc 永久生效）：

export WALLET_PRIVATE_KEY="0x你的私钥"
export OKX_ACCESS_KEY="你的Key"
export OKX_SECRET_KEY="你的Secret"
export OKX_PASSPHRASE="你的Passphrase"

source ~/.zshrc

---

调用示例

代码调用

from scripts.broadcast_sign_transfer import BroadcastTransaction

bt = BroadcastTransaction(chain_index="56")

# 原生代币转账
result = bt.transfer_native(
    to_address="0xRecipient...",
    amount=0.01,
    enable_mev_protection=False,
)
print(result.summary())

# ERC20 转账
result = bt.transfer_token(
    token_address="0x55d398326f99059fF775485246999027B3197955",  # BSC USDT
    to_address="0xRecipient...",
    amount=100.0,
    enable_mev_protection=False,
)
print(result.summary())

命令行调用

# 原生代币转账
python3 scripts/broadcast_sign_transfer.py --chain 56 native \
  --to 0xRecipient... \
  --amount 0.01

# ERC20 转账
python3 scripts/broadcast_sign_transfer.py --chain 56 token \
  --token 0x55d398326f99059fF775485246999027B3197955 \
  --to 0xRecipient... \
  --amount 100

# 开启 MEV 保护
python3 scripts/broadcast_sign_transfer.py --chain 56 native \
  --to 0xRecipient... \
  --amount 0.01 \
  --mev

---

Gas 处理机制

转账类型	Gas 处理方式
原生代币	固定 21000（EVM 协议层常量）
ERC20 Token	eth_estimateGas 动态估算 × 1.2 安全系数

Gas 价格根据链类型自动切换：

• Legacy（BSC）：使用 gasPrice
• EIP-1559（ETH/Polygon 等）：使用 maxFeePerGas + maxPriorityFeePerGas

---

错误处理

错误信息	原因	解决方法
暂不支持链 {chain_index}	链未在支持列表中	检查 chain_index 是否正确
to_address 格式错误	地址不以 0x 开头	检查地址格式
amount 必须大于 0	金额为负数或 0	输入正确金额
余额不足	ERC20 余额不够	检查钱包余额
链 {chain_index} 不支持 MEV 保护	该链不支持 MEV	关闭 enable_mev_protection
401 Unauthorized	使用了普通 API Key	确认使用 OKX Web3 API Key
广播失败（code=xxx）	OKX API 返回错误	检查 API 凭证和交易数据
缺少 OKX API 凭证	环境变量未配置	配置四个环境变量后重试
缺少钱包私钥	WALLET_PRIVATE_KEY 未配置	配置私钥环境变量

---

安全注意事项

• ⚠️ 私钥通过环境变量传入，不要硬编码在代码里
• ⚠️ 广播成功不代表交易成功，需通过 explorer_url 确认链上状态
• ⚠️ 广播后的交易无法撤销，请在调用前确认地址和金额正确
• ⚠️ ~/.zshrc 是明文存储，确保只有自己能访问该文件

---

依赖安装

pip3 install requests web3

---

文件结构

broadcast-sign-transfer/
├── broadcast_sign_transfer.md     ← 当前文件，AI 技能说明书
└── scripts/
    └── broadcast_sign_transfer.py ← 可执行的 Python 客户端

---

当前支持的链（v1.0.0）

chain_index	链名	Gas 类型	MEV 保护	浏览器
56	BSC	Legacy	✅	bscscan.com

v1.0.0 仅支持 BSC，更多链将在后续版本中陆续支持。