Broadcast Signed Transaction Skill

什么是这个 Skill？

这个 Skill 将已经签名好的交易 hex 直接广播到链上：

用户输入（signedTx hex + chainIndex + address）
    ↓
参数校验（格式 / OKX 凭证检查）
    ↓
调用 OKX Broadcast API 广播
    ↓
返回 orderId、txHash、区块浏览器链接

与 broadcast-sign-transfer 的区别：

什么时候该用这个 Skill？

满足以下条件时使用：

1. 用户已有签名好的交易 hex（以 0x 开头的十六进制字符串）
2. 用户想直接广播，不需要重新签名
3. 用户说了类似的话：
   • "我有一笔签名好的交易，帮我广播"
   • "直接广播这个 signedTx"
   • "广播已签名交易"
   • "broadcast signed tx"
   • "把这个 hex 广播到链上"

不适用的情况：

• 用户还没签名，需要从私钥开始 → 使用 broadcast-sign-transfer
• 用户只想查询交易状态 → 使用 mev_tx_status_query.py
• 用户没有 OKX API Key → 先引导配置环境变量

执行流程（Step by Step）

Step 1: 收集必要参数
        ├── chainIndex  → 用户指定，或从日志/上下文中提取
        ├── address     → 发送方地址（0x 开头）
        ├── signedTx    → 已签名的 hex（0x 开头）
        └── --mev       → 是否开启 MEV 保护（可选，默认关闭）

Step 2: 验证环境变量
        └── OKX_ACCESS_KEY / OKX_SECRET_KEY / OKX_PASSPHRASE

Step 3: 调用广播脚本
        └── python3 scripts/broadcast_signed_tx.py \
              --chain \x3CchainIndex> \
              --address \x3Caddress> \
              --signed-tx \x3CsignedTx> \
              [--mev] [--json-only]

Step 4: 解析结果
        ├── 成功 → 展示 orderId、txHash、区块浏览器链接
        └── 失败 → 展示具体错误原因并给出解决建议

输入参数

--chain（必填）

• 类型：字符串（链 ID）

• 说明：区块链链 ID，传给 OKX API 的 chainIndex 字段

• 常用值：

  chain	链名	区块浏览器
  1	Ethereum	etherscan.io
  56	BSC	bscscan.com
  8453	Base	basescan.org
  42161	Arbitrum	arbiscan.io
  196	xLayer	oklink.com/xlayer
  501	Solana	solscan.io

• 示例：--chain 56

• 注意：不在列表中的链也可以传，OKX API 会进行校验

--address（必填）

• 类型：字符串
• 说明：发送方钱包地址
• 格式：0x 开头，42 位十六进制字符
• 示例：--address 0xaF3e6407073b2793271dA3d45A393397517ee3d9

--signed-tx（必填）

• 类型：字符串
• 说明：已签名的交易 hex，由客户端签名后得到
• 格式：0x 开头的完整 RLP 编码交易
• 示例：--signed-tx 0x02f8...（完整 hex）
• 获取方式：
  • web3.py：signed = w3.eth.account.sign_transaction(tx, pk) → signed.raw_transaction.to_0x_hex()
  • ethers.js：signer.signTransaction(tx) → 得到 0x...

--mev（选填，flag）

• 默认：关闭
• 说明：开启 MEV 保护，防止三明治攻击
• 示例：--mev

--json-only（选填，flag）

• 说明：仅输出 JSON，适合 AI 解析结果
• 示例：--json-only

输出结果

成功时

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

{
  "success": true,
  "order_id": "1234567890",
  "tx_hash": "0xabc123...",
  "chain_index": "56",
  "chain_name": "BSC",
  "explorer_url": "https://bscscan.com/tx/0xabc123...",
  "mev_enabled": false,
  "error": null
}

失败时

==============================================================
  ❌ 广播失败（Chain-56）
==============================================================
  错误原因  : 广播失败（code=50001）: Invalid signed transaction
==============================================================

环境变量（必须配置）

⚠️ 必须使用 OKX Web3 API Key，普通交易 API Key 会返回 401 错误。 ⚠️ 此 Skill 不需要 WALLET_PRIVATE_KEY（私钥），交易已在外部签名。

配置方式：

export OKX_ACCESS_KEY="你的Key"
export OKX_SECRET_KEY="你的Secret"
export OKX_PASSPHRASE="你的Passphrase"
source ~/.zshrc

调用示例

命令行

# BSC 广播
python3 scripts/broadcast_signed_tx.py \
  --chain 56 \
  --address 0xYourAddress \
  --signed-tx 0xYourSignedTxHex

# ETH 开启 MEV 保护
python3 scripts/broadcast_signed_tx.py \
  --chain 1 \
  --address 0xYourAddress \
  --signed-tx 0xYourSignedTxHex \
  --mev

# 仅输出 JSON（AI 解析）
python3 scripts/broadcast_signed_tx.py \
  --chain 56 \
  --address 0xYourAddress \
  --signed-tx 0xYourSignedTxHex \
  --json-only

Python 代码调用

from scripts.broadcast_signed_tx import broadcast_signed_transaction

result = broadcast_signed_transaction(
    chain_index           = "56",
    address               = "0xYourAddress",
    signed_tx             = "0xYourSignedTxHex",
    enable_mev_protection = False,
)

if result["success"]:
    print(f"✅ 广播成功：{result['tx_hash']}")
    print(f"浏览器：{result['explorer_url']}")
else:
    print(f"❌ 失败：{result['error']}")

错误处理

安全注意事项

• ✅ 此 Skill 无需私钥，不存在私钥泄露风险
• ⚠️ 广播前确认 signedTx 内容正确：广播后无法撤销
• ⚠️ 确认 address 与 signedTx 的发送方地址一致，否则 OKX API 会拒绝
• ⚠️ OKX API 凭证请妥善保管，不要提交到版本控制

依赖安装

# 仅依赖 requests，无需 web3
pip3 install requests

文件结构

broadcast-signed-transaction/
├── SKILL.md                          ← 当前文件，AI 技能说明书
└── scripts/
    └── broadcast_signed_tx.py        ← 可执行的 Python 广播工具