HandleChat
HandleChat lets people with supported Cardano wallets and Handle NFTs start one-to-one chats using $handles.
Today, HandleChat focuses on the core chat flow: connect a wallet, resolve another person's $handle, complete the session handshake, and exchange encrypted text messages.
HandleChat uses the Signal protocol through libsignal-compatible libraries to establish secure sessions between participants. Messages are encrypted before they leave the sender and decrypted only by the intended recipient.
- A supported browser Cardano wallet.
- At least one Handle NFT in that wallet.
- A wallet with a staking or reward address available.
Important:
If your wallet does not contain a Handle NFT, HandleChat will not let you continue past sign-in.
- Open HandleChat and connect your wallet.
- Select Start Chatting.
- HandleChat checks your wallet for a Handle and uses it as your chat identity.
If your wallet has multiple Handles, HandleChat currently uses the first one it can successfully resolve.
- Select + New Chat.
- Enter the other person's $handle.
- Select Resolve to confirm the Handle exists.
- Select Add Chat.
The new conversation appears in your chat list immediately, then remains in a waiting state until the other person completes the session on their side.
Note:
HandleChat currently starts new chats by resolving a $handle. There is no separate contact directory inside the app.
When someone starts a chat with you, the conversation appears in your sidebar with two options:
- Accept starts the session and opens the chat.
- Deny declines the request and removes it from your list.
Once the session is active, you can send and receive encrypted text messages in the conversation thread. Messages are shown with timestamps, and unread activity in other chats is highlighted in the sidebar.
Opening a different conversation can trigger a fresh session handshake before messaging continues. This is part of the current secure session flow.
HandleChat is designed so message contents stay protected during transport and are not handled as readable plain text within the messaging flow.
- Messages are encrypted end-to-end, so the sender and intended recipient are the parties who can read the message body.
- Session setup uses Signal-style identity keys, pre-keys, and session negotiation instead of plain text message exchange.
- When a session needs to be resumed or refreshed, HandleChat re-establishes the secure session rather than continuing with a broken state.
- If decryption fails, HandleChat treats that as a session problem and prompts recovery instead of presenting corrupted content as a valid message.
Developer note:
The HandleChat app and SDK use the Signal protocol through the libsignal stack for session setup, encryption, and message decryption.
- You can remove an individual chat from the sidebar. This clears that chat from the current device.
- You can disconnect your wallet. This clears all HandleChat data from the current device and returns you to the sign-in screen.
- Chats are one-to-one only.
- Messages are text only.
- Chat history is stored in the current browser on the current device. It is not synced across devices.
- If a secure session breaks, HandleChat can mark the affected message as failed and ask you to refresh before trying again.
Developers who want to build their own HandleChat-compatible client can use the @koralabs/handle-chat-sdk package.
The SDK is focused on the encrypted messaging layer. It provides helpers for creating local identity bundles, populating Signal stores, encrypting outgoing messages, decrypting incoming messages, and serializing chat state for browser or app storage.
- Use it to generate identity and pre-key material for a chat user.
- Use it to encrypt and decrypt message payloads between participants.
- Use it to serialize bundles and local stores so chat state can survive page reloads.
- Use it with your own UI and transport layer, or alongside the HandleChat service.
For package setup and exported utilities, see the SDK installation and SDK reference pages.