diff --git a/README.md b/README.md
new file mode 100644
index 0000000..bd36358
--- /dev/null
+++ b/README.md
@@ -0,0 +1,29 @@
+# chongming-jwt
+
+基于 Rust 和 PyO3 实现的 JWT 库，性能优越，支持 HS256/HS384/HS512/RS256/RS384/RS512。
+
+## 安装
+
+通过 uv 自动编译（需 Rust 工具链）。
+
+## 使用
+
+```python
+from chongming_jwt import JWT
+
+jwt = JWT("your-secret-key", "HS256")
+
+# 编码
+token = jwt.encode('{"sub": "user"}', expires_in_seconds=3600)
+
+# 解码
+payload = jwt.decode(token)
+
+# 验证
+is_valid = jwt.validate(token)
+```
+
+## 注意
+
+- 载荷必须包含 `sub` 字段
+- 密钥建议至少 32 字节（HS256）