From 9e7c8f05a1c3f6f242576fb31f8b570569136336 Mon Sep 17 00:00:00 2001
From: Manuel Polo <mistermx@gmail.com>
Date: Mon, 25 May 2026 20:53:58 +0000
Subject: [PATCH] docs(auth): add API key -> JWT snippet and SDK cross-link

Generator regen does not touch the README. Add a short usage snippet showing
how to call `auth.sync()` with an AuthenticatedClient configured to send
X-API-Key, document the QTSURFER_APIKEY env-var convention, and point
production callers at the sibling SDK for token-refresh handling.

Part of openapi-auth-rollout Phase 2 (#168).
---
 README.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/README.md b/README.md
index 7106441..cc82694 100644
--- a/README.md
+++ b/README.md
@@ -57,6 +57,35 @@ instruments = get_instruments.sync(client=client, exchange_id="binance")
 print(f"{len(instruments or [])} instruments on binance")
 ```
 
+### API key → JWT
+
+Every endpoint above expects a short-lived JWT in the `Authorization: Bearer …`
+header. Exchange a long-lived API key for one via `auth`:
+
+```python
+import os
+
+from qtsurfer.api.client import AuthenticatedClient
+from qtsurfer.api.client.api.auth import auth
+
+# AuthenticatedClient also drives the apikey header — set prefix="" so it
+# sends `X-API-Key: <key>` instead of `Authorization: Bearer <key>`.
+apikey_client = AuthenticatedClient(
+    base_url="https://api.qtsurfer.com/v1",
+    token=os.environ["QTSURFER_APIKEY"],
+    prefix="",
+    auth_header_name="X-API-Key",
+)
+
+token_response = auth.sync(client=apikey_client)
+jwt = token_response.access_token  # use this in subsequent calls
+```
+
+For production use, prefer the [`qtsurfer-sdk`](https://github.com/QTSurfer/sdk-python)
+`auth(apikey)` helper — it handles token refresh, env-var pickup
+(`QTSURFER_APIKEY`), and pluggable token storage so callers don't reinvent any
+of it on top of the raw client.
+
 Each generated endpoint module exposes four entrypoints:
 
 | Function | Returns |