Docs: clarify live vs historical fetchOrderBook for Polymarket archives

[realfishsam]

Bug Description

The Fetch Order Book docs are misleading for Polymarket historical orderbook usage, especially closed/resolved 5m crypto markets.

Docs page: https://www.pmxt.dev/docs/api-reference/fetch-order-book
Source: docs/api-reference/fetch-order-book.mdx

What is wrong / confusing

1. The docs show a live fetch_order_book(token_id) example, but users trying this on a valid resolved market token get Polymarket's live CLOB error:

   {"error":"No orderbook exists for the requested token id"}

   This happens because no since/until historical params are passed, so the SDK hits the live orderbook path, not the archive path.

2. The docs recommend discovering the example historical market with:

   market = poly.fetch_market(slug="...")

   For 5m crypto slugs such as btc-updown-5m-1779481500, Polymarket exposes the slug via Gamma /events?slug=...; /markets?slug=... returns []. Users need to use fetch_event(slug=...) and then the nested market, or pass the conditionId/token id directly with historical params.

3. The generated top snippet on the page includes placeholder/misleading params:

   outcome="value",
   since=1,
   until=1,

   and the page labels the endpoint as GET, while SDK historical examples use POST body args.

4. The docs do not clearly distinguish:

   • live CLOB orderbook: fetch_order_book(outcome_token_id)
   • historical archive lookup: fetch_order_book(market_or_condition_id, params={"since": ..., "until": ..., "outcome": ...})

Repro

import pmxt

poly = pmxt.Polymarket(pmxt_api_key="pmxt_...")
book = poly.fetch_order_book("23523572091470643364331891196535905541939125250184703417699687648361933766651")
print(book)

This token id is valid for the closed event slug btc-updown-5m-1779481500, but the live orderbook no longer exists.

Polymarket Gamma behavior:

GET https://gamma-api.polymarket.com/markets?slug=btc-updown-5m-1779481500 -> []
GET https://gamma-api.polymarket.com/events?slug=btc-updown-5m-1779481500 -> event with nested market

Relevant conditionId:

0xc704f74e2f9dfae70f770cb253ffadde10768eeab41233098bf5ac67995a94b5

Expected Behavior

Update the docs so users can correctly bulk/query historical per-second orderbook snapshots:

• Make clear that no-params fetch_order_book(token_id) is live-only and may fail for closed/resolved markets.
• Show the correct historical snapshot/range calls using since/until.
• For Polymarket 5m crypto slugs, use fetch_event(slug=...) or conditionId-based examples instead of fetch_market(slug=...).
• Replace bogus placeholder params (outcome="value", since=1, until=1) with realistic examples or hide them from the generated snippet.
• Add a note that historical data is archive-backed and keyed by Polymarket conditionId + outcome asset id/token id.

Suggested Fix

Patch docs/api-reference/fetch-order-book.mdx with:

• a "Live vs historical" warning/callout
• a Polymarket 5m crypto example using fetch_event(slug=...)
• a conditionId/direct-token example for archive queries
• corrected curl syntax with closed quotes