stx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

STX Skill

Provides Stacks L2 STX token and contract operations using the Hiro API. Transfer and contract write operations require an unlocked wallet (use

bun run wallet/wallet.ts unlock

first). Balance and status queries work with just an address.

借助Hiro API实现Stacks L2 STX代币与合约操作。转账和合约写入操作需要解锁钱包（请先执行

bun run wallet/wallet.ts unlock

）。余额和状态查询仅需地址即可完成。

Usage

使用方法

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

bun run stx/stx.ts <子命令> [选项]

Subcommands

子命令

get-balance

Get the STX balance for a Stacks address. Returns balance in both micro-STX and STX.

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

Options:

```
--address
```
(optional) — Stacks address to check (uses active wallet if omitted)

Output:

json

{
  "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"
}

查询指定Stacks地址的STX余额，返回微STX和STX两种单位的余额。

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

选项：

```
--address
```
（可选）—— 要查询的Stacks地址（若省略则使用当前激活的钱包）

输出：

json

{
  "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

Transfer STX to a recipient. Requires an unlocked wallet.

1 STX = 1,000,000 micro-STX. Specify

--amount

in micro-STX.

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

Options:

```
--recipient
```
(required) — Stacks address to send to (starts with SP or ST)
```
--amount
```
(required) — Amount in micro-STX (e.g., "2000000" for 2 STX)
```
--memo
```
(optional) — Memo message to include with the transfer
```
--fee
```
(optional) — Fee preset (low|medium|high) or micro-STX amount; auto-estimated if omitted

Output:

json

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

向指定接收方转账STX，需要解锁钱包。

1 STX = 1,000,000 微STX，

--amount

参数需以微STX为单位指定。

bun run stx/stx.ts transfer --recipient <地址> --amount <微STX数量> [--memo <备注文本>] [--fee low|medium|high|<微STX数量>]

选项：

```
--recipient
```
（必填）—— 接收方的Stacks地址（以SP或ST开头）
```
--amount
```
（必填）—— 转账金额（微STX单位，例如“2000000”代表2 STX）
```
--memo
```
（可选）—— 转账附带的备注信息
```
--fee
```
（可选）—— 手续费预设值（low|medium|high）或具体微STX金额；若省略则自动估算

输出：

json

{
  "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

Broadcast a pre-signed Stacks transaction to the network.

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

Options:

```
--signed-tx
```
(required) — The signed transaction as a hex string

Output:

json

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

将预签名的Stacks交易广播至网络。

bun run stx/stx.ts broadcast-transaction --signed-tx <十六进制字符串>

选项：

```
--signed-tx
```
（必填）—— 预签名交易的十六进制字符串

输出：

json

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

call-contract

Call a function on a Stacks smart contract. Signs and broadcasts the transaction. Requires an unlocked wallet.

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>]

Options:

```
--contract-address
```
(required) — Contract deployer's address (e.g., SP2...)
```
--contract-name
```
(required) — Contract name (e.g., my-token)
```
--function-name
```
(required) — Function to call
```
--args
```
(optional) — Function arguments as JSON array (default: "[]"). For typed args:
```
[{"type":"uint","value":100}]
```
```
--post-condition-mode
```
(optional) —
```
deny
```
(default) blocks unexpected transfers;
```
allow
```
permits any
```
--post-conditions
```
(optional) — Post conditions as JSON array. See SKILL.md for format.
```
--fee
```
(optional) — Fee preset or micro-STX; auto-estimated if omitted

Post condition format:

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"}

Output:

json

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

调用Stacks智能合约中的函数，会签名并广播交易，需要解锁钱包。

bun run stx/stx.ts call-contract --contract-address <地址> --contract-name <名称> --function-name <函数名> [--args <JSON数组>] [--post-condition-mode allow|deny] [--post-conditions <JSON数组>] [--fee low|medium|high|<微STX数量>]

选项：

```
--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
```
（可选）—— 手续费预设值或具体微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"}

输出：

json

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

deploy-contract

Deploy a Clarity smart contract to the Stacks blockchain. Requires an unlocked wallet.

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

Options:

```
--contract-name
```
(required) — Unique name for the contract (lowercase, hyphens allowed)
```
--code-body
```
(required) — The complete Clarity source code
```
--fee
```
(optional) — Fee preset or micro-STX; auto-estimated if omitted

Output:

json

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

将Clarity智能合约部署至Stacks区块链，需要解锁钱包。

bun run stx/stx.ts deploy-contract --contract-name <名称> --code-body <Clarity源码> [--fee low|medium|high|<微STX数量>]

选项：

```
--contract-name
```
（必填）—— 合约的唯一名称（小写，允许使用连字符）
```
--code-body
```
（必填）—— 完整的Clarity源码
```
--fee
```
（可选）—— 手续费预设值或具体微STX金额；若省略则自动估算

输出：

json

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

get-transaction-status

Check the status of a Stacks transaction by its txid.

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

Options:

```
--txid
```
(required) — The transaction ID (64 character hex string)

Output:

json

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

通过交易ID（txid）查询Stacks交易的状态。

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

选项：

```
--txid
```
（必填）—— 交易ID（64位十六进制字符串）

输出：

json

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

Notes

注意事项

Balance queries use the public Hiro API (no authentication required unless you set HIRO_API_KEY)
Transfer and contract operations require an unlocked wallet (use
```
bun run wallet/wallet.ts unlock
```
first)
Fees are auto-estimated if
```
--fee
```
is omitted; use presets (low|medium|high) or exact micro-STX amounts
Post condition mode
```
deny
```
(default) prevents unintended asset movements; use
```
allow
```
only when necessary

余额查询使用公开的Hiro API（除非设置HIRO_API_KEY，否则无需认证）
转账和合约操作需要解锁钱包（请先执行
```
bun run wallet/wallet.ts unlock
```
）
若省略
```
--fee
```
参数，会自动估算手续费；可使用预设值（low|medium|high）或精确的微STX金额
默认后置条件模式为
```
deny
```
，可防止非预期的资产转移；仅在必要时使用
```
allow
```
模式