Skip to content

fix: tighten server manager exception handling #871

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
realfishsam wants to merge 6 commits into
base: main
Choose a base branch
from
Open

fix: tighten server manager exception handling #871

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
46c3c1f
docs: clarify historical fetch order book usage
realfishsam Jun 2, 2026
f5aebf2
docs: sync generated API docs
realfishsam Jun 2, 2026
b18710a
fix: tighten server manager exception handling
realfishsam Jun 5, 2026
66db719
chore: sync generated outputs
realfishsam Jun 5, 2026
a052ed9
docs: sync generated Mintlify docs
realfishsam Jun 5, 2026
a34ea57
docs: sync generated docs after core build
realfishsam Jun 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 18 additions & 18 deletions core/api-doc-config.generated.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"_generated": "Auto-generated by extract-jsdoc.js on 2026-06-02T00:34:44.916Z. Do not edit manually.",
"_generated": "Auto-generated by extract-jsdoc.js on 2026-06-05T14:28:27.808Z. Do not edit manually.",
"methods": {
"has": {
"summary": "HTTP verb for the endpoint (e.g. GET, POST). */",
Expand Down Expand Up @@ -566,7 +566,7 @@
"type": "UnifiedEvent[]",
"description": "Filtered array of events"
},
"source": "BaseExchange.ts:1317"
"source": "BaseExchange.ts:1318"
},
"watchOrderBook": {
"summary": "Watch order book updates in real-time via WebSocket.",
Expand Down Expand Up @@ -595,7 +595,7 @@
"type": "OrderBook",
"description": "Promise that resolves with the current orderbook state"
},
"source": "BaseExchange.ts:1413"
"source": "BaseExchange.ts:1414"
},
"watchOrderBooks": {
"summary": "Watch multiple order books simultaneously via WebSocket.",
Expand Down Expand Up @@ -624,7 +624,7 @@
"type": "Record<string, OrderBook>",
"description": "Promise that resolves with order books keyed by ID"
},
"source": "BaseExchange.ts:1426"
"source": "BaseExchange.ts:1427"
},
"unwatchOrderBook": {
"summary": "Unsubscribe from a previously watched order book stream.",
Expand All @@ -641,7 +641,7 @@
"type": "void",
"description": "Result"
},
"source": "BaseExchange.ts:1454"
"source": "BaseExchange.ts:1455"
},
"watchTrades": {
"summary": "Watch trade executions in real-time via WebSocket.",
Expand Down Expand Up @@ -676,7 +676,7 @@
"type": "Trade[]",
"description": "Promise that resolves with recent trades"
},
"source": "BaseExchange.ts:1467"
"source": "BaseExchange.ts:1468"
},
"watchAddress": {
"summary": "Stream activity for a public wallet address",
Expand All @@ -699,7 +699,7 @@
"type": "SubscribedAddressSnapshot",
"description": "Promise that resolves with the latest SubscribedAddressSnapshot snapshot"
},
"source": "BaseExchange.ts:1481"
"source": "BaseExchange.ts:1482"
},
"unwatchAddress": {
"summary": "Stop watching a previously registered wallet address and release its resource updates.",
Expand All @@ -716,7 +716,7 @@
"type": "void",
"description": "Result"
},
"source": "BaseExchange.ts:1494"
"source": "BaseExchange.ts:1495"
},
"close": {
"summary": "Close all WebSocket connections and clean up resources.",
Expand All @@ -726,7 +726,7 @@
"type": "void",
"description": "Result"
},
"source": "BaseExchange.ts:1503"
"source": "BaseExchange.ts:1504"
},
"fetchMarketMatches": {
"summary": "Find the same or related market on other venues. Two modes:",
Expand All @@ -743,7 +743,7 @@
"type": "MatchResult[]",
"description": "Array of matched markets with relation and confidence"
},
"source": "BaseExchange.ts:1517"
"source": "BaseExchange.ts:1518"
},
"fetchMatches": {
"summary": "fetchMatches",
Expand All @@ -760,7 +760,7 @@
"type": "MatchResult[]",
"description": "Result"
},
"source": "BaseExchange.ts:1533"
"source": "BaseExchange.ts:1534"
},
"fetchEventMatches": {
"summary": "Find the same or related event on other venues. Two modes:",
Expand All @@ -777,7 +777,7 @@
"type": "EventMatchResult[]",
"description": "Array of matched events with market-level match details"
},
"source": "BaseExchange.ts:1541"
"source": "BaseExchange.ts:1542"
},
"compareMarketPrices": {
"summary": "Compare live prices for the same market across venues. Finds identity matches and returns side-by-side best bid/ask prices so you can spot price differences at a glance.",
Expand All @@ -794,7 +794,7 @@
"type": "PriceComparison[]",
"description": "Array of price comparisons across venues"
},
"source": "BaseExchange.ts:1557"
"source": "BaseExchange.ts:1558"
},
"fetchRelatedMarkets": {
"summary": "Find related markets across venues. Discovers subset/superset market relationships",
Expand All @@ -811,7 +811,7 @@
"type": "PriceComparison[]",
"description": "Array of subset/superset matches with live prices"
},
"source": "BaseExchange.ts:1567"
"source": "BaseExchange.ts:1568"
},
"fetchMatchedMarkets": {
"summary": "fetchMatchedMarkets",
Expand All @@ -828,7 +828,7 @@
"type": "MatchedMarketPair[]",
"description": "Result"
},
"source": "BaseExchange.ts:1578"
"source": "BaseExchange.ts:1579"
},
"fetchMatchedPrices": {
"summary": "fetchMatchedPrices",
Expand All @@ -845,7 +845,7 @@
"type": "MatchedPricePair[]",
"description": "Array of matched market pairs with prices from each venue"
},
"source": "BaseExchange.ts:1586"
"source": "BaseExchange.ts:1587"
},
"fetchHedges": {
"summary": "fetchHedges",
Expand All @@ -862,7 +862,7 @@
"type": "PriceComparison[]",
"description": "Array of subset/superset matches with live prices"
},
"source": "BaseExchange.ts:1597"
"source": "BaseExchange.ts:1598"
},
"fetchArbitrage": {
"summary": "fetchArbitrage",
Expand All @@ -879,7 +879,7 @@
"type": "ArbitrageOpportunity[]",
"description": "Array of arbitrage opportunities sorted by spread"
},
"source": "BaseExchange.ts:1607"
"source": "BaseExchange.ts:1608"
},
"watchPrices": {
"summary": "Watch AMM price updates for a market address (Limitless only).",
Expand Down
95 changes: 66 additions & 29 deletions docs/api-reference/fetch-order-book.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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"},
)

Expand All @@ -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" }
);
Expand All @@ -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")
Expand All @@ -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) =>
Expand All @@ -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>
Loading
Loading