update readme

Author: jackharrhy

README.md

@@ -1,18 +1,62 @@
 # stackcoin-python
 
-Python client for interacting with the StackCoin HTTP API.
+Python library for the StackCoin API. Provides a typed async REST client and a WebSocket gateway for real-time events.
 
-https://pypi.org/project/stackcoin/
+## Install
 
 ```sh
 pip install stackcoin
 ```
 
+Requires Python 3.13+. Dependencies: `httpx`, `pydantic>=2`, `websockets`.
+
+## Quick start
+
+```python
+import asyncio
+import stackcoin
+
+async def main():
+    async with stackcoin.Client(token="...") as client:
+        me = await client.get_me()
+        print(f"{me.username}: {me.balance} STK")
+
+        events = await client.get_events()
+        for event in events:
+            print(f"[{event.type}] {event.data}")
+
+asyncio.run(main())
+```
+
+## Gateway (real-time events)
+
+```python
+import stackcoin
+
+gateway = stackcoin.Gateway(token="...")
+
+@gateway.on("transfer.completed")
+async def on_transfer(event: stackcoin.TransferCompletedEvent):
+    print(f"Transfer of {event.data.amount} STK from #{event.data.from_id} to #{event.data.to_id}")
+
+@gateway.on("request.accepted")
+async def on_accepted(event: stackcoin.RequestAcceptedEvent):
+    print(f"Request #{event.data.request_id} accepted")
+
+await gateway.connect()
+```
+
 ## Examples
 
-- `./examples/basic_usage.py`, bare bones creation of `AuthenticatedClient`, checking balance, making some requests, etc.
-- `./examples/simple_cli.py`, thorough usage of the API in a bare-bones command line interface.
+- `examples/basic_usage.py` -- REST client basics (balance, requests, transactions)
+- `examples/simple_cli.py` -- interactive REPL with live gateway events
 
----
+## Development
+
+Models are generated from the StackCoin OpenAPI spec using `datamodel-codegen`:
+
+```sh
+STACKCOIN_ROOT=/path/to/StackCoin just generate
+```
 
-This package is generated by running [openapi-python-client](https://github.com/openapi-generators/openapi-python-client) against [StackCoin's OpenAPI specification](https://stackcoin.world/swaggerui), the `./stackcoin` directory in this repository is the package, and is generated by running `just generate` (or running the commands under `generate` in the `Justfile`).
+This regenerates `stackcoin/stackcoin/models.py` from `openapi.json`.