chore: merge main and refresh generated docs

Author: realfishsam

core/api-doc-config.generated.json

@@ -1,5 +1,5 @@
 {
-    "_generated": "Auto-generated by extract-jsdoc.js on 2026-06-08T07:59:06.055Z. Do not edit manually.",
+    "_generated": "Auto-generated by extract-jsdoc.js on 2026-06-08T08:01:55.819Z. Do not edit manually.",
     "methods": {
         "has": {
             "summary": "HTTP verb for the endpoint (e.g. GET, POST). */",

docs/api-reference/fetch-order-book.mdx

@@ -7,7 +7,11 @@ openapi: GET /api/{exchange}/fetchOrderBook
 
 ### Live order book
 
-Fetch the current L2 order book for an outcome. If you already have an outcome token ID, pass it directly:
+Fetch the current L2 order book for an outcome from the exchange's live order book endpoint. For Polymarket this is a live CLOB call: pass the outcome token ID directly and omit historical params.
+
+<Warning>
+`poly.fetch_order_book(token_id)` without `params.since` or `params.until` is live-only. It does not read PMXT Archive data and may fail for closed, resolved, or otherwise inactive Polymarket markets with an error such as `No orderbook exists`.
+</Warning>
 
 <CodeGroup>
 ```python Python
@@ -28,28 +32,25 @@ console.log(`${book.bids.length} bids, ${book.asks.length} asks`);
 
 ```bash curl
 curl "https://api.pmxt.dev/api/polymarket/fetchOrderBook?outcomeId=104932610032177696635191871147557737718087870958469629338467406422339967452218" \
-  -H "Authorization: Bearer $PMXT_API_KEY"
+  -H "Authorization: Bearer ***"
 ```
 </CodeGroup>
 
 ### Historical snapshot
 
-Get the order book at a specific point in time. Pass `since` as a Unix timestamp in milliseconds — returns the nearest snapshot at or before that time.
+Get the order book at a specific point in time by passing `since` as a Unix timestamp in milliseconds. Historical Polymarket queries are served from the PMXT Archive and return the nearest reconstructed snapshot at or before that time.
 
-For binary markets, you can pass the market ID and choose the side with `params.outcome`. Use `"yes"` or `"no"` instead of copying the long outcome token ID:
+For binary markets, you can pass the Polymarket condition ID as the first argument and choose the side with `params.outcome`. Use `"yes"` or `"no"` instead of copying the long outcome token ID.
 
 <CodeGroup>
 ```python Python
 import pmxt
 
 poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")
 
-market = poly.fetch_market(
-    slug="will-spacex-starship-flight-test-12-launch-by-may-22-354-721"
-)
-
+# Historical lookup against PMXT Archive, not the live CLOB.
 book = poly.fetch_order_book(
-    market.market_id,
+    "0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5",
     params={"since": 1779487200000, "outcome": "yes"},
 )
 
@@ -63,12 +64,9 @@ import { Polymarket } from "pmxtjs";
 
 const poly = new Polymarket({ pmxtApiKey: "pmxt_..." });
 
-const market = await poly.fetchMarket({
-  slug: "will-spacex-starship-flight-test-12-launch-by-may-22-354-721",
-});
-
+// Historical lookup against PMXT Archive, not the live CLOB.
 const book = await poly.fetchOrderBook(
-  market.marketId,
+  "0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5",
   undefined,
   { since: 1779487200000, outcome: "yes" }
 );
@@ -79,34 +77,75 @@ console.log(`  best ask: ${Math.min(...book.asks.map((a) => a.price)).toFixed(3)
 
 ```bash curl
 curl -X POST "https://api.pmxt.dev/api/polymarket/fetchOrderBook" \
-  -H "Authorization: Bearer $PMXT_API_KEY" \
+  -H "Authorization: Bearer ***" \
+  -H "Content-Type: application/json" \
+  -d '{"args":["0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5", null, {"since": 1779487200000, "outcome": "yes"}]}'
+```
+</CodeGroup>
+
+### Historical crypto 5m events
+
+Polymarket crypto 5-minute slugs such as `btc-updown-5m-1779481500` are event slugs. Use `fetch_event(slug=...)`, then select the nested market you want. Do not use `fetch_market(slug=...)` for these event-level slugs.
+
+<CodeGroup>
+```python Python
+import pmxt
+
+poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")
+event = poly.fetch_event(slug="btc-updown-5m-1779481500")
+market = event.markets[0]
+
+book = poly.fetch_order_book(
+    market.market_id,
+    params={"since": 1779487200000, "outcome": "yes"},
+)
+print(f"{market.title}: {book.dt}")
+```
+
+```javascript JavaScript
+import { Polymarket } from "pmxtjs";
+
+const poly = new Polymarket({ pmxtApiKey: "pmxt_..." });
+const event = await poly.fetchEvent({ slug: "btc-updown-5m-1779481500" });
+const market = event.markets[0];
+
+const book = await poly.fetchOrderBook(
+  market.marketId,
+  undefined,
+  { since: 1779487200000, outcome: "yes" }
+);
+console.log(`${market.title}: ${book.datetime}`);
+```
+
+```bash curl
+curl -X POST "https://api.pmxt.dev/api/polymarket/fetchEvent" \
+  -H "Authorization: Bearer ***" \
   -H "Content-Type: application/json" \
-  -d '{"args":["61b0ed20-7f42-41fd-af15-7b86153f6bb7", null, {"since": 1779487200000, "outcome": "yes"}]}'
+  -d '{"kwargs":{"slug":"btc-updown-5m-1779481500"}}'
 ```
 </CodeGroup>
 
 ### Historical range (reconstructed L2 books)
 
 Pass both `since` and `until` to get an array of fully reconstructed L2 order book snapshots. Each snapshot is a complete book at that moment in time — not deltas.
 
-Default 100 snapshots per request, max 1000.
+The API returns up to `limit` snapshots from the PMXT Archive. Defaults to 100 snapshots per request, max 1000. For raw bulk downloads, use the Parquet files in the [PMXT Archive](https://archive.pmxt.dev) instead of trying to stream bulk data through the live order book endpoint.
 
 <CodeGroup>
 ```python Python
 import pmxt
 
 poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")
-
-market = poly.fetch_market(
-    slug="will-spacex-starship-flight-test-12-launch-by-may-22-354-721"
-)
+event = poly.fetch_event(slug="btc-updown-5m-1779481500")
+market = event.markets[0]
 
 books = poly.fetch_order_book(
     market.market_id,
     params={
         "since": 1779480000000,
         "until": 1779487200000,
         "outcome": "yes",
+        "limit": 100,
     }
 )
 print(f"{len(books)} snapshots")
@@ -118,15 +157,13 @@ for ob in books[:3]:
 import { Polymarket } from "pmxtjs";
 
 const poly = new Polymarket({ pmxtApiKey: "pmxt_..." });
-
-const market = await poly.fetchMarket({
-  slug: "will-spacex-starship-flight-test-12-launch-by-may-22-354-721",
-});
+const event = await poly.fetchEvent({ slug: "btc-updown-5m-1779481500" });
+const market = event.markets[0];
 
 const books = await poly.fetchOrderBook(
   market.marketId,
   undefined,
-  { since: 1779480000000, until: 1779487200000, outcome: "yes" }
+  { since: 1779480000000, until: 1779487200000, outcome: "yes", limit: 100 }
 );
 console.log(`${books.length} snapshots`);
 books.slice(0, 3).forEach((ob) =>
@@ -136,12 +173,12 @@ books.slice(0, 3).forEach((ob) =>
 
 ```bash curl
 curl -X POST "https://api.pmxt.dev/api/polymarket/fetchOrderBook" \
-  -H "Authorization: Bearer $PMXT_API_KEY" \
+  -H "Authorization: Bearer ***" \
   -H "Content-Type: application/json" \
-  -d '{"args":["61b0ed20-7f42-41fd-af15-7b86153f6bb7", null, {"since": 1779480000000, "until": 1779487200000, "outcome": "yes"}]}'
+  -d '{"args":["0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5", null, {"since": 1779480000000, "until": 1779487200000, "outcome": "yes", "limit": 100}]}'
 ```
 </CodeGroup>
 
 <Info>
-Historical order book data is backed by the [PMXT Archive](https://archive.pmxt.dev) — the same tick-level data available as Parquet files, but queryable directly from the API without downloading or parsing files. Supports Polymarket, Kalshi, Limitless, and Opinion.
+Historical order book data is backed by the [PMXT Archive](https://archive.pmxt.dev) — the same tick-level data available as Parquet files, but queryable directly from the API without downloading or parsing files. Historical `fetchOrderBook` supports Polymarket, Kalshi, Limitless, and Opinion.
 </Info>