---

name: "broadcast-signed-transaction" version: "1.0.0" description: "直接广播已签名的 hex 交易到链上，无需私钥，一步完成广播" tags: ["web3", "evm", "broadcast", "signed-tx", "okx", "defi", "mev"] author: "wangchengming@apache.org" license: "MIT"

Broadcast Signed Transaction Skill

什么是这个 Skill？

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

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

与 broadcast-sign-transfer 的区别：

能力	broadcast-sign-transfer	broadcast-signed-transaction
构造交易	✅ 自动构造	❌ 不需要
签名交易	✅ 需要私钥	❌ 不需要私钥
广播交易	✅	✅
适用场景	从零开始转账	已有签名 hex，直接广播

---

什么时候该用这个 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 <chainIndex> \
              --address <address> \
              --signed-tx <signedTx> \
              [--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_ACCESS_KEY	OKX Web3 API Key
OKX_SECRET_KEY	OKX Secret Key
OKX_PASSPHRASE	OKX Passphrase

⚠️ 必须使用 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']}")

---

错误处理

错误信息	原因	解决方法
缺少 OKX API 凭证	环境变量未配置	配置三个环境变量后重试
address 格式错误	地址不以 0x 开头	检查地址格式
signed_tx 格式错误	hex 不以 0x 开头或为空	检查签名 hex
HTTP 错误 401	API Key 类型错误	确认使用 OKX Web3 API Key
广播失败（code=50001）	签名 hex 无效	检查 signedTx 是否完整，chainIndex 是否匹配
广播失败（code=50002）	address 与签名不匹配	确认 address 是签名交易的发送方
网络请求异常	网络问题	检查网络连接后重试

---

安全注意事项

• ✅ 此 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 广播工具