Kasia — Encrypted Messaging on Kaspa
Send and receive encrypted messages on the Kaspa blockchain via the Kasia protocol. Uses mcporter to call kasia-mcp tools.
Prerequisites
mcporterinstalled (npm install -g mcporter)kasia-mcpbuilt and configured inconfig/mcporter.jsonkaspa-mcpconfigured (same wallet) — needed to broadcast transactions- Wallet mnemonic or private key set in mcporter config
Run scripts/setup.sh to configure automatically:
scripts/setup.sh /path/to/kasia-mcp --mnemonic "your twelve word phrase" --network mainnet
Verify: mcporter list kasia (should show 8 tools)
Tools
Call via mcporter call kasia.<tool> from the workspace directory.
Read Operations (no transaction needed)
| Tool | Purpose | Example |
|---|---|---|
kasia_get_conversations | List all conversations + status | mcporter call kasia.kasia_get_conversations |
kasia_get_requests | Pending incoming handshakes | mcporter call kasia.kasia_get_requests |
kasia_get_messages | Read decrypted messages | mcporter call kasia.kasia_get_messages address="kaspa:q..." |
kasia_read_self_stash | Read encrypted private data | mcporter call kasia.kasia_read_self_stash scope="notes" |
Write Operations (two-step: generate payload → broadcast)
Write tools return a payload and instructions. Broadcast with kaspa.send_kaspa:
# Step 1: Generate payload
mcporter call kasia.kasia_send_handshake address="kaspa:q..."
# Returns: { action, to, amount, payload, instructions }
# Step 2: Broadcast (use the returned values)
mcporter call 'kaspa.send_kaspa(to: "kaspa:q...", amount: "0.2", payload: "<hex>")'
| Tool | Purpose |
|---|---|
kasia_send_handshake | Start a conversation with someone |
kasia_accept_handshake | Accept an incoming handshake request |
kasia_send_message | Send an encrypted message in an active conversation |
kasia_write_self_stash | Store encrypted private data on-chain |
Conversation Flow
- Check requests:
kasia_get_requests— see pending incoming handshakes - Start or accept:
kasia_send_handshakeorkasia_accept_handshake→ broadcast withkaspa.send_kaspa - Chat:
kasia_send_message→ broadcast. Read replies withkasia_get_messages - Pay: Use
kaspa.send_kaspadirectly for payments (no Kasia-specific tool needed)
Conversation Status
pending_outgoing— You sent a handshake, waiting for acceptancepending_incoming— Someone sent you a handshake, needs acceptanceactive— Both sides completed handshake, can exchange messages
Background Polling
For real-time message relay, set up a background poller:
- Create a polling script that calls
kasia_get_messagesevery N seconds - Track seen transaction IDs to avoid duplicates
- Write new messages to a file (e.g.,
memory/kasia-new-messages.jsonl) - Use a cron job or heartbeat check to relay new messages to the user
See references/protocol.md for the full protocol specification and indexer API details.
Important
- Mainnet only — kasia-mcp enforces mainnet (messaging isn't available on testnet)
- Two-step writes — Write tools generate payloads; you must broadcast with
kaspa.send_kaspa - Same wallet — kasia-mcp and kaspa-mcp must use the same mnemonic/key
- Costs KAS — Every message is a transaction (~0.2 KAS minimum per tx)