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:**

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:

Switch Networks

```bash

Testnet

export KASPA_NETWORK="testnet-10"

./kaswallet.sh info

Back to mainnet

export KASPA_NETWORK="mainnet"

./kaswallet.sh info

```

Units

All command inputs accept KAS. Outputs include both KAS and sompi where relevant.

Security Notes

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

```