1 files changed, 59 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0e7c891
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# nostr
+
+A Go library for the [Nostr protocol](https://github.com/nostr-protocol/nostr).
+
+```bash
+go get code.northwest.io/nostr
+```
+
+## Features
+
+- **Keys** — Generate, parse, and convert between hex/bech32 (npub/nsec)
+- **Events** — Create, sign, and verify NIP-01 events
+- **Filters** — Build subscription filters
+- **Relay** — WebSocket connections with publish/subscribe
+- **Tags** — Parse and build event tags
+
+## Usage
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "code.northwest.io/nostr"
+)
+
+func main() {
+    // Generate a new key pair
+    key, _ := nostr.GenerateKey()
+    fmt.Println("npub:", key.Npub())
+
+    // Create and sign an event
+    event := &nostr.Event{
+        Kind:    nostr.KindTextNote,
+        Content: "Hello Nostr!",
+    }
+    event.Sign(key)
+
+    // Connect to a relay and publish
+    ctx := context.Background()
+    relay, _ := nostr.Connect(ctx, "wss://relay.damus.io")
+    defer relay.Close()
+
+    relay.Publish(ctx, event)
+}
+```
+
+## Examples
+
+See [examples/basic](examples/basic) for a complete runnable example.
+
+## Benchmarks
+
+Performance benchmarks are in [benchmarks/](benchmarks/).
+
+## License
+
+MIT