Kaspa Wallet
# Kaspa Wallet CLI
A standalone command-line wallet for the Kaspa blockchain network.
## Installation
```bash
python3 install.py
```
**Requirements:** Python 3.8+ with pip. Works on macOS, Linux, Windows.
**Troubleshooting install:**
- If pip fails: `pip install kaspa` manually, or try `KASPA_PYTHON=python3.12 python3 install.py`
- If venv missing: `sudo apt install python3-venv` (Ubuntu/Debian)
- To reinstall: `rm -rf .venv && python3 install.py`
## Environment Variables
**Required (one of):**
```bash
export KASPA_PRIVATE_KEY="64-character-hex-string"
# OR
export KASPA_MNEMONIC="your twelve or twenty four word seed phrase"
```
**Optional:**
```bash
export KASPA_NETWORK="mainnet" # mainnet (default), testnet-10
export KASPA_RPC_URL="wss://..." # Custom RPC endpoint
export KASPA_RPC_CONNECT_TIMEOUT_MS="30000" # Connection timeout (default: 15000)
```
## Commands
All commands output JSON. Exit code 0 = success, 1 = error.
### Check Balance
```bash
./kaswallet.sh balance # Your wallet balance
./kaswallet.sh balance kaspa:qrc8y... # Any address balance
```
**Output:**
```json
{"address": "kaspa:q...", "balance": "1.5", "sompi": "150000000", "network": "mainnet"}
```
### Send KAS
```bash
./kaswallet.sh send <address> <amount> # Send specific amount
./kaswallet.sh send <address> max # Send entire balance
./kaswallet.sh send <address> <amount> priority # Priority fee tier
```
**Output (success):**
```json
{"status": "sent", "txid": "abc123...", "from": "kaspa:q...", "to": "kaspa:q...", "amount": "0.5", "fee": "0.0002"}
```
**Output (error):**
```json
{"error": "Storage mass exceeds maximum", "errorCode": "STORAGE_MASS_EXCEEDED", "hint": "...", "action": "consolidate_utxos"}
```
### Network Info
```bash
./kaswallet.sh info
```
**Output:**
```json
{"network": "mainnet", "url": "wss://...", "blocks": 12345678, "synced": true, "version": "1.0.0"}
```
### Fee Estimates
```bash
./kaswallet.sh fees
```
**Output:**
```json
{"network": "mainnet", "low": {"feerate": 1.0, "estimatedSeconds": 60}, "economic": {...}, "priority": {...}}
```
### Generate New Wallet
```bash
./kaswallet.sh generate-mnemonic
```
**Output:**
```json
{"mnemonic": "word1 word2 word3 ... word24"}
```
### Payment URI
```bash
./kaswallet.sh uri # Your address
./kaswallet.sh uri kaspa:q... 1.5 "payment" # With amount and message
```
## Error Handling
All errors return JSON with structured information:
| errorCode | Meaning | Resolution |
|-----------|---------|------------|
| `STORAGE_MASS_EXCEEDED` | Amount too small for current UTXOs | Send `max` to yourself first to consolidate |
| `NO_UTXOS` | No spendable outputs | Wait for confirmations or fund wallet |
| `INSUFFICIENT_FUNDS` | Balance too low | Check balance, reduce amount |
| `RPC_TIMEOUT` | Network slow | Retry or increase timeout |
| `NO_CREDENTIALS` | Missing wallet key | Set KASPA_PRIVATE_KEY or KASPA_MNEMONIC |
| `SDK_NOT_INSTALLED` | Kaspa SDK missing | Run `python3 install.py` |
## Common Workflows
### Consolidate UTXOs (Fix Storage Mass Error)
When sending fails with `STORAGE_MASS_EXCEEDED`:
```bash
# 1. Get your address
./kaswallet.sh balance
# Returns: {"address": "kaspa:qYOUR_ADDRESS...", ...}
# 2. Send max to yourself (consolidates UTXOs)
./kaswallet.sh send kaspa:qYOUR_ADDRESS... max
# 3. Now send the original amount (will work)
./kaswallet.sh send kaspa:qRECIPIENT... 0.5
```
### Check Transaction Status
After sending, use the `txid` to verify on a block explorer:
- Mainnet: `https://explorer.kaspa.org/txs/{txid}`
- Testnet: `https://explorer-tn10.kaspa.org/txs/{txid}`
### Switch Networks
```bash
# Testnet
export KASPA_NETWORK="testnet-10"
./kaswallet.sh info
# Back to mainnet
export KASPA_NETWORK="mainnet"
./kaswallet.sh info
```
## Units
- **KAS**: Human-readable unit (e.g., 1.5 KAS)
- **sompi**: Smallest unit, 1 KAS = 100,000,000 sompi
All command inputs accept KAS. Outputs include both KAS and sompi where relevant.
## Security Notes
- Private keys and mnemonics are passed via environment variables only
- Never log or expose these values
- The wallet does not store credentials on disk
- Each command establishes a fresh RPC connection
## Examples for Agents
```bash
# Check if wallet is configured and has funds
./kaswallet.sh balance
# Parse: if balance > 0, wallet is ready
# Send payment with error handling
./kaswallet.sh send kaspa:recipient... 1.0
# If errorCode == "STORAGE_MASS_EXCEEDED":
# Run: ./kaswallet.sh send YOUR_ADDRESS max
# Then retry original send
# Verify network connectivity
./kaswallet.sh info
# Check: synced == true before sending
```
标签
skill
ai
