@pulsepairs/sdk 0.2.0

package/dist/http.d.ts

@@ -0,0 +1,46 @@
+import type { ApiConfig, Balance, CancelOrderBody, MarketDetail, MarketListItem, OrderBookFull, OrdersResponse, PairSymbol, PostOrderBody, Position, Stats, Trade, Version } from "./types.js";
+export declare class UpDownHttpClient {
+    private readonly baseUrl;
+    constructor(baseUrl: string);
+    getVersion(): Promise<Version>;
+    getHealth(): Promise<{
+        status: string;
+        relayer?: string;
+        uptime?: number;
+    }>;
+    getConfig(): Promise<ApiConfig>;
+    getMarkets(opts?: {
+        timeframe?: 300 | 900 | 3600;
+        pair?: PairSymbol;
+    }): Promise<MarketListItem[]>;
+    getMarket(address: string): Promise<MarketDetail>;
+    getOrderbook(marketAddress: string): Promise<OrderBookFull>;
+    getBalance(wallet: string): Promise<Balance>;
+    getPositions(wallet: string): Promise<Position[]>;
+    getTrades(wallet: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<Trade[]>;
+    getOrders(wallet: string, opts?: {
+        status?: string[];
+        limit?: number;
+        offset?: number;
+    }): Promise<OrdersResponse>;
+    getStats(): Promise<Stats>;
+    postOrder(body: PostOrderBody): Promise<{
+        id: string;
+        status: string;
+        market: string;
+        option: number;
+        side: string;
+        type: string;
+        price: number;
+        amount: string;
+        createdAt: number | string;
+    }>;
+    cancelOrder(orderId: string, body: CancelOrderBody): Promise<{
+        id: string;
+        status: "CANCEL_PENDING" | string;
+    }>;
+}
+export declare function wsUrlFromHttpBase(httpBase: string): string;

package/dist/http.js

@@ -0,0 +1,120 @@
+function buildUrl(base, path, query) {
+    const b = base.replace(/\/$/, "");
+    const p = path.startsWith("/") ? path : `/${path}`;
+    const u = new URL(`${b}${p}`);
+    if (query) {
+        for (const [k, v] of Object.entries(query)) {
+            if (v !== undefined && v !== "")
+                u.searchParams.set(k, String(v));
+        }
+    }
+    return u.toString();
+}
+async function parseJson(res) {
+    const text = await res.text();
+    if (!res.ok) {
+        let msg = text;
+        try {
+            const j = JSON.parse(text);
+            if (j.error)
+                msg = j.error;
+        }
+        catch {
+            /* ignore */
+        }
+        throw new Error(msg || res.statusText);
+    }
+    if (!text)
+        return undefined;
+    return JSON.parse(text);
+}
+export class UpDownHttpClient {
+    baseUrl;
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    async getVersion() {
+        const res = await fetch(buildUrl(this.baseUrl, "/version"));
+        return parseJson(res);
+    }
+    async getHealth() {
+        const res = await fetch(buildUrl(this.baseUrl, "/health"));
+        return parseJson(res);
+    }
+    async getConfig() {
+        const res = await fetch(buildUrl(this.baseUrl, "/config"));
+        return parseJson(res);
+    }
+    async getMarkets(opts) {
+        const res = await fetch(buildUrl(this.baseUrl, "/markets", {
+            timeframe: opts?.timeframe,
+            pair: opts?.pair,
+        }));
+        return parseJson(res);
+    }
+    async getMarket(address) {
+        const res = await fetch(buildUrl(this.baseUrl, `/markets/${encodeURIComponent(address)}`));
+        return parseJson(res);
+    }
+    async getOrderbook(marketAddress) {
+        const res = await fetch(buildUrl(this.baseUrl, `/orderbook/${encodeURIComponent(marketAddress)}`));
+        return parseJson(res);
+    }
+    async getBalance(wallet) {
+        const res = await fetch(buildUrl(this.baseUrl, `/balance/${wallet}`));
+        return parseJson(res);
+    }
+    async getPositions(wallet) {
+        const res = await fetch(buildUrl(this.baseUrl, `/positions/${wallet}`));
+        return parseJson(res);
+    }
+    async getTrades(wallet, opts) {
+        const res = await fetch(buildUrl(this.baseUrl, `/trades/${wallet}`, {
+            limit: opts?.limit,
+            offset: opts?.offset,
+        }));
+        return parseJson(res);
+    }
+    async getOrders(wallet, opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit != null)
+            params.set("limit", String(opts.limit));
+        if (opts?.offset != null)
+            params.set("offset", String(opts.offset));
+        if (opts?.status)
+            for (const s of opts.status)
+                params.append("status", s);
+        const url = buildUrl(this.baseUrl, `/orders/${wallet}`) +
+            (params.toString() ? `?${params.toString()}` : "");
+        const res = await fetch(url);
+        return parseJson(res);
+    }
+    async getStats() {
+        const res = await fetch(buildUrl(this.baseUrl, "/stats"));
+        return parseJson(res);
+    }
+    async postOrder(body) {
+        const res = await fetch(buildUrl(this.baseUrl, "/orders"), {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return parseJson(res);
+    }
+    async cancelOrder(orderId, body) {
+        const res = await fetch(buildUrl(this.baseUrl, `/orders/${orderId}`), {
+            method: "DELETE",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        return parseJson(res);
+    }
+}
+export function wsUrlFromHttpBase(httpBase) {
+    const u = new URL(httpBase);
+    u.protocol = u.protocol === "https:" ? "wss:" : "ws:";
+    u.pathname = "/stream";
+    u.search = "";
+    u.hash = "";
+    return u.toString();
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { UpDownHttpClient, wsUrlFromHttpBase } from "./http.js";
+export { UpDownWsClient, type UpDownWsMessage, type SubscribePayload, type WsAuthCredentials, type ConnectAuthedOptions, } from "./ws.js";
+export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, type OrderSignMessage, type CancelSignMessage, type WsAuthMessage, type ParsedComposite, } from "./eip712.js";
+export { CLOB_AUTH_TYPES, CLOB_AUTH_MESSAGE, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS, type ClobAuthDomain, type ClobAuthMessage, } from "./auth.js";
+export { ensureSettlementAllowance, MAX_UINT256, type EnsureAllowanceResult, } from "./approve.js";
+export { UpDownAccountKitSigner, bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature, type UpDownAccountKitConfig, type Eip1193Provider, type GrantSessionResult, type RawTypedDataSigner, } from "./accountKit.js";
+export { OrderType, OrderSide, Option, type ApiConfig, type Balance, type CancelOrderBody, type Eip712Domain, type MarketDetail, type MarketListItem, type OptionValue, type OrderBookFull, type OrderBookLevel, type OrderBookSide, type OrderRow, type OrderSideKey, type OrderSideValue, type OrderStatus, type OrderTypeKey, type OrderTypeValue, type OrdersResponse, type PairConfig, type PairSymbol, type PostOrderBody, type Position, type Stats, type Trade, type Version, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,15 @@
+// HTTP + WS clients
+export { UpDownHttpClient, wsUrlFromHttpBase } from "./http.js";
+export { UpDownWsClient, } from "./ws.js";
+// EIP-712 helpers
+export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, } from "./eip712.js";
+// Phase 3 / Gate 1 — L2 HMAC auth helpers
+export { CLOB_AUTH_TYPES, CLOB_AUTH_MESSAGE, buildClobAuthTypedData, buildHmacSignature, HMAC_HEADERS, } from "./auth.js";
+// Approve helper
+export { ensureSettlementAllowance, MAX_UINT256, } from "./approve.js";
+// Account Kit (Alchemy SCA) — owner-key ERC-1271 order signing + gasless custody.
+// Peer deps (@account-kit/*, @aa-sdk/core) are lazy-imported; importing this
+// module does NOT require them unless you construct/connect the signer.
+export { UpDownAccountKitSigner, bareErc1271Signer, stripErc6492Wrapper, isErc6492Signature, } from "./accountKit.js";
+// Types
+export { OrderType, OrderSide, Option, } from "./types.js";

package/dist/types.d.ts

@@ -0,0 +1,235 @@
+/**
+ * UpDown SDK type surface — mirrors the backend's REST + WS response shapes
+ * one-to-one. Keep field names and casing in sync with `docs/api.md`; if a
+ * shape drifts, update both in the same commit.
+ */
+export type PairSymbol = "BTC-USD" | "ETH-USD";
+export type OrderTypeKey = "LIMIT" | "MARKET" | "POST_ONLY" | "IOC";
+export type OrderSideKey = "BUY" | "SELL";
+/** Numeric enum values match the backend's on-chain encoding. */
+export declare const OrderType: {
+    readonly LIMIT: 0;
+    readonly MARKET: 1;
+    readonly POST_ONLY: 2;
+    readonly IOC: 3;
+};
+export type OrderTypeValue = (typeof OrderType)[OrderTypeKey];
+export declare const OrderSide: {
+    readonly BUY: 0;
+    readonly SELL: 1;
+};
+export type OrderSideValue = (typeof OrderSide)[OrderSideKey];
+export declare const Option: {
+    readonly UP: 1;
+    readonly DOWN: 2;
+};
+export type OptionValue = (typeof Option)[keyof typeof Option];
+/** Per-pair config emitted by `/config.pairs[]`. */
+export type PairConfig = {
+    pairId: PairSymbol;
+    settlementAddress: `0x${string}`;
+    /** Empty string when the pair has no autocycler wired (read-only mode). */
+    autocyclerAddress: `0x${string}` | "";
+    eip712: {
+        domain: Eip712Domain;
+    };
+};
+export type Eip712Domain = {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: `0x${string}`;
+};
+export type ApiConfig = {
+    chainId: number;
+    usdtAddress: `0x${string}`;
+    relayerAddress: `0x${string}`;
+    platformFeeBps: number;
+    makerFeeBps: number;
+    /** When `"probability-weighted"`, taker fees scale as `4 × p × (1 − p) × totalBps`. */
+    feeModel?: "probability-weighted" | string;
+    /** `platformFeeBps + makerFeeBps` (peak fee at 50¢). */
+    peakFeeBps?: number;
+    dmmRebateBps: number;
+    usdtDecimals: number;
+    /** Multi-pair list — preferred for new clients. */
+    pairs: PairConfig[];
+    /**
+     * @deprecated Use `pairs[i].settlementAddress` and look up by the market's
+     * `settlementAddress` via `findPairBySettlement(...)`. Kept as the FIRST
+     * pair's value for one release cycle of overlap.
+     */
+    settlementAddress: `0x${string}`;
+    /**
+     * @deprecated Use `pairs[i].eip712.domain` per market. Kept as the FIRST
+     * pair's domain for one release cycle of overlap.
+     */
+    eip712: {
+        domain: Eip712Domain;
+    };
+};
+export type MarketListItem = {
+    /** Composite key `<settlementAddress>-<marketId>`. */
+    address: string;
+    marketId?: string;
+    settlementAddress?: `0x${string}`;
+    pairId: string;
+    pairSymbol?: PairSymbol;
+    chartSymbol?: "BTC" | "ETH";
+    startTime: number;
+    endTime: number;
+    duration: number;
+    status: "ACTIVE" | "TRADING_ENDED" | "RESOLVED" | "CLAIMED" | string;
+    winner: number | null;
+    upPrice: string;
+    downPrice: string;
+    strikePrice?: string;
+    settlementPrice?: string;
+    volume: string;
+};
+export type MarketDetail = MarketListItem & {
+    timeRemainingSeconds: number;
+    orderBook: {
+        up: OrderBookSide;
+        down: OrderBookSide;
+    };
+};
+export type OrderBookSide = {
+    bestBid: {
+        price: number;
+        depth: string;
+    } | null;
+    bestAsk: {
+        price: number;
+        depth: string;
+    } | null;
+};
+export type OrderBookFull = {
+    up: {
+        bids: OrderBookLevel[];
+        asks: OrderBookLevel[];
+    };
+    down: {
+        bids: OrderBookLevel[];
+        asks: OrderBookLevel[];
+    };
+};
+export type OrderBookLevel = {
+    price: number;
+    depth: string;
+    count: number;
+};
+export type Balance = {
+    wallet: string;
+    smartAccountAddress: string;
+    available: string;
+    inOrders: string;
+    cachedBalance: string;
+    balanceLastSyncedAt: string;
+    withdrawNonce: number;
+};
+export type Position = {
+    market: string;
+    marketStatus: string;
+    option: number;
+    optionLabel: "UP" | "DOWN";
+    shares: string;
+    avgPrice: number;
+    costBasis: string;
+};
+export type Trade = {
+    tradeId: string;
+    market: string;
+    option: number;
+    buyOrderId: string;
+    sellOrderId: string;
+    buyer: string;
+    seller: string;
+    price: number;
+    amount: string;
+    platformFee: string;
+    makerFee: string;
+    settlementStatus: string;
+    createdAt: string;
+};
+export type OrderStatus = "OPEN" | "PARTIALLY_FILLED" | "FILLED" | "CANCEL_PENDING" | "CANCELLED" | string;
+export type OrderRow = {
+    orderId: string;
+    maker: string;
+    market: string;
+    option: number;
+    side: number;
+    type: number;
+    price: number;
+    amount: string;
+    filledAmount: string;
+    /**
+     * uint256 nonce, JSON-string-encoded. Backend's `OrderModel` schema
+     * stores this as `String` (PR-13.1 hotfix) to preserve full precision
+     * — a `number` here would silently truncate above 2^53. Parse via
+     * `BigInt(row.nonce)` if you need the value, or pass the string
+     * straight to `signTypedData` (viem accepts string-form bigints).
+     */
+    nonce: string;
+    /** uint256 unix-sec expiry, JSON-string-encoded. See `nonce`. */
+    expiry: string;
+    /** EIP-712 signature; backend marks this required on the row. */
+    signature: string;
+    status: OrderStatus;
+    reason?: string;
+    createdAt: string;
+    updatedAt?: string;
+};
+export type OrdersResponse = {
+    orders: OrderRow[];
+    total: number;
+    limit: number;
+    offset: number;
+};
+export type Stats = {
+    totalVolume: string;
+    activeMarketsCount: number;
+    totalTraders: number;
+};
+export type Version = {
+    commit: string;
+    bootedAt: string;
+    env: string;
+    nodeVersion: string;
+};
+/** Atomic-USDT body for `POST /orders`. The backend re-verifies the
+ *  signature against the per-pair domain on receipt. */
+export type PostOrderBody = {
+    maker: string;
+    /** Composite key `<settlement>-<marketId>` — used for routing only. */
+    market: string;
+    option: number;
+    side: number | OrderSideKey;
+    type: number | OrderTypeKey;
+    /** bps; 0 for MARKET. */
+    price?: number;
+    /** Atomic USDT (1 USDT = 1_000_000). */
+    amount: string;
+    /**
+     * F-2026-17731 (Hacken remediation V2): signed fee cap, atomic-USDT decimal
+     * string. Position between `amount` and `nonce` in the signed `Order` — MUST
+     * be present and MUST equal the value inside the signature, else the on-chain
+     * `SignatureChecker` rejects the fill (the ORDER_TYPEHASH includes `maxFee`).
+     * Compute as `amount * (platformFeeBps + makerFeeBps) / 10000` (peak fee).
+     */
+    maxFee: string;
+    nonce: number;
+    expiry: number;
+    signature: string;
+};
+export type CancelOrderBody = {
+    maker: string;
+    signature: string;
+    /**
+     * uint256 nonce — must match what was signed. **Send as a JSON string** to
+     * preserve full precision; backend's PR-13.1 hotfix coerces via `BigInt(...)`.
+     */
+    nonce: string | number;
+    /** uint256 unix-sec expiry — must match what was signed. */
+    expiry: string | number;
+};

package/dist/types.js

@@ -0,0 +1,20 @@
+/**
+ * UpDown SDK type surface — mirrors the backend's REST + WS response shapes
+ * one-to-one. Keep field names and casing in sync with `docs/api.md`; if a
+ * shape drifts, update both in the same commit.
+ */
+/** Numeric enum values match the backend's on-chain encoding. */
+export const OrderType = {
+    LIMIT: 0,
+    MARKET: 1,
+    POST_ONLY: 2,
+    IOC: 3,
+};
+export const OrderSide = {
+    BUY: 0,
+    SELL: 1,
+};
+export const Option = {
+    UP: 1,
+    DOWN: 2,
+};

package/dist/ws.d.ts

@@ -0,0 +1,118 @@
+/**
+ * WebSocket client with auto-reconnect + PR-19 auth handshake.
+ *
+ * Two paths:
+ *
+ *   - `connectPublic(channels)` — public channels only (`markets`,
+ *     `orderbook:*`, `trades:*`). Sends `{type:'subscribe', channels}`
+ *     immediately on open, no auth.
+ *
+ *   - `connectAuthed({ signAuth, channels })` — sends
+ *     `{type:'auth', ...}` first, awaits `auth_ok`, then sends
+ *     `{type:'subscribe', channels}`. Required for `orders:<wallet>` +
+ *     `balance:<wallet>` (PR-19 gates these behind a verified WsAuth
+ *     signature). On reconnect within the 24h token TTL, replays the
+ *     cached token via `{type:'auth', token}` — only re-prompts the
+ *     `signAuth` callback if the server rejects the cached token.
+ *
+ * Server message envelope (mirrors `src/ws/WebSocketServer.ts:235-293`):
+ *
+ *   client → server   { type: 'auth', wallet, timestamp, sessionId, signature }
+ *   server → client   { type: 'auth_ok', wallet, token, expiresAt }
+ *                  or { type: 'auth_error' }   (no reason echoed — anti-probe)
+ *
+ *   client → server   { type: 'auth', token }            (token replay)
+ *   server → client   { type: 'auth_ok', wallet, token } (token re-validated)
+ *
+ * State machine:
+ *   idle → authenticating → subscribing → live
+ *                                       → unauthed-failure  (signAuth rejected)
+ *
+ * The legacy `connect(SubscribePayload)` API is retained as a deprecated
+ * shim that routes to `connectPublic` so existing public-only callers
+ * keep working without code changes. The `wallet` field on the legacy
+ * payload is now silently ignored (it was never authenticated and
+ * post-PR-19 the server drops private subs from anonymous clients).
+ */
+export type UpDownWsMessage = {
+    type: string;
+    channel?: string;
+    data?: unknown;
+};
+/**
+ * @deprecated Use `connectPublic(channels)` for public channels or
+ * `connectAuthed({ signAuth, channels })` for `orders:*` / `balance:*`.
+ * Pre-PR-19 the `wallet` field auto-subscribed `orders:<wallet>` without
+ * any signature check; that gate is now closed and a `wallet`-only
+ * payload no longer receives per-wallet events.
+ */
+export type SubscribePayload = {
+    type: "subscribe";
+    channels: string[];
+    wallet?: string;
+};
+/** Returned from a `signAuth` callback. */
+export type WsAuthCredentials = {
+    wallet: `0x${string}`;
+    /** Unix seconds, as a bigint. Server window is ±60s. */
+    timestamp: bigint;
+    /** 32-byte hex (bytes32). See `freshSessionId()`. */
+    sessionId: `0x${string}`;
+    /** EIP-712 signature over `WS_AUTH_TYPES`. */
+    signature: `0x${string}`;
+    /**
+     * Optional cached token from a previous `auth_ok`. When supplied, the
+     * client tries token replay first and only sends the signed payload if
+     * the server returns `auth_error`.
+     */
+    token?: string;
+};
+export type ConnectAuthedOptions = {
+    /** Async callback that returns the credentials to authenticate with. */
+    signAuth: () => Promise<WsAuthCredentials>;
+    /** Channels to subscribe to AFTER auth_ok. May include public channels. */
+    channels: string[];
+    /** Optional callback fired when auth fails terminally (signAuth rejected
+     *  by the server). The client stops reconnecting in that case. */
+    onAuthError?: (reason?: string) => void;
+};
+export declare class UpDownWsClient {
+    private readonly url;
+    private readonly onMessage;
+    private ws;
+    private reconnect;
+    private timer;
+    private closed;
+    private mode;
+    private state;
+    /** Cached token + expiry from the last successful auth_ok. Replayed on
+     *  reconnect; cleared if the server returns auth_error against it. */
+    private cachedToken;
+    private cachedTokenExpiresAt;
+    constructor(url: string, onMessage: (msg: UpDownWsMessage) => void);
+    /**
+     * Subscribe to public channels only (`markets`, `orderbook:*`,
+     * `trades:*`). No signature required.
+     */
+    connectPublic(channels: string[]): void;
+    /**
+     * Authenticate via the PR-19 EIP-712 handshake, then subscribe.
+     * Required for `orders:*` and `balance:*` channels.
+     */
+    connectAuthed(opts: ConnectAuthedOptions): void;
+    /**
+     * @deprecated Use `connectPublic(channels)` or `connectAuthed({ ... })`.
+     * Pre-PR-19 the WS server accepted `{type:'subscribe', wallet}` and
+     * auto-attached `orders:<wallet>` to the anonymous client; that path
+     * is now closed. The `wallet` field on the payload is ignored — if
+     * the channel list contains private channels they will be silently
+     * dropped by the server because the connection is unauthenticated.
+     */
+    connect(subscribe: SubscribePayload): void;
+    disconnect(): void;
+    private openSocket;
+    private startHandshake;
+    private runSignAndSendAuth;
+    private handleIncoming;
+    private send;
+}