kaspa-wallet

Send and receive KAS cryptocurrency. Check balances, send payments, generate wallets.

Security Scan

The package appears to implement a functional Kaspa CLI wallet, but there are inconsistencies and supply-chain risks you should understand before installing (missing declared env requirements, an unpinned PyPI dependency, and unclear provenance).

Purpose & Capability

The skill's stated purpose (send/receive KAS) matches the included code (install.py, scripts/kaswallet.py, kaswallet.sh). However the registry metadata claims 'Required env vars: none' while the SKILL.md and the code clearly require a wallet secret (KASPA_PRIVATE_KEY or KASPA_MNEMONIC). This mismatch is an incoherence: anyone installing this wallet must supply secrets, yet the skill metadata does not declare them.

Instruction Scope

The runtime instructions in SKILL.md map directly to the included scripts: set credentials via environment variables, run install.py to create a venv and pip-install the 'kaspa' SDK, and invoke kaswallet.sh. The instructions do not ask the agent to read unrelated files or exfiltrate data. They do instruct agents to rely on env vars for keys (expected for a CLI wallet).

Install Mechanism

There is no registry-level install spec, but the bundle includes an install.py that creates a local .venv and runs pip install -r requirements.txt. requirements.txt contains a single unpinned dependency 'kaspa' (no version). Installing from PyPI without a pinned, audited version is a supply-chain risk (package typosquatting or future malicious updates). The installer performs standard venv creation and pip actions (no obscure download URLs), but the unpinned dependency and lack of provenance for the 'kaspa' package raise concern.

Credentials

The wallet legitimately needs a private key or mnemonic (KASPA_PRIVATE_KEY or KASPA_MNEMONIC) and optionally RPC config. That requirement is present in SKILL.md and in the code (scripts/kaswallet.py). However the skill's declared metadata listed no required env vars or primary credential, which is inconsistent and misleading. Requiring a mnemonic/private key is a high-sensitivity need and should be clearly declared. The code claims it does not store credentials to disk (installer and scripts don't write secrets), which aligns with expectations.

Persistence & Privilege

The skill does not request elevated persistence: always:false, no system-wide changes, and installer only creates a .venv inside the skill directory. It does not modify other skills or system agent settings. The skill can be invoked autonomously by the agent (platform default), which increases blast radius if malicious, but that is not combined here with other definitive red flags.

What to consider before installing

This package mostly does what it says (a CLI Kaspa wallet) but contains a few important red flags you should address before use: - Do not run this on a machine that holds real funds until you vet it. The code requires a private key or mnemonic via environment variables; those are sensitive values. - The installer pulls the 'kaspa' package from PyPI with no version pin. Verify the 'kaspa' package on PyPI (author, downloads, homepage) and prefer a pinned, audited dependency. Consider running install in an isolated VM or container. - The registry metadata omits the required env vars; that mismatch is suspicious—assume the skill requires a wallet secret and treat it accordingly. - Review the included scripts (install.py and scripts/kaswallet.py) locally. If you can't audit the code, consider using ephemeral testnet keys (KASPA_NETWORK=testnet-10) and fund only a small test balance first. - If you decide to install, run the installer in a sandbox (container/VM), inspect what gets installed into .venv, and avoid storing secrets in shared shells or logs. Prefer hardware wallets or a well-known, audited wallet for real funds. If you want, I can: - fetch and summarize the remainder of scripts/kaswallet.py (the file was truncated in the review input) to look for further surprises, - check the PyPI 'kaspa' package metadata, or - suggest minimal changes to harden the installer (pin deps, add checksum/lockfile, declare env requirements in metadata).

Kaspa Wallet CLI

A standalone command-line wallet for the Kaspa blockchain network.

Installation

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

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

Optional:

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

./kaswallet.sh balance                    # Your wallet balance
./kaswallet.sh balance kaspa:qrc8y...     # Any address balance

Output:

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

Send KAS

./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):

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

Output (error):

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

Network Info

./kaswallet.sh info

Output:

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

Fee Estimates

./kaswallet.sh fees

Output:

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

Generate New Wallet

./kaswallet.sh generate-mnemonic

Output:

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

Payment URI

./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:

# 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

# 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

# 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