TypeScript SDK Reference

The TypeScript client is auto-generated from the OpenAPI spec and published as @predictorsdk/client on npm. It needs Node 18 or later and works with both import and require: the package ships an ES module build and a CommonJS build, each with its own types.

// CommonJS
const { PredictorSDKClient } = require("@predictorsdk/client");

An app that loads the package both ways gets two copies of it, so an error thrown by one is not an instanceof the other's PredictorSDKError; use one style.

Client surfaces

When you await a call to one of the other surfaces, it resolves to the parsed response body. Use .withRawResponse() if you also need headers or status metadata.

Four surfaces are paginated with a cursor: getSportsMatchingMarkets, getMarkets, getBinanceCryptoPrices and listPolymarketWalletPositions. Each resolves to a Page that walks the cursor for you; see Pagination.

Usage

import { PredictorSDKClient } from "@predictorsdk/client";

const client = new PredictorSDKClient({
  token: "YOUR_API_KEY",
});

// A paginated call answers a page: page.data holds this page's events.
const page = await client.getSportsMatchingMarkets({ league: "nfl" });
for (const event of page.data) {
  console.log(event.eventId, event.scheduledDate, event.scheduledStart, event.title);
}

// A lookup finds events by identifier and answers one unpaginated response.
const found = await client.lookupSportsMatchingMarkets({
  sourceId: "kalshi:KXNBAGAME-26OCT20OKCSAS",
});

const categories = await client.getCategories();
const plans = await client.getPlans(); // Public; no API key is sent.

Pagination

A call to getSportsMatchingMarkets, getMarkets, getBinanceCryptoPrices or listPolymarketWalletPositions resolves to a Page. Iterate it with for await to visit every item on every page; the client sends each next cursor and repeats the filters that issued it.

// Every event on every page.
const page = await client.getSportsMatchingMarkets({ league: "nfl", limit: 50 });
for await (const event of page) {
  console.log(event.eventId, event.title);
}

// One provider's markets, a page at a time. The whole catalog is about
// 470,000 markets, thousands of pages, so filter by provider or category first.
const markets = await client.getMarkets({ provider: "prophetx", limit: 100 });
while (true) {
  console.log(markets.data.length, markets.response.pagination.total);
  if (!markets.hasNextPage()) break;
  await markets.getNextPage(); // advances `markets` in place
}

Iterating or calling getNextPage() moves the same Page forward, so read page.response first if you need the first page's pagination or snapshot. pagination.total is a number on getMarkets and getSportsMatchingMarkets, and null on getBinanceCryptoPrices and listPolymarketWalletPositions, whose upstreams cannot count; follow hasNextPage() rather than total. See the Pagination guide for the cursor rules.

Configuration

Key types

SportsMatchingListResponse

The page.response of getSportsMatchingMarkets. Contains the matched events in data, the pagination block, and a snapshot freshness block.

SportsMatchingLookupResponse

The response from lookupSportsMatchingMarkets: one unpaginated response, with no pagination block.

SportsMatchingLookupResult

CanonicalSportsEvent

One matched game, as the list and the lookup both return it.

PaginationBlock

CanonicalSportsSourceMarket

One venue market matched to a canonical submarket, with the same fields on every venue. eventId is the venue's parent event, for getEvent; marketId is the market itself, for getMarket. Pass provider to either call as its provider, or use the composite provider + ":" + id. Any of eventId, marketId or marketSlug, prefixed with provider, finds the event again as sourceId. See Which identifier goes where.

GetSportsMatchingMarketsRequest

Pass an empty object {} (or nothing) to list every matched event. The filters narrow the list, and total, hasMore and the cursors describe the filtered set.

// Tonight's NFL games: filters compose, and every page keeps them.
const page = await client.getSportsMatchingMarkets({
  league: "nfl",
  scheduledDate: "2026-10-15",
});
for await (const event of page) {
  console.log(event.eventId, event.scheduledStart);
}

LookupSportsMatchingMarketsRequest

Send at least one identifier; with both parameters, at most 100 unique values in all.

// `lookups` reports what each identifier found; there is no pagination block.
const response = await client.lookupSportsMatchingMarkets({
  sourceId: ["kalshi:KXNBAGAME-26OCT20OKCSAS", "sxbet:L19766755"],
});
for (const [id, found] of Object.entries(response.lookups)) {
  console.log(id, found.eventIds);
}

MarketsListResponse

The page.response of getMarkets. Contains data, catalog snapshot freshness, and pagination.

UnifiedMarket

A market from any supported prediction market provider.

GetMarketsRequest

GetMarketRequest and GetEventRequest

getMarket takes a marketId and getEvent an eventId, either as a platform-native ID or the composite {provider}:{id}. Both take an optional provider (GetMarketRequestProvider and GetEventRequestProvider) to say which venue an ID belongs to. A bare ID that more than one venue holds answers 409 with the candidates; retry with provider set to one of them, or with the composite form. The retired platform is not accepted.

const market = await client.getMarket({
  marketId: "KXNBAGAME-26OCT20OKCSAS-OKC",
  provider: "kalshi",
});
const event = await client.getEvent({ eventId: "KXNBAGAME-26OCT20OKCSAS", provider: "kalshi" });
console.log(event.provider); // "kalshi": pass it back as `provider` for the nested markets

EventResponse

The response from getEvent.

GetBinanceCryptoPricesRequest

CryptoPricesResponse

The page.response of getBinanceCryptoPrices: newest prices first, one per second.

Raw responses

Use .withRawResponse() on a surface that is not paginated to access HTTP metadata alongside the parsed body:

const raw = await client
  .lookupSportsMatchingMarkets({ sourceId: "kalshi:KXNBAGAME-26OCT20OKCSAS" })
  .withRawResponse();
console.log(raw.rawResponse.status);
console.log(raw.rawResponse.headers.get("X-RateLimit-Reset")); // Unix seconds
console.log(raw.data.data.length);

A paginated surface keeps the metadata on its page:

const page = await client.getSportsMatchingMarkets();
console.log(page.rawResponse.status);
console.log(page.rawResponse.headers.get("X-RateLimit-Reset")); // Unix seconds

Error handling

The SDK throws typed errors for known HTTP error codes:

The client retries a 408, 429 or 5xx response twice by default (maxRetries, on the client or per request). A 429 waits for Retry-After, or else until the second-based X-RateLimit-Reset. Any other retried status honours Retry-After and otherwise backs off exponentially from one second. No wait exceeds 60 seconds, and an abortSignal ends a wait as soon as it aborts; timeoutInSeconds limits each attempt. A 409 is never retried: send the request again with a provider from its candidates.

A request that gets no response because the connection was refused, reset or closed by the server (Node reports ECONNREFUSED, ECONNRESET or UND_ERR_SOCKET on the error's cause) is retried the same way, with the same backoff and the same limit. A timeout and an abort are never retried. Every call is a read, so repeating one is safe. The Go and Python SDKs follow the same policy, and error.requestId is the response's request id.

import { PredictorSDK, PredictorSDKClient } from "@predictorsdk/client";

const client = new PredictorSDKClient({
  token: "YOUR_API_KEY",
});

try {
  // A venue ID needs its provider prefix: "kalshi:KXNBAGAME-26OCT20OKCSAS".
  await client.lookupSportsMatchingMarkets({ sourceId: "KXNBAGAME-26OCT20OKCSAS" });
} catch (error) {
  if (error instanceof PredictorSDK.BadRequestError) {
    console.log("Bad request:", error.body.code, error.body.message);
  }
}