Kaspa Wallet CLI

一个用于Kaspa区块链网络的独立命令行钱包。

安装

bash
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

环境变量

必需（二选一）：
bash
export KASPAPRIVATEKEY=64字符十六进制字符串

或者

export KASPA_MNEMONIC=你的12或24个单词的助记词

可选：
bash
export KASPA_NETWORK=mainnet # mainnet（默认），testnet-10
export KASPARPCURL=wss://... # 自定义RPC端点
export KASPARPCCONNECTTIMEOUTMS=30000 # 连接超时时间（默认：15000）

命令

所有命令输出JSON格式。退出码0=成功，1=错误。

查询余额

bash
./kaswallet.sh balance # 你的钱包余额
./kaswallet.sh balance kaspa:qrc8y... # 任意地址余额

输出：
json
{address: kaspa:q..., balance: 1.5, sompi: 150000000, network: mainnet}

发送KAS

bash
./kaswallet.sh send <地址> <金额> # 发送指定金额
./kaswallet.sh send <地址> max # 发送全部余额
./kaswallet.sh send <地址> <金额> priority # 优先费率等级

输出（成功）：
json
{status: sent, txid: abc123..., from: kaspa:q..., to: kaspa:q..., amount: 0.5, fee: 0.0002}

输出（错误）：
json
{error: 存储质量超过最大值, errorCode: STORAGEMASSEXCEEDED, hint: ..., action: consolidate_utxos}

网络信息

bash
./kaswallet.sh info

输出：
json
{network: mainnet, url: wss://..., blocks: 12345678, synced: true, version: 1.0.0}

费率估算

bash
./kaswallet.sh fees

输出：
json
{network: mainnet, low: {feerate: 1.0, estimatedSeconds: 60}, economic: {...}, priority: {...}}

生成新钱包

bash
./kaswallet.sh generate-mnemonic

输出：
json
{mnemonic: 单词1 单词2 单词3 ... 单词24}

支付URI

bash
./kaswallet.sh uri # 你的地址
./kaswallet.sh uri kaspa:q... 1.5 payment # 带金额和消息

错误处理

所有错误返回包含结构化信息的JSON：

errorCode	含义	解决方法
STORAGEMASSEXCEEDED	当前UTXO的金额太小	先向自己发送max进行合并
NO_UTXOS

无可花费输出 | 等待确认或充值钱包 |
| INSUFFICIENT_FUNDS | 余额不足 | 检查余额，减少金额 |
| RPC_TIMEOUT | 网络缓慢 | 重试或增加超时时间 |
| NOCREDENTIALS | 缺少钱包密钥 | 设置KASPAPRIVATEKEY或KASPAMNEMONIC |
| SDKNOTINSTALLED | 缺少Kaspa SDK | 运行python3 install.py |

常见工作流程

合并UTXO（解决存储质量错误）

当发送失败并显示STORAGEMASSEXCEEDED时：

bash

1. 获取你的地址

./kaswallet.sh balance

返回：{address: kaspa:q你的地址..., ...}

2. 向自己发送最大金额（合并UTXO）

./kaswallet.sh send kaspa:q你的地址... max

3. 现在发送原始金额（将成功）

./kaswallet.sh send kaspa:q接收方地址... 0.5

检查交易状态

发送后，使用txid在区块浏览器上验证：

• - 主网：https://explorer.kaspa.org/txs/{txid}
• 测试网：https://explorer-tn10.kaspa.org/txs/{txid}

切换网络

bash

测试网

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连接

代理示例

bash

检查钱包是否已配置并有资金

./kaswallet.sh balance

解析：如果余额 > 0，钱包已就绪

发送付款并处理错误

./kaswallet.sh send kaspa:接收方地址... 1.0

如果 errorCode == STORAGEMASSEXCEEDED：

运行：./kaswallet.sh send 你的地址 max

然后重试原始发送

验证网络连接

./kaswallet.sh info

检查：发送前 synced == true