https://github.com/Spl0itable/NYM
A lightweight, yet feature-rich, ephemeral chat client built on Nostr protocol, bridged with Bitchat for anonymous, temporary messaging.
https://github.com/Spl0itable/NYM
android android-app android-application bitchat chat chat-app chat-application chatapp chatroom ios ios-app ios-application messenger messenger-platform nostr nostr-client nostr-protocol
Last synced: about 2 months ago
JSON representation
A lightweight, yet feature-rich, ephemeral chat client built on Nostr protocol, bridged with Bitchat for anonymous, temporary messaging.
- Host: GitHub
- URL: https://github.com/Spl0itable/NYM
- Owner: Spl0itable
- License: agpl-3.0
- Created: 2025-08-23T06:49:55.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2026-04-10T06:50:57.000Z (2 months ago)
- Last Synced: 2026-04-10T08:36:34.275Z (2 months ago)
- Topics: android, android-app, android-application, bitchat, chat, chat-app, chat-application, chatapp, chatroom, ios, ios-app, ios-application, messenger, messenger-platform, nostr, nostr-client, nostr-protocol
- Language: JavaScript
- Homepage: https://nymchat.app
- Size: 10.2 MB
- Stars: 50
- Watchers: 0
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-nostr - Nymchat - A like iRC lightweight, yet feature-rich, ephemeral chat client built on Nostr protocol, bridged with Bitchat for anonymous, temporary messaging. (Clients / Mobile)
README
```
##\ ##\
## | ## |
#######\ ##\ ##\ ######\####\ #######\ #######\ ######\ ######\
## __##\ ## | ## |## _## _##\ ## _____|## __##\ \____##\\_## _|
## | ## |## | ## |## / ## / ## |## / ## | ## | ####### | ## |
## | ## |## | ## |## | ## | ## |## | ## | ## |## __## | ## |##\
## | ## |\####### |## | ## | ## |\#######\ ## | ## |\####### | \#### |
\__| \__| \____## |\__| \__| \__| \_______|\__| \__| \_______| \____/
##\ ## |
\###### |
\______/
```
# Nymchat
A lightweight, yet feature-rich, ephemeral chat client built on [Nostr](https://github.com/nostr-protocol/nostr) protocol, bridged with [Bitchat](https://bitchat.free) for anonymous, temporary messaging.
## Overview
Nymchat, also known as NYM (Nostr Ynstant Messenger), is a Progressive Web App (PWA) chat messenger that uses [Nostr](https://github.com/nostr-protocol/nostr)'s ephemeral events (kind 20000) for non-geohash and geohash-based location channels and [NIP-17](https://github.com/nostr-protocol/nips/blob/master/17.md) encrypted events (kind 1059) for private messages. No registration required - just pick a nym and start chatting.
## Features
### Identity
- **Ephemeral Identity** - Generate temporary keypairs and pseudonyms per session
- **Auto-Ephemeral Mode** - Auto-start ephemeral sessions without a welcome screen
### Channels
- **Geohash Channels** - Location-based channels using geohash encoding (kind 20000)
- **Non-Geohash Channels** - Non-geohash channels (kind 20000)
- **Channel Sharing** - Generate shareable URLs for channels
- **Channel Pinning** - Pin frequently used channels to the top of your list
- **Proximity Sorting** - Sort geohash channels by distance from your location
### Messaging
- **Private Messages** - End-to-end encrypted 1:1 PMs using [NIP-17](https://github.com/nostr-protocol/nips/blob/master/17.md) (kind 14 rumor format) wrapped in NIP-59 gift wraps
- **MLS Group Chats (Marmot Protocol)** - End-to-end encrypted group messaging using the [Marmot Protocol](https://github.com/nicobao/NIP-EE) (MLS / [RFC 9420](https://www.rfc-editor.org/rfc/rfc9420)), providing forward secrecy and post-compromise security for group conversations. Uses kind 443 (KeyPackage), kind 444 (Welcome), and kind 445 (group messages). Falls back to NIP-17 automatically if MLS is unavailable.
- **Private Group Chats (Legacy)** - End-to-end encrypted multi-party group chats via [NIP-59](https://github.com/nostr-protocol/nips/blob/master/59.md); each message is individually gift-wrapped per member with an ephemeral sender key and a randomized envelope timestamp (±2 h) so relays cannot correlate group membership or timing
- **Rich Text** - Markdown support for bold, italic, strikethrough, code blocks, and quotes
- **Message Reactions** - React to messages with emojis ([NIP-25](https://github.com/nostr-protocol/nips/blob/master/25.md))
- **Auto-Reply** - Set away messages with `/brb` command
- **Image/Video Sharing** - Upload and share images or video
### Lightning Integration
- **Lightning Zaps** - Send Lightning payments to messages and user profiles ([NIP-57](https://github.com/nostr-protocol/nips/blob/master/57.md))
- **Lightning Addresses** - Set your Lightning address for receiving zaps
- **QR Invoice Display** - Visual QR codes for Lightning invoices
### Moderation & Privacy
- **User Blocking** - Block unwanted users and channels
- **Keyword Filtering** - Block messages containing specific keywords or phrases
- **Flood Protection** - Automatic spam prevention
- **Image Blur** - Option to blur images from other users until clicked
### Customization
- **Multiple Themes** - Matrix Green, Amber, Cyberpunk, Hacker Blue, Ghost (B&W), Bitchat (Multicolor)
- **Notification Sounds** - Classic Beep, ICQ Uh-Oh, MSN Alert, or Silent
- **Time Format** - 12-hour or 24-hour time display
- **Auto-Scroll** - Toggle automatic message scrolling
## Protocol Implementation
### Channels
- Geohash event `kind 20000` with `['g', geohash]` tag
- Non-Geohash event `kind 20000` with `['g', channel]` tag
- Tag `['n', nym]` for nickname
### Private Messages & Group Chats (NIP-17)
- NIP-17 `kind 14` rumor (message content + metadata) sealed inside NIP-59 `kind 1059` gift wraps
- Each gift wrap uses a one-time ephemeral sender key; the `created_at` timestamp is randomized ±2 hours so relays cannot correlate senders, recipients, or timing
- Group chats send one gift wrap per member — each individually encrypted to that member's public key
### MLS Group Chats (Marmot Protocol)
- Based on the [Messaging Layer Security (MLS)](https://www.rfc-editor.org/rfc/rfc9420) protocol via [Marmot Protocol](https://github.com/marmot-protocol/marmot)
- `kind 443` — KeyPackage publication (pre-keys for group invitations)
- `kind 444` — Welcome messages (gift-wrapped to invited members)
- `kind 445` — Group messages (encrypted with epoch-level keys from the MLS ratchet tree)
- Provides forward secrecy and post-compromise security — compromising a single key does not expose past or future messages
- Falls back to legacy NIP-17 gift wraps automatically when MLS is unavailable
- Typing indicators, reactions, and read receipts work across both NIP-17 and MLS groups
### Reactions & Zaps
- Reaction events `kind 7` (NIP-25) with `['k', originalKind]` tag for proper categorization
- Lightning zaps `kind 9735` (NIP-57) with full invoice generation and payment tracking
## Available Commands
**Basic Commands:**
- `/help` - Show available commands
- `/join ` - Join a channel (e.g., /join #9q5)
- `/j` - Shortcut for /join
- `/pm ` - Open a 1:1 private message (e.g., /pm nym or /pm nym#xxxx)
- `/nick ` - Change your nym
- `/who` - List online nyms in current channel
- `/w` - Shortcut for /who
- `/clear` - Clear chat messages
- `/leave` - Leave current channel or group chat
- `/quit` - Disconnect from Nymchat
**Group Chat Commands:**
- `/group @user1 @user2 [name]` - Create a new private group (uses MLS when available)
- `/invite @nym` - In a channel: invite user to the channel. In a group chat: add a new member to the group
- `/addmember @nym` - Add a member to the current group chat
- `/groupinfo` - Show members of the current group
- `/leave` - Leave and remove yourself from the current group chat
**Moderation Commands:**
- `/block [nym|#channel]` - Block a user or channel
- `/unblock ` - Unblock a user or channel
**Social Commands:**
- `/slap ` - Slap someone with a trout
- `/hug ` - Give a warm hug
- `/me ` - Action message (e.g., /me is coding)
- `/shrug` - Send a shrug ¯\_(ツ)_/¯
- `/brb ` - Set away message
- `/back` - Clear away message
- `/poll` - Create a poll
**Formatting Commands:**
- `/bold ` or `/b` - Send bold text
- `/italic ` or `/i` - Send italic text
- `/strike ` or `/s` - Send strikethrough text
- `/code ` or `/c` - Send code block
- `/quote ` or `/q` - Send quoted text
**Lightning Commands:**
- `/zap ` - Send Lightning zap to user profile
**Channel Commands:**
- `/share` - Share current channel URL
## Nymbot
Nymbot is a built-in AI-powered chat bot that responds to `?` commands in any channel. You can also mention **@Nymbot** in a message or quote-reply to a Nymbot response to continue a conversation.
### Bot Commands
**AI & Knowledge:**
- `?ask ` - Ask the AI anything (also triggered via `@Nymbot `)
- `?define ` - Look up a word's definition, part of speech, and example usage
- `?translate ` - Translate text (auto-detects language; English text translates to Spanish)
- `?news` - Latest breaking news headlines
**Games & Fun:**
- `?trivia [category]` - Trivia questions (categories: general, history, science, crypto, nostr)
- `?joke` - Random tech/Bitcoin-themed joke
- `?riddle` - Random riddle — reply to answer
- `?wordplay [mode]` - Word games (modes: wordle, anagram, scramble) — reply to guess
- `?roll [NdN]` - Roll dice (e.g., `?roll 2d6`; default 1d6)
- `?flip` - Flip a coin
- `?8ball ` - Magic 8-ball
- `?pick ...` - Randomly pick from a list of options
**Utility:**
- `?math ` - Calculate a math expression
- `?units to ` - Unit converter (e.g., `?units 10 km to mi`)
- `?time` - Current UTC time and Unix timestamp
- `?btc` - Current Bitcoin price
**Channel Activity:**
- `?who` - Who's active in the current channel
- `?summarize` - Summary of the current channel discussion
- `?top` - Top channels by recent message activity
- `?last [N]` - Last N messages across channels (default 10, max 25)
- `?seen ` - Where and when a nym was last seen
**Info:**
- `?help` - List all available bot commands
- `?about` - About Nymchat
- `?nostr` - Random Nostr protocol tips
### Conversational AI
Nymbot is context-aware — when you use `?ask` or `?summarize`, the bot receives the recent channel messages and active user list, so it can answer questions about the current conversation, reference what users said, and summarize discussions intelligently.
Quote-reply to any Nymbot response to continue the conversation — the bot automatically carries context from the reply chain (up to 6 messages of history). You can also quote any message and mention `@Nymbot` to ask the AI about it.
## Running PWA Locally
You can load Nymchat directly on your own machine by opening the `index.html` file in your browser:
1. Clone or download this repository
2. Open `index.html` in any modern web browser (Chrome, Firefox, Safari, Edge)
3. That's it — Nymchat will connect to the Nostr relay network and you can start chatting
No build tools, web server, or dependencies are required. The entire web app is self-contained in the `index.html`, `css/`, and `js/` directories.
## Mobile App (iOS & Android)
Nymchat is also available as an open source Flutter app for iOS and Android. The source code is located in the [`android-ios-app/`](android-ios-app/) directory.
The Flutter app is a native shell wrapper around the Nymchat PWA, providing:
- **Push Notifications** - Native push notifications for new messages
- **Native Performance** - Smooth, native-feeling experience on both platforms
### Building the Flutter App
1. Ensure you have the [Flutter SDK](https://flutter.dev/docs/get-started/install) installed (requires SDK ^3.6.0)
2. Navigate to the app directory:
```
cd android-ios-app
```
3. Install dependencies:
```
flutter pub get
```
4. Run on your device or emulator:
```
flutter run
```
## Contributing
Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request
## Changelog
See the [releases page](https://github.com/Spl0itable/NYM/releases) for each update's changes.
## Legal
If you choose to use Nymchat on 21 Million LLC operated infrastructure and domain (nymchat.app), your use is subject to the below Terms of Service and Privacy Policy.
- [Terms of Service](https://web.nymchat.app/static/tos)
- [Privacy Policy](https://web.nymchat.app/static/pp)
## Contact
Created and operated by [21 Million LLC](https://nostrservices.com) - Lead developer: [@Luxas#a8df](https://nostr.band/npub16jdfqgazrkapk0yrqm9rdxlnys7ck39c7zmdzxtxqlmmpxg04r0sd733sv)
## License
Copyright 21 Million LLC
Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details. https://www.gnu.org/licenses/agpl-3.0.html