euclid-clob-sdk 0.1.0__tar.gz

euclid_clob_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Euclid Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

euclid_clob_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,567 @@
+Metadata-Version: 2.4
+Name: euclid-clob-sdk
+Version: 0.1.0
+Summary: Python SDK for the Euclid exchange API
+Author: Euclid Protocol
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/EuclidProtocol/euclid-python-sdk
+Project-URL: Repository, https://github.com/EuclidProtocol/euclid-python-sdk
+Project-URL: Issues, https://github.com/EuclidProtocol/euclid-python-sdk/issues
+Project-URL: Changelog, https://github.com/EuclidProtocol/euclid-python-sdk/blob/main/CHANGELOG.md
+Keywords: euclid,exchange,trading,orderbook,clob,market-data,websocket,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx2<3,>=2.13.1
+Requires-Dist: attrs>=22.2.0
+Requires-Dist: websockets<18,>=15
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Provides-Extra: codegen
+Requires-Dist: openapi-python-client==0.30.0; extra == "codegen"
+Requires-Dist: ruff==0.17.4; extra == "codegen"
+Provides-Extra: typecheck
+Requires-Dist: mypy==2.4.1; extra == "typecheck"
+Dynamic: license-file
+
+# Euclid Python SDK
+
+A Python client for the Euclid exchange API: market data, account and balances, and order
+placement, with a blocking client and an asyncio client that share one implementation, plus
+asyncio WebSocket streams for live market data, a local order book, and your own account events.
+
+> **Status: pre-release (`0.x`).** The API of this package may change between minor versions;
+> [`CHANGELOG.md`](CHANGELOG.md) says what each release changed.
+
+## Install
+
+Python 3.11 or newer.
+
+```bash
+pip install euclid-clob-sdk
+```
+
+The distribution is named `euclid-clob-sdk`; the package you import is `euclid`.
+
+## Getting started
+
+The example scripts are in this repository, not in the installed package, so start from a
+checkout:
+
+```bash
+git clone https://github.com/EuclidProtocol/euclid-python-sdk
+cd euclid-python-sdk
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .
+export EUCLID_BASE_URL=https://your-euclid-host.example
+export EUCLID_API_KEY="ek1.<key-id>.<secret>"     # optional: leave it out for public data only
+python examples/check_setup.py
+```
+
+`check_setup.py` prints one line per check: the configuration, the server, market data, the
+WebSocket and, when a key is set, one read per kind of private data, with the scopes the key is
+missing. It changes nothing and never prints the key. From there,
+[`examples/`](examples/README.md) is a path from reading an order book to a small quoting loop
+that only trades when you pass `--live`.
+
+The SDK and the examples read real environment variables. Nothing loads a `.env` file for you.
+[`.env.example`](.env.example) lists the variable names; to use a copy of it from your shell:
+
+```bash
+cp .env.example .env          # then edit .env; it is ignored by git
+set -a; source .env; set +a
+```
+
+## Quick start
+
+```python
+from decimal import Decimal
+from euclid import EuclidClient, OrderType, Side
+
+with EuclidClient("ek1.<key-id>.<secret>", base_url="https://<your-euclid-host>") as client:
+    book = client.get_order_book("ETH-USDC", limit=5)
+    print(book.bids[0].price, book.asks[0].price)
+
+    order = client.place_order(
+        pair_id="ETH-USDC",
+        side=Side.BUY,
+        order_type=OrderType.POST_ONLY,
+        price=Decimal("1950.25"),
+        base_size=Decimal("0.5"),
+    )
+    client.cancel_order(pair_id="ETH-USDC", order_id=order.order_id)
+```
+
+`AsyncEuclidClient` has the same methods with the same arguments; `await` them and use
+`async with`. Live data is under [WebSocket streams](#websocket-streams). Runnable scripts are
+in [`examples/`](examples/README.md).
+
+## Configuration
+
+The API is five services that may be on different hosts. This package contains no hostnames;
+you supply them.
+
+```python
+from euclid import Environment, EuclidClient
+
+# One origin for everything:
+client = EuclidClient(api_key, base_url="https://gateway.example")
+
+# Or one URL per service:
+client = EuclidClient(
+    api_key,
+    environment=Environment(
+        engine="https://...",  # orders, balances, pairs, assets
+        market_data="https://...",  # order book, klines, tickers, trades
+        order_history="https://...",  # open orders and order history
+        account_indexer="https://...",  # account history: transactions, deposits, withdrawals, transfers
+        auth="https://...",  # not used by any wrapped method yet
+    ),
+)
+
+# Or from the environment: EUCLID_API_KEY, EUCLID_BASE_URL, and optionally
+# EUCLID_ENGINE_URL, EUCLID_MARKET_DATA_URL, EUCLID_ORDER_HISTORY_URL,
+# EUCLID_ACCOUNT_INDEXER_URL, EUCLID_AUTH_URL.
+client = EuclidClient.from_env()
+```
+
+The WebSocket URLs are derived from these: the market-data stream is `/ws` on the market-data
+URL and the account stream is `/ws/account/transactions` on the engine URL, with `https`
+becoming `wss`. If your deployment serves them elsewhere, set
+`Environment(market_data_stream="wss://...", account_stream="wss://...")` or
+`EUCLID_MARKET_DATA_WS_URL` and `EUCLID_ACCOUNT_WS_URL`.
+
+- The API key is optional. Without one, the public methods work and the others raise
+  `ConfigurationError` before sending anything.
+- The key is sent only on routes that require it, as `Authorization: Bearer <key>`. It is never
+  sent to the market-data service.
+- Plain `http://` and `ws://` are refused except for localhost, unless you pass
+  `allow_insecure_http=True`.
+- `client.has_api_key` says whether the client has a credential, and
+  `client.environment.configured` lists the URLs that are set.
+
+## Amounts are `Decimal`
+
+Every price, size and balance is a `decimal.Decimal` in human units, in both directions:
+`Decimal("0.5")` ETH, never a scaled integer and never a float. Arguments accept a `Decimal`,
+an `int` or a `str`. A `float` raises `TypeError`, because `0.1 + 0.2` is not `0.3`.
+
+The API itself returns most amounts as integers scaled by a per-pair or per-asset number of
+decimal places. The SDK reads those scales from the exchange and converts for you. It caches
+them for `metadata_ttl` seconds (default 60); `client.forget_metadata()` drops the cache.
+
+`str()` of a very small `Decimal` uses scientific notation (`1E-8`). Print with the `f` format
+to avoid it: `f"{balance.available:f}"`.
+
+An order's price must be a whole number of the pair's `tick_size` and its size a whole number
+of `lot_size`. A `Pair` rounds for you, exactly:
+
+```python
+pair = next(p for p in client.list_pairs() if p.pair_id == "ETH-USDC")
+bid = pair.round_price(mid - offset)  # down to the tick
+ask = pair.round_price(mid + offset, up=True)  # up to the tick
+size = pair.round_size("0.12345")  # down to the lot
+smallest = pair.min_size_at(bid)  # smallest order the pair accepts at that price
+```
+
+Do not use `Decimal.quantize` for this. It fixes the number of decimal places, which is the
+same thing only when the tick is a power of ten: with a tick of `0.05`,
+`Decimal("100.02").quantize(Decimal("0.05"))` is still `100.02`.
+
+## Errors
+
+A failed call raises; nothing returns an error object. Everything derives from `EuclidError`.
+
+| Exception | When |
+| --- | --- |
+| `ValidationError` | 400: malformed request or a trading rule was broken |
+| `AuthenticationError` | 401: missing, invalid or expired credential |
+| `PermissionDeniedError` | 403: valid credential, not allowed |
+| `InsufficientScopeError` | 403 with reason `INSUFFICIENT_SCOPE` (a `PermissionDeniedError`) |
+| `NotFoundError` | 404: unknown order, pair or symbol |
+| `ConflictError` | 409 |
+| `RateLimitError` | 429; `retry_after` holds the `Retry-After` seconds when sent |
+| `ServerError` | 5xx |
+| `NetworkError`, `RequestTimeoutError` | no HTTP response arrived |
+| `UnexpectedResponseError` | a success response the SDK could not read |
+| `ConfigurationError`, `UnknownPairError` | raised locally, before or without a request |
+| `SubscriptionError` | a stream subscription the server refused for good (`UNKNOWN_SYMBOL`, ...) |
+| `StreamError` | a stream gave up reconnecting, or could not be brought back in sync |
+| `StreamTimeoutError` | nothing arrived within the `timeout` given to `receive` (also a built-in `TimeoutError`) |
+
+Server errors are `APIError` subclasses and carry `status`, `reason` (such as
+`VALIDATION_FAILED`), `domain` (such as `engine.euclid`), `message`, `error_code` (the stable
+business code, such as `POST_ONLY_WOULD_CROSS`), `metadata` and `body`.
+
+```python
+from euclid import RateLimitError, ValidationError
+
+try:
+    client.place_order(pair_id="ETH-USDC", side="buy", price="1950.25", base_size="0.5")
+except ValidationError as error:
+    print(error.error_code, error.message)
+except RateLimitError as error:
+    print("retry in", error.retry_after)
+```
+
+After a `NetworkError` on a call that changes state, the SDK cannot know whether the server
+applied it. Check `list_open_orders()` before retrying an order. The SDK never retries by itself.
+
+## Account history
+
+```python
+page = client.list_account_transactions(page_size=50)  # newest first
+for tx in page.items:
+    print(tx.engine_seq, tx.kind, [t.base_amount for t in tx.trades])
+
+# Everything after a known point, oldest first, across all pages:
+for tx in client.paginate(client.list_account_transactions, after_engine_seq=1200):
+    ...
+
+# At most 250 items, asking for no page that is not needed:
+recent = list(client.paginate(client.list_my_trades, limit=250))
+
+# Page by page, when you want what a page carries besides its items:
+for page in client.pages(client.list_deposits, page_size=100):
+    print(len(page.items), page.freshness)
+
+found = client.get_account_transaction(transaction_hash="...")
+deposits = client.list_deposits(asset="USDC")
+withdrawals = client.list_withdrawals(status="reserved")
+transfers = client.list_transfers(direction="sent")
+```
+
+With `AsyncEuclidClient`, `paginate` is an async iterator: `async for tx in client.paginate(...)`.
+A `page_token` remembers the position and direction of a walk, so `after_engine_seq` and
+`before_engine_seq` are ignored when a token is given.
+
+**This data is a projection and can trail the engine.** It is served by the account indexer,
+which stores what the engine commits a moment after the engine commits it. Three consequences:
+
+- Every page and lookup carries a `freshness`: `freshness.is_current`, `freshness.state`, and
+  `freshness.lag` (how many engine sequences behind, when known).
+- A lookup returns a `Lookup`. `result.item is None` means the indexer has no such record.
+  Treat that as "does not exist" only when `result.known_absent` is true; otherwise the
+  indexer may not have caught up yet and the lookup is worth repeating.
+- For anything you act on, ask the authoritative service: balances from `get_balances`
+  (the engine ledger), open orders from `list_open_orders`. The account indexer's own copies of
+  balances and order holds are deliberately not wrapped.
+
+Scopes an API key needs: `funds:read` for transactions, `deposits:read`, `withdrawals:read` and
+`transfers:read` for the others.
+
+## WebSocket streams
+
+The streams are asyncio and are built on an `AsyncEuclidClient`, which they use for the URLs
+and for the REST calls they need. Each one is an async iterator. Blocking code can read its
+account's events with [`BlockingAccountStream`](#from-blocking-code); the market-data streams
+have no blocking form.
+
+`websockets` is the WebSocket library: it is the most widely used asyncio implementation, is
+pure Python with no dependencies of its own, and answers pings and detects dead connections
+without help.
+
+### Market data
+
+```python
+from euclid import AsyncEuclidClient, MarketDataStream
+
+async with AsyncEuclidClient(base_url="https://<your-euclid-host>") as client:
+    async with MarketDataStream(client) as stream:
+        async for trade in stream.trades("ETH-USDC"):
+            print(trade.price, trade.size)
+```
+
+| Method | Yields |
+| --- | --- |
+| `stream.depth(symbol, depth=20, speed_ms=100)` | `OrderBook`: a full snapshot that replaces the last |
+| `stream.depth_diff(symbol)` | `DepthDiff`: changed levels; size zero removes a level |
+| `stream.trades(symbol)` | `PublicTrade` |
+| `stream.book_ticker(symbol)` | `BookTicker`: best bid and ask |
+| `stream.klines(symbol, interval="1m")` | `KlineUpdate` |
+| `stream.order_book(symbol)` | `BookUpdate`, from a `LocalOrderBook` |
+
+The server allows one subscription per connection, so every subscription has its own
+connection; `MarketDataStream` keeps track of them and closes them together. Iterate several
+subscriptions from separate tasks. Closing a subscription (`await subscription.aclose()`, or
+leaving its `async with`) sends an unsubscribe, which ends that connection for good. It waits
+at most `close_timeout` seconds (default 5, set on `MarketDataStream`) for the server to
+acknowledge, then closes anyway. No API key is sent.
+
+To wait for one event with a time limit, instead of looping:
+
+```python
+book = await stream.depth("ETH-USDC").receive(timeout=10)
+```
+
+`receive` raises `StreamTimeoutError` if nothing arrives in time, and the message says why
+connecting failed if it did. The subscription can still be read afterwards.
+
+### A local order book
+
+```python
+async with stream.order_book("ETH-USDC", depth=1000) as book:
+    async for update in book:
+        print(book.best_bid, book.best_ask, book.bids(5), update.resynced)
+```
+
+`LocalOrderBook` subscribes to the depth-diff channel, loads a snapshot over REST and applies
+each diff on top. Every diff names the range of book updates it covers. A diff that is already
+included is ignored. A diff that skips an update is a gap: the book stops, loads a fresh
+snapshot and continues from there, and it does the same after every reconnect. It never applies
+a diff out of sequence. `book.gaps` and `book.resyncs` count what happened.
+
+The server sends the latest change roughly every 200 ms, not every change, so on a busy pair
+gaps are normal and the book is rebuilt from snapshots often (at most once per
+`min_resync_interval`, default one second). If you only need the top of a busy book,
+`stream.depth(symbol, depth=20, speed_ms=100)` is simpler and just as fresh.
+
+### Your account's events
+
+```python
+from euclid import AccountStream
+
+async with AsyncEuclidClient(api_key, base_url="https://<your-euclid-host>") as client:
+    async with AccountStream(client) as stream:
+        async for event in stream:
+            print(event.kind, event.transaction_hash, event.orders, event.trades)
+```
+
+Each event is one committed transaction that touched your account, as the same
+`AccountTransaction` record that [`list_account_transactions`](#account-history) returns: `kind`
+(`"place_order"`, `"cancel_order"`, ...), `engine_seq`, the order changes it made and the trades
+it executed, with amounts as `Decimal`. `event.raw` is the transaction exactly as the server
+sent it, and `event.unparsed` names any amount the SDK could not convert because its pair or
+asset is not in the exchange's lists. The stream authenticates with a 60-second ticket that it
+fetches itself; the API key needs the `funds:read` scope.
+
+To continue where an earlier run stopped, save `stream.cursor` and pass
+`AccountStream(client, cursor=saved)`. Without a cursor the stream starts at the present;
+`from_start=True` replays the account's history first.
+
+After a disconnect the stream reads what it missed over HTTP, from the account history, and
+yields it in order before it reconnects, so events keep arriving even while the socket cannot
+be re-established. You can also ask for this yourself:
+`await stream.backfill(after_engine_seq=n)` queues everything after sequence `n`, to be yielded
+next. History is read by `engine_seq`. The stream's `cursor` and the history's `page_token` are
+different tokens and are never exchanged for one another. If the history cannot be read, the
+stream reconnects anyway and the server replays from the cursor; the reason is kept in
+`stream.last_backfill_error`. Pass `backfill_on_reconnect=False` to switch this off.
+
+### From blocking code
+
+```python
+from euclid import BlockingAccountStream, EuclidClient
+
+with EuclidClient(api_key, base_url="https://<your-euclid-host>") as client:
+    with BlockingAccountStream(client) as events:
+        events.wait_until_connected(timeout=10)
+        order = client.place_order(...)
+        for event in events.drain():  # what has arrived so far; never waits
+            ...
+        event = events.get(timeout=5)  # wait for one; None if none came
+        for event in events:  # or block until each arrives
+            ...
+```
+
+`BlockingAccountStream` is an `AccountStream` running on a background thread, with its own
+connection built from the client's key and URLs. It takes the same options (`cursor`,
+`max_reconnect_attempts`, ...), delivers the same events, and reconnects and catches up the
+same way. Events wait in memory until you read them. If the stream fails for good, the next
+read raises the error it failed with. Call `wait_until_connected` before doing something whose
+result you want to see: a stream started without a cursor delivers what happens after it
+connects.
+
+### Reconnecting
+
+All streams reconnect by themselves. The wait starts at half a second and doubles up to 30
+seconds, with random jitter, and starts over once a connection works; pass `backoff=Backoff(...)`
+to change it. A refused connection that names a `Retry-After` waits at least that long. By
+default a stream retries for ever; `max_reconnect_attempts=n` makes it raise `StreamError` after
+`n` failures in a row. Failures that retrying cannot fix are raised straight away:
+`SubscriptionError` for an unknown symbol or a rejected subscription, `AuthenticationError` or
+`InsufficientScopeError` when a ticket is refused.
+
+After a reconnect:
+
+- a market-data subscription subscribes again, and `trades` first fetches the trades it missed
+  over REST and yields them in order;
+- a `LocalOrderBook` rebuilds from a snapshot;
+- an `AccountStream` first yields what it missed from the HTTP history, then gets a new ticket
+  and resumes after the last cursor it received, dropping any transaction it has already
+  delivered (by `transaction_hash`).
+
+### What the streams do not guarantee
+
+The server describes its WebSockets as best-effort, and so is this layer.
+
+- **The stream alone is not a durable record.** A process that restarts has to catch up itself:
+  save `event.engine_seq` as you process events and, on start, walk
+  `list_account_transactions(after_engine_seq=saved)` before or alongside the stream.
+- **The history the backfill reads can itself be behind.** It comes from the account indexer,
+  which trails the engine by a moment; `stream.last_backfill_freshness` says by how much. A
+  transaction too new for the indexer arrives later, over the socket or the next backfill.
+- **An account stream started without a cursor can miss events** if it disconnects before the
+  server has told it a position (the server sends one at most 20 seconds after connecting).
+- **Duplicates are dropped within one `AccountStream` object only**, across the last 10,000
+  transactions it saw (`dedupe_window`).
+- **Depth, book-ticker and kline streams are samples.** After a reconnect you get the current
+  state, not what changed in between.
+- **A local order book is only as deep as its last snapshot** (`depth` levels per side, at most
+  5000), and between a gap and the next snapshot it is briefly behind.
+- **Do not act on money from a stream event alone.** Confirm an order's state with `get_order`
+  or `list_open_orders` first.
+- Prices and sizes are converted with the pair's scales as read when the subscription
+  connected. If a pair is reconfigured, close and reopen its subscriptions.
+
+## What is wrapped
+
+| Area | Methods |
+| --- | --- |
+| Reference data | `get_server_time`, `list_pairs`, `list_assets`, `get_exchange_info` |
+| Market data | `get_order_book`, `get_klines`, `get_symbol_stats`, `get_ticker`, `list_public_trades` |
+| Account | `get_account`, `get_balances`, `get_balance`, `get_fee_tier`, `create_account_stream_ticket` |
+| Trading | `place_order`, `cancel_order`, `cancel_all_orders`, `cancel_replace` |
+| Orders and trades | `list_open_orders`, `list_order_history`, `get_order`, `list_my_trades` |
+| Account history | `list_account_transactions`, `get_account_transaction`, `list_deposits`, `list_withdrawals`, `get_withdrawal`, `list_transfers` |
+| Paging | `paginate` walks the items of every page of any method above that returns a `Page`, up to an optional `limit`; `pages` yields the pages themselves |
+| Trading rules | `Pair.round_price`, `Pair.round_size`, `Pair.min_size_at` |
+| Streams (asyncio) | `MarketDataStream`, `LocalOrderBook`, `AccountStream` |
+| Streams (blocking) | `BlockingAccountStream` |
+
+All arguments of the trading, order and history methods are keyword-only. You never pass a user
+id: the SDK reads it once from the account route and reuses it.
+
+Not wrapped yet: making a transfer or a withdrawal, wallet-signed orders, API-key and session
+management (the whole auth service), leaderboards, fee-schedule discovery, the multi-symbol
+ticker and stats lists, and from the account indexer its copies of balances and order holds
+(the engine's `get_balances` and `list_open_orders` are the authority for those), raw fee
+postings, and the public block explorer. The exact list, with a reason per route, is
+`NOT_YET_WRAPPED` in [`src/euclid/_ops.py`](src/euclid/_ops.py); a test fails if the API gains a
+route that is neither wrapped nor on that list.
+
+## How the package is built
+
+```
+specs/                  the five public OpenAPI documents, one per service, pruned (see below)
+scripts/sync_specs.py   refreshes specs/ from the server's public documents
+scripts/build_spec.py   merges them into one document with short schema names
+src/euclid/_generated/  low-level client generated from the merged document (private)
+src/euclid/             the hand-written public API on top of it
+```
+
+**The generated code is checked in.** Installing the package needs no generator and no build
+step, the exact code that ships is visible in review, and a diff of `_generated/` shows what an
+API change does to the client. Nobody edits it by hand.
+
+**The documents in `specs/` are pruned copies, not byte-identical ones.** The server's public
+OpenAPI documents define more schemas than their routes use. Each file here is the server's
+document with those removed: a schema is kept only if a route in the same document reaches it,
+directly or through another schema, or if it is one of the market-data WebSocket messages
+(`WsClientMessage`, `WsServerMessage` and what they reference). Paths, operations, descriptions,
+security schemes and the kept schemas are exactly as the server publishes them. A test fails if
+`specs/` ever holds a schema that is not reachable this way.
+
+Never copy a document into `specs/` by hand. To refresh them, put the server's public documents
+in a directory of their own and run:
+
+```bash
+python scripts/sync_specs.py path/to/public/documents
+pip install -e ".[codegen]"
+python scripts/regenerate.py
+```
+
+`sync_specs.py` uses the same rule as the merge to decide what to keep, needs only the standard
+library, and writes nothing unless every file passes. It refuses a file not named
+`euclid.<service>.v1.openapi.json` for one of the five services, and a document with an
+`internal` path.
+
+`python scripts/regenerate.py --check` exits non-zero if `_generated/` does not match `specs/`;
+the test suite runs the same check when the generator is installed. The generator
+(`openapi-python-client`) and the formatter (`ruff`) are pinned in `pyproject.toml` so the output
+is reproducible.
+
+Runtime dependencies: [`httpx2`](https://github.com/pydantic/httpx2) and `attrs`, which the
+generated client uses for HTTP and models, and
+[`websockets`](https://github.com/python-websockets/websockets) for the streams.
+
+## Development
+
+```bash
+pip install -e ".[test,codegen,typecheck]"
+pytest --cov                          # the tests, with coverage of the hand-written code
+ruff check . && ruff format --check . # lint and formatting
+mypy                                  # types: strict for the package, default for examples and scripts
+python scripts/regenerate.py --check  # the generated client matches specs/
+```
+
+The tests use a mocked HTTP transport and a scripted in-process WebSocket, with an injected
+clock and sleep. They never touch the network and never wait. Coverage of the hand-written code
+must stay at 95% or more; the generated client is left out of that number, because
+`regenerate.py --check` is what guards it.
+
+Every push to `main` and every pull request runs the same commands in
+[GitHub Actions](.github/workflows/ci.yml):
+
+- the tests on Python 3.11, 3.12, 3.13 and 3.14 on Linux, and on macOS;
+- the tests again with the oldest version of each dependency that `pyproject.toml` allows;
+- lint, formatting, types and the generated-client check;
+- a build of the wheel and source archive, a check of what they contain
+  (`scripts/check_distribution.py`), and an install of the wheel into a clean environment.
+
+Windows is not tested.
+
+### Releasing
+
+A release is a git tag. Pushing a tag such as `v0.2.0` runs
+[the release workflow](.github/workflows/release.yml), which checks, builds, publishes to PyPI
+and creates the GitHub release with that version's changelog entry as its notes.
+
+1. On a branch: set the version in `src/euclid/_version.py`, add a `## <version>` section to
+   [`CHANGELOG.md`](CHANGELOG.md), and merge it to `main`.
+   `python scripts/check_release.py` tells you whether the two agree.
+2. Optional rehearsal: run the Release workflow by hand from the Actions tab. That builds the
+   same way and uploads to TestPyPI.
+3. Tag the merged commit and push the tag:
+
+   ```bash
+   git switch main && git pull
+   git tag v0.2.0
+   git push origin v0.2.0
+   ```
+
+The workflow refuses to publish if the tag is not on `main`, if the tag and the version in the
+code differ, if the changelog has no entry for the version, or if the tests or the package
+checks fail. A version on PyPI is permanent: it can be hidden afterwards but never replaced, so
+a mistake is fixed by releasing the next patch version.
+
+Publishing uses PyPI's trusted publishing, so no token is stored in this repository. It needs a
+one-time setup by an owner of the PyPI project: on pypi.org, under the project's publishing
+settings (or "pending publisher" before the first release), add a GitHub publisher with
+
+| Field | Value |
+| --- | --- |
+| Owner | `EuclidProtocol` |
+| Repository | `euclid-python-sdk` |
+| Workflow | `release.yml` |
+| Environment | `pypi` |
+
+and the same on test.pypi.org with the environment `testpypi`. To require a person to approve
+each publish, add required reviewers to the `pypi` environment in this repository's settings.
+
+## Licence
+
+[MIT](LICENSE).