diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c3c21e1
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# Nostr Widget
+
+A simple WordPress plugin to display the latest Nostr posts from a configurable public key and up to 5 HTTP Nostr relay APIs, right in a widget area of your site.
+
+## Features
+
+* Show recent Nostr text posts (“notes”) from any public key
+* Supports up to 5 configurable relay API URLs (e.g., nostr.band, Mutiny, etc.)
+* Simple widget UI for configuration
+* Stops at the first relay that returns posts (tries relays in order)
+* Lightweight and easy to use
+
+## Requirements
+
+* WordPress 5.0 or later
+* PHP 7.4 or later
+* At least one relay that supports HTTP API (WebSocket-only relays are not supported in PHP)
+
+## Installation
+
+1. Upload the plugin files to the `/wp-content/plugins/nostr-widget/` directory, or install via the WordPress plugin admin screen by uploading the ZIP.
+2. Activate the plugin through the **Plugins** menu in WordPress.
+3. Go to **Appearance → Widgets**.
+4. Add the **Nostr Widget** to your desired sidebar or widget area.
+5. Enter the Nostr hex public key and at least one relay API endpoint (up to 5).
+6. Save and enjoy!
+
+## Relay Examples
+
+* [nostr.band](https://nostr.band/api/v0/search):
+  `https://nostr.band/api/v0/search`
+* [Mutiny Wallet relay](https://api.nostr.mutinywallet.com/):
+  `https://api.nostr.mutinywallet.com/search`
+
+> **Note:** Most public Nostr relays use WebSockets and are not accessible from PHP. You need a relay with an HTTP API like nostr.band or Mutiny.
+
+## Usage
+
+1. **Widget settings:**
+
+   * Enter your **Nostr public key** (hex format, e.g., `npub1...` is NOT supported yet).
+   * Enter one or more relay HTTP URLs.
+2. **Widget output:**
+
+   * The latest 5 text notes from the given public key will show up in your widget area.
+
+## Screenshot
+
+```
++----------------------+
+| Nostr Posts          |
++----------------------+
+| [2024-06-24 18:43]   |
+| Hello world!         |
+|----------------------|
+| [2024-06-23 20:11]   |
+| Another note here... |
+|----------------------|
+| ... up to 5 posts    |
++----------------------+
+```
+
+## Roadmap / TODO
+
+* [ ] npub1 → hex key support
+* [ ] Aggregate posts from all relays, not just first with results
+* [ ] Better error handling and relay status display
+* [ ] Custom CSS/styling options
+* [ ] Shortcode support
+
+## Contributing
+
+PRs and suggestions are welcome!
+Open an issue or submit a pull request.
+
+## License
+
+MIT