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，更多链将在后续版本中陆续支持。