@predimarkets/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Predimarkets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# @predimarkets/sdk
+
+Official TypeScript client for the [Predimarkets](https://predimarkets.com) API — matching, oracle resolution and settlement for prediction markets.
+
+Zero runtime dependencies. Runs on Node 18+, Bun, Deno and Cloudflare Workers.
+
+```bash
+npm install @predimarkets/sdk
+```
+
+## Quick start
+
+```ts
+import { Predimarkets } from '@predimarkets/sdk';
+
+const client = new Predimarkets({ apiKey: process.env.PREDIMARKETS_API_KEY! });
+
+const { markets } = await client.markets.list({ status: 'open' });
+const market = markets[0];
+
+// Price the bet before you place it.
+const quote = await client.parimutuel.quote({
+  marketId: market.id,
+  outcomeId: market.outcomes[0].id,
+  stake: 100,
+});
+
+// Place it.
+const order = await client.orders.create({
+  marketId: market.id,
+  outcomeId: market.outcomes[0].id,
+  userId: 'your-user-123',
+  amount: 100,
+});
+```
+
+Your API key authenticates you as the partner; `userId` is **your** id for the end
+user placing the bet. Keep the key server-side — it must never reach a browser.
+
+## Markets
+
+```ts
+await client.markets.list({ status: 'open', limit: 20 });
+await client.markets.get('will-france-win-the-world-cup-2026'); // id or slug
+await client.markets.priceHistory(market.id, { timeframe: '1D' });
+await client.markets.orderBook(market.id);
+```
+
+Search is semantic, not just keyword — queries are ranked by embedding similarity
+fused with full-text, so a question finds the market that answers it even when
+they share no words:
+
+```ts
+await client.markets.search('who wants to be president');
+```
+
+## Orders
+
+Parimutuel markets take an `amount` — the money the user is staking, debited and
+staked 1:1, with no share price to reason about:
+
+```ts
+await client.orders.create({
+  marketId, outcomeId, userId: 'user-123', amount: 100,
+});
+```
+
+Order-book markets take a `quantity`, plus a `price` for limit orders:
+
+```ts
+await client.orders.create({
+  marketId, outcomeId, userId: 'user-123',
+  side: 'buy', type: 'limit', quantity: 1000, price: 0.65,
+});
+```
+
+## Positions and trades
+
+```ts
+await client.positions.list({ userId: 'user-123' });
+await client.trades.list({ userId: 'user-123', limit: 50 });
+```
+
+## Multi-outcome markets
+
+```ts
+const state = await client.parimutuel.categorical.state(marketId);
+await client.parimutuel.categorical.quote({ marketId, outcomeId, stake: 50 });
+```
+
+An outcome that is out of the running (knocked out, lost) comes back with
+`eliminated: true` and takes no new bets — the API rejects them with
+`OUTCOME_ELIMINATED`. Render it as dead rather than hiding it: its share of the
+pool is real, so the remaining outcomes' percentages will not add to 100 without
+it.
+
+## Webhooks
+
+Predimarkets signs every webhook with HMAC-SHA256 over the raw body, in the
+`x-predimarkets-signature` header.
+
+```ts
+import { Predimarkets, SIGNATURE_HEADER } from '@predimarkets/sdk';
+
+app.post('/webhooks/predimarkets', express.raw({ type: 'application/json' }), async (req, res) => {
+  const event = await client.webhooks.constructEvent({
+    payload: req.body.toString('utf8'),      // the RAW bytes, not the parsed JSON
+    signature: req.headers[SIGNATURE_HEADER],
+    secret: process.env.PREDIMARKETS_WEBHOOK_SECRET!,
+  });
+
+  // constructEvent throws if the signature is wrong, so you cannot forget to check.
+  switch (event.event_type) {
+    case 'market.resolved':   /* pay your users */ break;
+    case 'positions.refund':  /* credit the refund */ break;
+  }
+  res.sendStatus(200);
+});
+```
+
+Pass the **raw** body. Re-serialising parsed JSON changes a byte somewhere (key
+order, whitespace) and the signature will not match. The comparison is constant
+time, so it does not leak the secret to anyone timing your responses.
+
+## Errors
+
+Every non-2xx response throws a `PredimarketsError`. Branch on `code`, never on
+the message:
+
+```ts
+import { PredimarketsError } from '@predimarkets/sdk';
+
+try {
+  await client.orders.create({ /* … */ });
+} catch (err) {
+  if (err instanceof PredimarketsError) {
+    if (err.code === 'INSUFFICIENT_BALANCE') return topUp();
+    if (err.code === 'OUTCOME_ELIMINATED')   return refreshMarket();
+    console.error(err.code, err.message, err.failureReason);
+  }
+  throw err;
+}
+```
+
+## Anything not wrapped yet
+
+`client.request()` reaches any endpoint directly, with auth, timeouts and error
+handling already applied:
+
+```ts
+await client.request('GET', '/markets/:id/milestone-live'.replace(':id', marketId));
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,340 @@
+"use strict";
+/**
+ * @predimarkets/sdk — the official client for the Predimarkets API.
+ *
+ * Zero runtime dependencies: it uses the platform `fetch`, so it runs on Node 18+,
+ * Bun, Deno, Cloudflare Workers and the browser (server-side only — an API key
+ * must never reach a browser).
+ *
+ * The API speaks snake_case. This SDK speaks camelCase and translates at the
+ * boundary, so integrators write idiomatic TypeScript and never hand-build a
+ * query string.
+ *
+ *   const client = new Predimarkets({ apiKey: process.env.PREDIMARKETS_API_KEY! });
+ *   const { markets } = await client.markets.list({ status: 'open' });
+ *   await client.orders.create({
+ *     marketId: markets[0].id,
+ *     outcomeId: markets[0].outcomes[0].id,
+ *     userId: 'your-user-123',
+ *     side: 'buy',
+ *     amount: 100,
+ *   });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Webhooks = exports.SIGNATURE_HEADER = exports.Predimarkets = exports.PredimarketsError = exports.VERSION = void 0;
+exports.VERSION = '0.1.0';
+const DEFAULT_BASE_URL = 'https://api.predimarkets.com';
+const DEFAULT_TIMEOUT_MS = 30_000;
+// ─────────────────────────────────────────────────────────────────────────────
+// Errors
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Any non-2xx response from the API.
+ *
+ * `code` is the machine-readable code the API returns (INSUFFICIENT_BALANCE,
+ * MARKET_PAUSED, OUTCOME_ELIMINATED, …) — branch on that, never on the message.
+ */
+class PredimarketsError extends Error {
+    status;
+    code;
+    /** The API's own explanation of why the request failed, when it gives one. */
+    failureReason;
+    body;
+    constructor(args) {
+        super(args.message);
+        this.name = 'PredimarketsError';
+        this.status = args.status;
+        this.code = args.code;
+        this.failureReason = args.failureReason;
+        this.body = args.body;
+    }
+}
+exports.PredimarketsError = PredimarketsError;
+// ─────────────────────────────────────────────────────────────────────────────
+// Client
+// ─────────────────────────────────────────────────────────────────────────────
+class Predimarkets {
+    markets;
+    orders;
+    positions;
+    trades;
+    parimutuel;
+    webhooks;
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    constructor(options) {
+        if (!options?.apiKey) {
+            throw new Error('Predimarkets: apiKey is required');
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f) {
+            throw new Error('Predimarkets: no fetch available. Use Node 18+, or pass { fetch } explicitly.');
+        }
+        this.fetchImpl = f;
+        this.markets = new Markets(this);
+        this.orders = new Orders(this);
+        this.positions = new Positions(this);
+        this.trades = new Trades(this);
+        this.parimutuel = new Parimutuel(this);
+        this.webhooks = new Webhooks();
+    }
+    /** Escape hatch: call any endpoint the SDK doesn't wrap yet. */
+    async request(method, path, options = {}) {
+        const url = new URL(`${this.baseUrl}/v1${path.startsWith('/') ? path : `/${path}`}`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined && value !== null)
+                url.searchParams.set(key, String(value));
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(url.toString(), {
+                method,
+                signal: controller.signal,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                    'User-Agent': `predimarkets-sdk/${exports.VERSION}`,
+                },
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            });
+        }
+        catch (err) {
+            const aborted = err instanceof Error && err.name === 'AbortError';
+            throw new PredimarketsError({
+                message: aborted
+                    ? `Request timed out after ${this.timeoutMs}ms`
+                    : `Network error calling Predimarkets: ${err?.message ?? err}`,
+                status: 0,
+                code: aborted ? 'TIMEOUT' : 'NETWORK_ERROR',
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await response.text();
+        let body = undefined;
+        try {
+            body = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            body = text;
+        }
+        if (!response.ok) {
+            const error = body?.error ?? {};
+            throw new PredimarketsError({
+                message: error.message ?? `Predimarkets API returned ${response.status}`,
+                status: response.status,
+                code: error.code ?? 'UNKNOWN',
+                failureReason: error.failure_reason,
+                body,
+            });
+        }
+        return body;
+    }
+}
+exports.Predimarkets = Predimarkets;
+// ─────────────────────────────────────────────────────────────────────────────
+// Resources
+// ─────────────────────────────────────────────────────────────────────────────
+class Markets {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** List markets. Accepts an id or a slug anywhere a market is named. */
+    list(params = {}) {
+        return this.client.request('GET', '/markets', {
+            query: {
+                status: params.status,
+                limit: params.limit,
+                offset: params.offset,
+                category: params.category,
+            },
+        });
+    }
+    /**
+     * Search markets by meaning, not just keyword — the API ranks with embeddings
+     * fused with full-text, so "who wants to be president" finds the candidacy
+     * markets that share no words with the query.
+     */
+    search(query, params = {}) {
+        return this.client.request('GET', '/markets/search', {
+            query: { q: query, status: params.status, limit: params.limit, offset: params.offset },
+        });
+    }
+    get(marketIdOrSlug) {
+        return this.client.request('GET', `/markets/${encodeURIComponent(marketIdOrSlug)}`);
+    }
+    priceHistory(marketIdOrSlug, params = {}) {
+        return this.client.request('GET', `/markets/${encodeURIComponent(marketIdOrSlug)}/price-history`, {
+            query: { outcome_id: params.outcomeId, timeframe: params.timeframe },
+        });
+    }
+    orderBook(marketIdOrSlug) {
+        return this.client.request('GET', `/markets/${encodeURIComponent(marketIdOrSlug)}/orderbook`);
+    }
+}
+class Orders {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Place an order.
+     *
+     * For parimutuel markets pass `amount` (the money staked). For order-book
+     * markets pass `quantity`, plus `price` when `type` is 'limit'.
+     */
+    create(params) {
+        return this.client.request('POST', '/orders', {
+            body: {
+                market_id: params.marketId,
+                outcome_id: params.outcomeId,
+                partner_user_id: params.userId,
+                side: params.side ?? 'buy',
+                order_type: params.type ?? 'market',
+                amount: params.amount,
+                quantity: params.quantity,
+                price: params.price,
+                max_spend: params.maxSpend,
+            },
+        });
+    }
+}
+class Positions {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(params = {}) {
+        return this.client.request('GET', '/positions', {
+            query: {
+                partner_user_id: params.userId,
+                market_id: params.marketId,
+                status: params.status,
+            },
+        });
+    }
+}
+class Trades {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(params = {}) {
+        return this.client.request('GET', '/trades', {
+            query: {
+                partner_user_id: params.userId,
+                market_id: params.marketId,
+                limit: params.limit,
+                offset: params.offset,
+            },
+        });
+    }
+}
+class CategoricalParimutuel {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Price a stake on one outcome of a multi-outcome market, before placing it. */
+    quote(params) {
+        return this.client.request('GET', '/parimutuel-categorical/quote', {
+            query: { market_id: params.marketId, outcome_id: params.outcomeId, stake: params.stake },
+        });
+    }
+    /** Live pool state: per-outcome pool, probability and multiplier. */
+    state(marketIdOrSlug) {
+        return this.client.request('GET', `/parimutuel-categorical/markets/${encodeURIComponent(marketIdOrSlug)}`);
+    }
+}
+class Parimutuel {
+    client;
+    categorical;
+    constructor(client) {
+        this.client = client;
+        this.categorical = new CategoricalParimutuel(client);
+    }
+    /** Price a stake before placing it: fee, locked multiplier, estimated payout. */
+    quote(params) {
+        return this.client.request('GET', '/parimutuel/quote', {
+            query: {
+                market_id: params.marketId,
+                outcome_id: params.outcomeId,
+                stake: params.stake,
+                side: params.side,
+            },
+        });
+    }
+    /** Live pool state for a binary parimutuel market. */
+    state(marketIdOrSlug) {
+        return this.client.request('GET', `/parimutuel/markets/${encodeURIComponent(marketIdOrSlug)}`);
+    }
+    ticketValue(marketIdOrSlug, ticketId) {
+        return this.client.request('GET', `/parimutuel/markets/${encodeURIComponent(marketIdOrSlug)}/tickets/${encodeURIComponent(ticketId)}/value`);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Webhooks
+// ─────────────────────────────────────────────────────────────────────────────
+/** Header Predimarkets signs every webhook with. */
+exports.SIGNATURE_HEADER = 'x-predimarkets-signature';
+class Webhooks {
+    /**
+     * Verify a webhook actually came from Predimarkets.
+     *
+     * Pass the RAW request body — the exact bytes received. Re-serialising the
+     * parsed JSON will change a byte somewhere (key order, whitespace) and the
+     * signature will not match.
+     *
+     * Compared in constant time: a plain `===` leaks the secret one byte at a time
+     * to anyone who can measure the response.
+     */
+    async verify(params) {
+        if (!params.signature || !params.secret)
+            return false;
+        const expected = await hmacSha256Hex(params.secret, params.payload);
+        return timingSafeEqual(expected, params.signature);
+    }
+    /**
+     * Verify and parse in one step. Throws if the signature is wrong, so a handler
+     * cannot forget to check.
+     */
+    async constructEvent(params) {
+        const ok = await this.verify(params);
+        if (!ok) {
+            throw new PredimarketsError({
+                message: 'Webhook signature verification failed',
+                status: 400,
+                code: 'INVALID_SIGNATURE',
+            });
+        }
+        return JSON.parse(params.payload);
+    }
+}
+exports.Webhooks = Webhooks;
+/** HMAC-SHA256, hex — via WebCrypto so this works everywhere, not just Node. */
+async function hmacSha256Hex(secret, payload) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(payload));
+    return Array.from(new Uint8Array(sig))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+exports.default = Predimarkets;

package/dist/index.d.ts

@@ -0,0 +1,239 @@
+/**
+ * @predimarkets/sdk — the official client for the Predimarkets API.
+ *
+ * Zero runtime dependencies: it uses the platform `fetch`, so it runs on Node 18+,
+ * Bun, Deno, Cloudflare Workers and the browser (server-side only — an API key
+ * must never reach a browser).
+ *
+ * The API speaks snake_case. This SDK speaks camelCase and translates at the
+ * boundary, so integrators write idiomatic TypeScript and never hand-build a
+ * query string.
+ *
+ *   const client = new Predimarkets({ apiKey: process.env.PREDIMARKETS_API_KEY! });
+ *   const { markets } = await client.markets.list({ status: 'open' });
+ *   await client.orders.create({
+ *     marketId: markets[0].id,
+ *     outcomeId: markets[0].outcomes[0].id,
+ *     userId: 'your-user-123',
+ *     side: 'buy',
+ *     amount: 100,
+ *   });
+ */
+export declare const VERSION = "0.1.0";
+/**
+ * Any non-2xx response from the API.
+ *
+ * `code` is the machine-readable code the API returns (INSUFFICIENT_BALANCE,
+ * MARKET_PAUSED, OUTCOME_ELIMINATED, …) — branch on that, never on the message.
+ */
+export declare class PredimarketsError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** The API's own explanation of why the request failed, when it gives one. */
+    readonly failureReason?: string;
+    readonly body: unknown;
+    constructor(args: {
+        message: string;
+        status: number;
+        code: string;
+        failureReason?: string;
+        body?: unknown;
+    });
+}
+export interface ClientOptions {
+    /** Your partner API key. Server-side only — never ship this to a browser. */
+    apiKey: string;
+    /** Override the API host (e.g. a staging environment). */
+    baseUrl?: string;
+    /** Abort a request after this many ms. Default 30s. */
+    timeoutMs?: number;
+    /** Supply your own fetch (for tests, or a runtime without a global one). */
+    fetch?: typeof fetch;
+}
+export type MarketStatus = 'open' | 'closed' | 'resolved' | 'voided' | 'scheduled';
+export type OrderSide = 'buy' | 'sell';
+export type OrderType = 'limit' | 'market';
+export interface Outcome {
+    id: string;
+    label: string;
+    display_order: number;
+    current_price: number | null;
+    potential_return: number | null;
+    total_volume?: number;
+    /** Multi-outcome markets: this runner is out and takes no new bets. */
+    eliminated?: boolean;
+    eliminated_reason?: string | null;
+}
+export interface Market {
+    id: string;
+    title: string;
+    slug: string;
+    description: string | null;
+    image_url: string | null;
+    market_type: string;
+    source: string;
+    status: MarketStatus | string;
+    trading_ends_at: string;
+    resolution_at: string;
+    resolution_criteria?: string | null;
+    resolution?: string | null;
+    outcomes: Outcome[];
+    total_volume?: number;
+    traders?: number;
+    [key: string]: unknown;
+}
+export interface Paginated<T> {
+    markets?: T[];
+    total?: number;
+    limit?: number;
+    offset?: number;
+    [key: string]: unknown;
+}
+export interface CreateOrderParams {
+    marketId: string;
+    outcomeId: string;
+    /** Your own id for the end user placing the bet. */
+    userId: string;
+    side?: OrderSide;
+    type?: OrderType;
+    /**
+     * Parimutuel: the amount of money the user is staking. Preferred — it is
+     * debited and staked 1:1, with no separate share price to reason about.
+     */
+    amount?: number;
+    /** Order book: number of shares. */
+    quantity?: number;
+    /** Order book limit orders: price per share, 0–1. */
+    price?: number;
+    /** Hard cap on total spend including fees. Buy orders only. */
+    maxSpend?: number;
+}
+export interface QuoteParams {
+    marketId: string;
+    outcomeId: string;
+    stake: number;
+    /** Binary parimutuel only. */
+    side?: 'yes' | 'no';
+}
+export declare class Predimarkets {
+    readonly markets: Markets;
+    readonly orders: Orders;
+    readonly positions: Positions;
+    readonly trades: Trades;
+    readonly parimutuel: Parimutuel;
+    readonly webhooks: Webhooks;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    constructor(options: ClientOptions);
+    /** Escape hatch: call any endpoint the SDK doesn't wrap yet. */
+    request<T = unknown>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, options?: {
+        query?: Record<string, unknown>;
+        body?: unknown;
+    }): Promise<T>;
+}
+declare class Markets {
+    private readonly client;
+    constructor(client: Predimarkets);
+    /** List markets. Accepts an id or a slug anywhere a market is named. */
+    list(params?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+        category?: string;
+    }): Promise<Paginated<Market>>;
+    /**
+     * Search markets by meaning, not just keyword — the API ranks with embeddings
+     * fused with full-text, so "who wants to be president" finds the candidacy
+     * markets that share no words with the query.
+     */
+    search(query: string, params?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<Paginated<Market>>;
+    get(marketIdOrSlug: string): Promise<Market>;
+    priceHistory(marketIdOrSlug: string, params?: {
+        outcomeId?: string;
+        timeframe?: '1H' | '1D' | '1W' | '1M' | 'ALL';
+    }): Promise<unknown>;
+    orderBook(marketIdOrSlug: string): Promise<unknown>;
+}
+declare class Orders {
+    private readonly client;
+    constructor(client: Predimarkets);
+    /**
+     * Place an order.
+     *
+     * For parimutuel markets pass `amount` (the money staked). For order-book
+     * markets pass `quantity`, plus `price` when `type` is 'limit'.
+     */
+    create(params: CreateOrderParams): Promise<unknown>;
+}
+declare class Positions {
+    private readonly client;
+    constructor(client: Predimarkets);
+    list(params?: {
+        userId?: string;
+        marketId?: string;
+        status?: string;
+    }): Promise<unknown>;
+}
+declare class Trades {
+    private readonly client;
+    constructor(client: Predimarkets);
+    list(params?: {
+        userId?: string;
+        marketId?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<unknown>;
+}
+declare class CategoricalParimutuel {
+    private readonly client;
+    constructor(client: Predimarkets);
+    /** Price a stake on one outcome of a multi-outcome market, before placing it. */
+    quote(params: QuoteParams): Promise<unknown>;
+    /** Live pool state: per-outcome pool, probability and multiplier. */
+    state(marketIdOrSlug: string): Promise<unknown>;
+}
+declare class Parimutuel {
+    private readonly client;
+    readonly categorical: CategoricalParimutuel;
+    constructor(client: Predimarkets);
+    /** Price a stake before placing it: fee, locked multiplier, estimated payout. */
+    quote(params: QuoteParams): Promise<unknown>;
+    /** Live pool state for a binary parimutuel market. */
+    state(marketIdOrSlug: string): Promise<unknown>;
+    ticketValue(marketIdOrSlug: string, ticketId: string): Promise<unknown>;
+}
+/** Header Predimarkets signs every webhook with. */
+export declare const SIGNATURE_HEADER = "x-predimarkets-signature";
+export declare class Webhooks {
+    /**
+     * Verify a webhook actually came from Predimarkets.
+     *
+     * Pass the RAW request body — the exact bytes received. Re-serialising the
+     * parsed JSON will change a byte somewhere (key order, whitespace) and the
+     * signature will not match.
+     *
+     * Compared in constant time: a plain `===` leaks the secret one byte at a time
+     * to anyone who can measure the response.
+     */
+    verify(params: {
+        payload: string;
+        signature: string | null | undefined;
+        secret: string;
+    }): Promise<boolean>;
+    /**
+     * Verify and parse in one step. Throws if the signature is wrong, so a handler
+     * cannot forget to check.
+     */
+    constructEvent<T = unknown>(params: {
+        payload: string;
+        signature: string | null | undefined;
+        secret: string;
+    }): Promise<T>;
+}
+export default Predimarkets;

package/dist/index.js

@@ -0,0 +1,334 @@
+/**
+ * @predimarkets/sdk — the official client for the Predimarkets API.
+ *
+ * Zero runtime dependencies: it uses the platform `fetch`, so it runs on Node 18+,
+ * Bun, Deno, Cloudflare Workers and the browser (server-side only — an API key
+ * must never reach a browser).
+ *
+ * The API speaks snake_case. This SDK speaks camelCase and translates at the
+ * boundary, so integrators write idiomatic TypeScript and never hand-build a
+ * query string.
+ *
+ *   const client = new Predimarkets({ apiKey: process.env.PREDIMARKETS_API_KEY! });
+ *   const { markets } = await client.markets.list({ status: 'open' });
+ *   await client.orders.create({
+ *     marketId: markets[0].id,
+ *     outcomeId: markets[0].outcomes[0].id,
+ *     userId: 'your-user-123',
+ *     side: 'buy',
+ *     amount: 100,
+ *   });
+ */
+export const VERSION = '0.1.0';
+const DEFAULT_BASE_URL = 'https://api.predimarkets.com';
+const DEFAULT_TIMEOUT_MS = 30_000;
+// ─────────────────────────────────────────────────────────────────────────────
+// Errors
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Any non-2xx response from the API.
+ *
+ * `code` is the machine-readable code the API returns (INSUFFICIENT_BALANCE,
+ * MARKET_PAUSED, OUTCOME_ELIMINATED, …) — branch on that, never on the message.
+ */
+export class PredimarketsError extends Error {
+    status;
+    code;
+    /** The API's own explanation of why the request failed, when it gives one. */
+    failureReason;
+    body;
+    constructor(args) {
+        super(args.message);
+        this.name = 'PredimarketsError';
+        this.status = args.status;
+        this.code = args.code;
+        this.failureReason = args.failureReason;
+        this.body = args.body;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Client
+// ─────────────────────────────────────────────────────────────────────────────
+export class Predimarkets {
+    markets;
+    orders;
+    positions;
+    trades;
+    parimutuel;
+    webhooks;
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    fetchImpl;
+    constructor(options) {
+        if (!options?.apiKey) {
+            throw new Error('Predimarkets: apiKey is required');
+        }
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f) {
+            throw new Error('Predimarkets: no fetch available. Use Node 18+, or pass { fetch } explicitly.');
+        }
+        this.fetchImpl = f;
+        this.markets = new Markets(this);
+        this.orders = new Orders(this);
+        this.positions = new Positions(this);
+        this.trades = new Trades(this);
+        this.parimutuel = new Parimutuel(this);
+        this.webhooks = new Webhooks();
+    }
+    /** Escape hatch: call any endpoint the SDK doesn't wrap yet. */
+    async request(method, path, options = {}) {
+        const url = new URL(`${this.baseUrl}/v1${path.startsWith('/') ? path : `/${path}`}`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined && value !== null)
+                url.searchParams.set(key, String(value));
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(url.toString(), {
+                method,
+                signal: controller.signal,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    'Content-Type': 'application/json',
+                    'User-Agent': `predimarkets-sdk/${VERSION}`,
+                },
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            });
+        }
+        catch (err) {
+            const aborted = err instanceof Error && err.name === 'AbortError';
+            throw new PredimarketsError({
+                message: aborted
+                    ? `Request timed out after ${this.timeoutMs}ms`
+                    : `Network error calling Predimarkets: ${err?.message ?? err}`,
+                status: 0,
+                code: aborted ? 'TIMEOUT' : 'NETWORK_ERROR',
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await response.text();
+        let body = undefined;
+        try {
+            body = text ? JSON.parse(text) : undefined;
+        }
+        catch {
+            body = text;
+        }
+        if (!response.ok) {
+            const error = body?.error ?? {};
+            throw new PredimarketsError({
+                message: error.message ?? `Predimarkets API returned ${response.status}`,
+                status: response.status,
+                code: error.code ?? 'UNKNOWN',
+                failureReason: error.failure_reason,
+                body,
+            });
+        }
+        return body;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Resources
+// ─────────────────────────────────────────────────────────────────────────────
+class Markets {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** List markets. Accepts an id or a slug anywhere a market is named. */
+    list(params = {}) {
+        return this.client.request('GET', '/markets', {
+            query: {
+                status: params.status,
+                limit: params.limit,
+                offset: params.offset,
+                category: params.category,
+            },
+        });
+    }
+    /**
+     * Search markets by meaning, not just keyword — the API ranks with embeddings
+     * fused with full-text, so "who wants to be president" finds the candidacy
+     * markets that share no words with the query.
+     */
+    search(query, params = {}) {
+        return this.client.request('GET', '/markets/search', {
+            query: { q: query, status: params.status, limit: params.limit, offset: params.offset },
+        });
+    }
+    get(marketIdOrSlug) {
+        return this.client.request('GET', `/markets/${encodeURIComponent(marketIdOrSlug)}`);
+    }
+    priceHistory(marketIdOrSlug, params = {}) {
+        return this.client.request('GET', `/markets/${encodeURIComponent(marketIdOrSlug)}/price-history`, {
+            query: { outcome_id: params.outcomeId, timeframe: params.timeframe },
+        });
+    }
+    orderBook(marketIdOrSlug) {
+        return this.client.request('GET', `/markets/${encodeURIComponent(marketIdOrSlug)}/orderbook`);
+    }
+}
+class Orders {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Place an order.
+     *
+     * For parimutuel markets pass `amount` (the money staked). For order-book
+     * markets pass `quantity`, plus `price` when `type` is 'limit'.
+     */
+    create(params) {
+        return this.client.request('POST', '/orders', {
+            body: {
+                market_id: params.marketId,
+                outcome_id: params.outcomeId,
+                partner_user_id: params.userId,
+                side: params.side ?? 'buy',
+                order_type: params.type ?? 'market',
+                amount: params.amount,
+                quantity: params.quantity,
+                price: params.price,
+                max_spend: params.maxSpend,
+            },
+        });
+    }
+}
+class Positions {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(params = {}) {
+        return this.client.request('GET', '/positions', {
+            query: {
+                partner_user_id: params.userId,
+                market_id: params.marketId,
+                status: params.status,
+            },
+        });
+    }
+}
+class Trades {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    list(params = {}) {
+        return this.client.request('GET', '/trades', {
+            query: {
+                partner_user_id: params.userId,
+                market_id: params.marketId,
+                limit: params.limit,
+                offset: params.offset,
+            },
+        });
+    }
+}
+class CategoricalParimutuel {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** Price a stake on one outcome of a multi-outcome market, before placing it. */
+    quote(params) {
+        return this.client.request('GET', '/parimutuel-categorical/quote', {
+            query: { market_id: params.marketId, outcome_id: params.outcomeId, stake: params.stake },
+        });
+    }
+    /** Live pool state: per-outcome pool, probability and multiplier. */
+    state(marketIdOrSlug) {
+        return this.client.request('GET', `/parimutuel-categorical/markets/${encodeURIComponent(marketIdOrSlug)}`);
+    }
+}
+class Parimutuel {
+    client;
+    categorical;
+    constructor(client) {
+        this.client = client;
+        this.categorical = new CategoricalParimutuel(client);
+    }
+    /** Price a stake before placing it: fee, locked multiplier, estimated payout. */
+    quote(params) {
+        return this.client.request('GET', '/parimutuel/quote', {
+            query: {
+                market_id: params.marketId,
+                outcome_id: params.outcomeId,
+                stake: params.stake,
+                side: params.side,
+            },
+        });
+    }
+    /** Live pool state for a binary parimutuel market. */
+    state(marketIdOrSlug) {
+        return this.client.request('GET', `/parimutuel/markets/${encodeURIComponent(marketIdOrSlug)}`);
+    }
+    ticketValue(marketIdOrSlug, ticketId) {
+        return this.client.request('GET', `/parimutuel/markets/${encodeURIComponent(marketIdOrSlug)}/tickets/${encodeURIComponent(ticketId)}/value`);
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Webhooks
+// ─────────────────────────────────────────────────────────────────────────────
+/** Header Predimarkets signs every webhook with. */
+export const SIGNATURE_HEADER = 'x-predimarkets-signature';
+export class Webhooks {
+    /**
+     * Verify a webhook actually came from Predimarkets.
+     *
+     * Pass the RAW request body — the exact bytes received. Re-serialising the
+     * parsed JSON will change a byte somewhere (key order, whitespace) and the
+     * signature will not match.
+     *
+     * Compared in constant time: a plain `===` leaks the secret one byte at a time
+     * to anyone who can measure the response.
+     */
+    async verify(params) {
+        if (!params.signature || !params.secret)
+            return false;
+        const expected = await hmacSha256Hex(params.secret, params.payload);
+        return timingSafeEqual(expected, params.signature);
+    }
+    /**
+     * Verify and parse in one step. Throws if the signature is wrong, so a handler
+     * cannot forget to check.
+     */
+    async constructEvent(params) {
+        const ok = await this.verify(params);
+        if (!ok) {
+            throw new PredimarketsError({
+                message: 'Webhook signature verification failed',
+                status: 400,
+                code: 'INVALID_SIGNATURE',
+            });
+        }
+        return JSON.parse(params.payload);
+    }
+}
+/** HMAC-SHA256, hex — via WebCrypto so this works everywhere, not just Node. */
+async function hmacSha256Hex(secret, payload) {
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(payload));
+    return Array.from(new Uint8Array(sig))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+export default Predimarkets;

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@predimarkets/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript client for the Predimarkets API — matching, oracle resolution and settlement for prediction markets.",
+  "keywords": ["predimarkets", "prediction-markets", "parimutuel", "betting", "sdk", "api-client"],
+  "homepage": "https://predimarkets.com",
+  "license": "MIT",
+  "author": "Predimarkets",
+  "repository": { "type": "git", "url": "https://github.com/musakkka/predimarkets-sdk.git" },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "engines": { "node": ">=18" },
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/rename-cjs.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "@types/node": "^20.19.0"
+  }
+}