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"
# OR
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                          # 仅生成本钱包地址
./kaswallet.sh uri kaspa:q... 1.5 "payment" # 带金额与备注信息的支付 URI

错误处理

所有错误均返回结构化的 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}

切换网络

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

# 切回 Mainnet
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