Kaspa 钱包 CLI

一个独立的、面向 Kaspa 区块链网络的命令行钱包。

安装

python3 install.py

要求： Python 3.8+ 及 pip。支持 macOS、Linux 和 Windows。

安装问题排查：

• 若 pip 安装失败：手动执行 pip install kaspa，或尝试 KASPA_PYTHON=python3.12 python3 install.py
• 若缺少 venv：执行 sudo apt install python3-venv（Ubuntu/Debian）
• 如需重新安装：执行 rm -rf .venv && python3 install.py

环境变量

必需（任选其一）：

export KASPA_PRIVATE_KEY="64-character-hex-string"
# 或
export KASPA_MNEMONIC="your twelve or twenty four word seed phrase"

可选：

export KASPA_NETWORK="mainnet"              # mainnet（默认）、testnet-10
export KASPA_RPC_URL="wss://..."            # 自定义 RPC 端点
export KASPA_RPC_CONNECT_TIMEOUT_MS="30000" # 连接超时时间（默认：15000）

命令

所有命令均输出 JSON 格式结果。退出码 0 表示成功，1 表示错误。

查询余额

./kaswallet.sh balance                    # 查询本钱包余额
./kaswallet.sh balance kaspa:qrc8y...     # 查询任意地址余额

输出：

{"address": "kaspa:q...", "balance": "1.5", "sompi": "150000000", "network": "mainnet"}

发送 KAS

./kaswallet.sh send 
            # 发送指定金额
./kaswallet.sh send 
 max                # 发送全部余额
./kaswallet.sh send 
  priority  # 使用优先级手续费档位

成功输出：

{"status": "sent", "txid": "abc123...", "from": "kaspa:q...", "to": "kaspa:q...", "amount": "0.5", "fee": "0.0002"}

错误输出：

{"error": "Storage mass exceeds maximum", "errorCode": "STORAGE_MASS_EXCEEDED", "hint": "...", "action": "consolidate_utxos"}

网络信息

./kaswallet.sh info

输出：

{"network": "mainnet", "url": "wss://...", "blocks": 12345678, "synced": true, "version": "1.0.0"}

手续费估算

./kaswallet.sh fees

输出：

{"network": "mainnet", "low": {"feerate": 1.0, "estimatedSeconds": 60}, "economic": {...}, "priority": {...}}

生成新钱包

./kaswallet.sh generate-mnemonic

输出：

{"mnemonic": "word1 word2 word3 ... word24"}

支付 URI

./kaswallet.sh uri                          # 生成本钱包地址的 URI
./kaswallet.sh uri kaspa:q... 1.5 "payment" # 指定收款地址、金额与备注信息

错误处理

所有错误均以结构化 JSON 形式返回：

常见工作流

合并 UTXO（解决 Storage Mass 错误）

当发送交易失败并提示 STORAGE_MASS_EXCEEDED 时：

# 1. 获取本钱包地址
./kaswallet.sh balance
# 返回：{"address": "kaspa:qYOUR_ADDRESS...", ...}

# 2. 向自身地址发送 max（合并 UTXO）
./kaswallet.sh send kaspa:qYOUR_ADDRESS... max

# 3. 再次发送原始目标金额（此时应可成功）
./kaswallet.sh send kaspa:qRECIPIENT... 0.5

查询交易状态

发送完成后，使用返回的 txid 在区块浏览器中验证：

• Mainnet：https://explorer.kaspa.org/txs/{txid}
• Testnet：https://explorer-tn10.kaspa.org/txs/{txid}

切换网络

# 切换至测试网
export KASPA_NETWORK="testnet-10"
./kaswallet.sh info

# 切回主网
export KASPA_NETWORK="mainnet"
./kaswallet.sh info

单位说明

• KAS：人类可读单位（例如：1.5 KAS）
• sompi：最小单位，1 KAS = 100,000,000 sompi

所有命令输入均接受 KAS 单位；输出中在相关场景下同时包含 KAS 和 sompi 数值。

安全说明

• 私钥与助记词仅通过环境变量传入
• 切勿记录或暴露这些敏感值
• 钱包本身不会将凭据写入磁盘
• 每次命令执行均建立全新的 RPC 连接

面向 Agent 的示例用法

# 检查钱包是否已配置且有可用余额
./kaswallet.sh balance
# 解析输出：若 balance > 0，则钱包已就绪

# 发起支付并处理错误
./kaswallet.sh send kaspa:recipient... 1.0
# 若 errorCode == "STORAGE_MASS_EXCEEDED"：
#   执行：./kaswallet.sh send YOUR_ADDRESS max
#   然后重试原发送命令

# 验证网络连通性
./kaswallet.sh info
# 发送前检查：synced == true