stx

STX 技能

使用 Hiro API 执行 Stacks L2 STX 代币和合约操作。转账和合约写入操作需要已解锁的钱包（请先运行 bun run wallet/wallet.ts unlock）。只需提供地址即可查询余额和状态。

用法

bun run stx/stx.ts <subcommand> [options]

子命令

get-balance

查询 Stacks 地址的 STX 余额。返回以 micro-STX 和 STX 表示的余额。

bun run stx/stx.ts get-balance [--address <addr>]

选项：

• --address（可选）— 要查询的 Stacks 地址（若未提供，则使用当前钱包）

输出：

{
  "address": "SP2...",
  "network": "mainnet",
  "balance": {
    "microStx": "1000000",
    "stx": "1 STX"
  },
  "locked": {
    "microStx": "0",
    "stx": "0 STX"
  },
  "explorerUrl": "https://explorer.hiro.so/address/SP2...?chain=mainnet"
}

transfer

向收款方转账 STX。需要已解锁的钱包。

1 STX = 1,000,000 micro-STX。--amount 的值请使用 micro-STX。

bun run stx/stx.ts transfer --recipient <addr> --amount <microStx> [--memo <text>] [--fee low|medium|high|<microStx>]

选项：

• --recipient（必需）— 转账目标 Stacks 地址（以 SP 或 ST 开头）
• --amount（必需）— 以 micro-STX 表示的金额（例如，"2000000" 表示 2 STX）
• --memo（可选）— 随转账附上的备注消息
• --fee（可选）— 费用预设（low|medium|high）或 micro-STX 金额；若未提供，则自动估算

输出：

{
  "success": true,
  "txid": "abc123...",
  "from": "SP2...",
  "recipient": "SP3...",
  "amount": "2 STX",
  "amountMicroStx": "2000000",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}

broadcast-transaction

将已签名的 Stacks 交易广播到网络。

bun run stx/stx.ts broadcast-transaction --signed-tx <hex>

选项：

• --signed-tx（必需）— 十六进制字符串形式的已签名交易

输出：

{
  "success": true,
  "txid": "abc123...",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}

call-contract

调用 Stacks 智能合约中的函数。此操作会对交易签名并将其广播。需要已解锁的钱包。

bun run stx/stx.ts call-contract --contract-address <addr> --contract-name <name> --function-name <fn> [--args <json>] [--post-condition-mode allow|deny] [--post-conditions <json>] [--fee low|medium|high|<microStx>]

选项：

• --contract-address（必需）— 合约部署者的地址（例如，SP2...）
• --contract-name（必需）— 合约名称（例如，my-token）
• --function-name（必需）— 要调用的函数
• --args（可选）— JSON 数组格式的函数参数（默认值："[]"）。对于带类型的参数：[{"type":"uint","value":100}]
• --post-condition-mode（可选）— deny（默认值）会阻止意外转账；allow 允许任意转账
• --post-conditions（可选）— JSON 数组格式的后置条件。格式请参阅 SKILL.md。
• --fee（可选）— 费用预设或 micro-STX 金额；若未提供，则自动估算

后置条件格式：

• STX：{"type":"stx","principal":"SP...","conditionCode":"eq","amount":"1000000"}
• FT：{"type":"ft","principal":"SP...","asset":"SP...contract","assetName":"token-name","conditionCode":"eq","amount":"1000"}
• NFT：{"type":"nft","principal":"SP...","asset":"SP...contract","assetName":"nft-name","tokenId":"1"}

输出：

{
  "success": true,
  "txid": "abc123...",
  "contract": "SP2....my-token",
  "function": "transfer",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}

deploy-contract

将 Clarity 智能合约部署到 Stacks 区块链。需要已解锁的钱包。

bun run stx/stx.ts deploy-contract --contract-name <name> --code-body <clarity-source> [--fee low|medium|high|<microStx>]

选项：

• --contract-name（必需）— 合约的唯一名称（小写，可使用连字符）
• --code-body（必需）— 完整的 Clarity 源代码
• --fee（可选）— 费用预设或 micro-STX 金额；若未提供，则自动估算

输出：

{
  "success": true,
  "txid": "abc123...",
  "contractId": "SP2....my-contract",
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}

get-transaction-status

根据 txid 查询 Stacks 交易的状态。

bun run stx/stx.ts get-transaction-status --txid <txid>

选项：

• --txid（必需）— 交易 ID（64 个字符的十六进制字符串）

输出：

{
  "txid": "abc123...",
  "status": "success",
  "block_height": 150000,
  "network": "mainnet",
  "explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}

注意事项

• 余额查询使用公开的 Hiro API（除非设置了 HIRO_API_KEY，否则无需身份验证）
• 转账和合约操作需要已解锁的钱包（请先运行 bun run wallet/wallet.ts unlock）
• 若未提供 --fee，将自动估算费用；可使用预设（low|medium|high）或指定确切的 micro-STX 金额
• 后置条件模式 deny（默认值）可防止意外的资产转移；仅在必要时使用 allow