@pulsepairs/sdk 0.7.0 → 0.8.0

package/DOCUMENTATION.md

@@ -2,7 +2,7 @@
 
 **Version:** 0.7.0 · **License:** UNLICENSED · **Runtime:** Node ≥ 18 or a modern browser
 
-Complete reference for the UpDown (PulsePairs) TypeScript SDK: every export, its
+Complete reference for the UpDown TypeScript SDK: every export, its
 units, its failure modes, and the protocol it speaks.
 
 The [`README.md`](./README.md) is the quickstart. **This** document is the
@@ -61,19 +61,28 @@ on-chain fill. You never pay gas to place, amend or cancel an order — only for
 the one-time ERC-20 `approve` (and, on the smart-account path, the one-time
 account deploy).
 
-### The demo environment
+### The environments
 
-A full stack runs 24/7 on Arbitrum One with a mock oracle and mintable test USDT:
+Two stacks, both running 24/7 on **Arbitrum One** (dev is not a testnet — it is
+mainnet with a mock oracle and play money):
 
 ```
-UI       https://demo-pulsepairs.rainwins.com
-REST     https://api.demo-pulsepairs.rainwins.com
-WS       wss://api.demo-pulsepairs.rainwins.com/stream
-Faucet   POST /test/devmint   (10k cap, 1 mint / address / 5 min; also seeds gas ETH)
+DEV    REST   https://dev-api-updown.rain.trade
+       WS     wss://dev-api-updown.rain.trade/stream
+       Money  mock USDT, mintable
+       Oracle mock Data Streams; chart shows the CEX composite
+       Faucet POST /test/devmint  (10k cap, 1 mint / address / 5 min; also seeds gas ETH)
+
+PROD   REST   https://prod-api-updown.rain.trade
+       WS     wss://prod-api-updown.rain.trade/stream
+       Money  real USDT0
+       Oracle real Chainlink Data Streams; chart shows the DON benchmark it settles on
+       Faucet none — /test/devmint 404s
 ```
 
 Mint to the **smart-account** address if you are on the Account Kit path, not the
-owner EOA.
+owner EOA. Read `GET /config` on whichever host you point at for chain id and
+contract addresses; never hardcode them.
 
 ---
 
@@ -204,8 +213,25 @@ signed message. `PostOrderBody` additionally accepts the string forms
 (`"BUY"`, `"LIMIT"`, …) for `side`/`type`, but the *signature* is always over the
 numbers.
 
-`MARKET` orders carry `price: 0` (both in the signed message as `0n` and in the
-POST body as `0`).
+A `MARKET` order's `price` is its **slippage bound**, not a fill price: the worst
+price the order will accept — a CAP on a buy, a FLOOR on a sell. It is enforced
+twice, so it is not advisory: the engine breaks its match loop on it (an order
+whose depth sat outside the bound is cancelled `PRICE_THROUGH_LIMIT`, not
+`NO_LIQUIDITY`), and `UpDownSettlement.enterPosition` reverts `OrdersNotCrossed()`
+if a fill would cross it.
+
+`price: 0` is **rejected at submit** — *"Orders must specify a non-zero price.
+Market orders should be signed at the worst-acceptable slippage price."* There is
+no unbounded market order. Earlier versions of this document said MARKET orders
+carry `price: 0`; that was true of an older protocol and following it now
+produces an error on every order.
+
+Express the pad in **cents**, not as a percentage. A percentage bound is worth
+almost nothing at long-shot prices, which is where these markets spend their
+final minutes: 5% of an 8c option is 0.4c, against a book quoting a 7.39c
+spread — one production order missed a fill by 0.23c with depth to spare that
+way. `centsToBps` / `bpsToCents` are exported for the conversion; 100 bps is 1
+cent exactly.
 
 ### 3.4 Fees and `maxFee`
 
@@ -306,7 +332,7 @@ otherwise be replayable forever.
 
 ```ts
 import { UpDownHttpClient } from "@pulsepairs/sdk";
-const api = new UpDownHttpClient("https://api.demo-pulsepairs.rainwins.com");
+const api = new UpDownHttpClient("https://dev-api-updown.rain.trade");
 ```
 
 A thin, dependency-free wrapper over `fetch`. Trailing slashes on the base URL
@@ -331,7 +357,7 @@ runtimes) — they are not normalised.
 | `getVersion()` | `GET /version` | `Version` — `{ commit, bootedAt, env, nodeVersion }` |
 | `getHealth()` | `GET /health` | `{ status, relayer?, uptime? }` |
 | `getConfig()` | `GET /config` | `ApiConfig` — **fetch this first, never hardcode addresses** |
-| `getMarkets(opts?)` | `GET /markets` | `MarketListItem[]`; `opts.timeframe` ∈ `300 \| 900 \| 3600`, `opts.pair` ∈ `"BTC-USD" \| "ETH-USD"` |
+| `getMarkets(opts?)` | `GET /markets` | `MarketListItem[]`; `opts.timeframe` ∈ `300 \| 900` (60m retired 2026-08-18 — no new 3600s markets; the API still accepts `3600` and returns the historical ones), `opts.pair` ∈ `"BTC-USD" \| "ETH-USD"` |
 | `getMarket(address)` | `GET /markets/:address` | `MarketDetail` — list item + `timeRemainingSeconds` + top-of-book |
 | `getOrderbook(market)` | `GET /orderbook/:address` | `OrderBookFull` — full depth, both options, bids and asks |
 | `getBalance(wallet)` | `GET /balance/:wallet` | `Balance` — `available`, `inOrders`, `cachedBalance`, `withdrawNonce` |
@@ -428,8 +454,8 @@ the book asynchronously.
 ### `wsUrlFromHttpBase(httpBase)`
 
 ```ts
-wsUrlFromHttpBase("https://api.demo-pulsepairs.rainwins.com")
-// → "wss://api.demo-pulsepairs.rainwins.com/stream"
+wsUrlFromHttpBase("https://dev-api-updown.rain.trade")
+// → "wss://dev-api-updown.rain.trade/stream"
 ```
 
 Swaps `https:`→`wss:` / `http:`→`ws:`, forces the path to `/stream`, and strips
@@ -703,9 +729,14 @@ assertStakeBounds(amountAtomic: bigint, side?: "BUY" | "SELL"): void
 feeAtomic(notionalAtomic, priceBps, cfg): bigint
 
 MIN_STAKE_ATOMIC = 1_000_000n     // $1 of share FACE value (BUY only)
-MAX_STAKE_ATOMIC = 500_000_000n   // $500 of share FACE value
 ```
 
+> **`MAX_STAKE_ATOMIC` was removed in `0.8.0`** — the venue no longer caps order
+> size, so importing it is a compile error. If you were relying on it, pick your
+> own ceiling; nothing server-side will stop an oversized `amount` except your
+> own collateral (`CollateralGate` checks balance and allowance on-chain before
+> matching).
+
 Both `centsToBps` and `bpsToCents` are exclusive at both ends — 0¢ and 100¢ are
 not tradeable prices, and passing either throws.
 
@@ -721,8 +752,8 @@ Two things about the window that bite integrators:
   shares first (`cash / price`), which is always ≥ the cash figure, so a
   cash-denominated gate at $1 sits safely above this bound at every price.
 - **The minimum is entry-only.** Pass `side: "SELL"` for exits — a holder left
-  with 0.42 shares after a partial fill must be able to sell them. The maximum
-  still applies to both sides.
+  with 0.42 shares after a partial fill must be able to sell them. There is no
+  maximum on either side any more.
 
 > Changed 2026-07-23 (SDK 0.7.0): minimum was `5_000_000n` ($5, both sides).
 

package/README.md

@@ -1,8 +1,14 @@
 # @pulsepairs/sdk
 
-Standalone SDK for the **UpDown** (PulsePairs) up/down prediction markets —
+Standalone SDK for the **UpDown** up/down prediction markets —
 BTC-USD / ETH-USD, UP or DOWN, on 5-minute / 15-minute / 1-hour cycles.
 
+> **On the name:** the product is **UpDown**. "PulsePairs" is a retired name that
+> survives in two places for compatibility reasons only — this npm package's name
+> (`@pulsepairs/sdk`, renaming it would break every consumer) and two EIP-712 domain
+> strings that are hashed into signatures (`PulsePairs WebSocket Auth`,
+> `PulsePairsAuthDomain`). Neither can be changed without breaking deployed clients.
+
 This is the package [rain.trade](https://rain.trade) integrates to surface
 UpDown markets alongside Rain's own markets ("satellite" integration, Option A).
 It is deliberately **segregated** from `rain-sdk-v2`: bump this package's version
@@ -23,13 +29,20 @@ It gives you three things:
 > its units, its failure modes, the WS protocol, the full type surface and a
 > troubleshooting table — see **[`DOCUMENTATION.md`](./DOCUMENTATION.md)**.
 
-> **Live integration environment:** a public demo of the full stack (markets
-> cycling 24/7 on Arbitrum One, mock oracle, mintable test USDT) runs at
-> **https://demo-pulsepairs.rainwins.com** with the matcher API/WS at
-> **`https://api.demo-pulsepairs.rainwins.com`** (`wss://…/stream`). Every
-> example below targets it by default. Test funds: `POST /test/devmint`
-> (10k cap, 1 mint per address per 5 min — mint to the **smart-account**
-> address, not the owner EOA; it also seeds a little gas ETH).
+> **Live environments — there are two, both on Arbitrum One:**
+>
+> | | REST | WebSocket |
+> |---|---|---|
+> | **Dev** — mock oracle, mock USDT, faucet on | `https://dev-api-updown.rain.trade` | `wss://dev-api-updown.rain.trade/stream` |
+> | **Prod** — real Chainlink DON, real USDT0 | `https://prod-api-updown.rain.trade` | `wss://prod-api-updown.rain.trade/stream` |
+>
+> Examples below target **dev** by default — markets cycle 24/7 there and a
+> mistake costs play money. Test funds: `POST /test/devmint` (10k cap, 1 mint per
+> address per 5 min — mint to the **smart-account** address, not the owner EOA; it
+> also seeds a little gas ETH). The faucet 404s on prod.
+>
+> The older `demo-pulsepairs.rainwins.com` / `testnet-pulsepairs.rainwins.com`
+> hosts are retired; there is no Arbitrum Sepolia deployment.
 
 ---
 
@@ -96,15 +109,28 @@ await ensureSettlementAllowance({
 
 const maxFee = (amount * BigInt(cfg.platformFeeBps + cfg.makerFeeBps)) / 10000n; // peak fee
 const nonce = freshNonce();                           // CSPRNG; never Math.random/Date.now
+
+// A MARKET order's signed `price` is its SLIPPAGE BOUND — the worst price it
+// will accept — not a fill price. `price: 0` is REJECTED at submit ("Orders must
+// specify a non-zero price"), so there is no unbounded market order to sign.
+// Derive the bound from the current quote and pad it in CENTS: a percentage pad
+// is worth almost nothing at long-shot prices, where these markets spend their
+// final minutes (5% of an 8c option is 0.4c, against a 7.39c spread). 100 bps =
+// 1 cent exactly. On a BUY the bound is reference + pad (the most you will pay);
+// on a SELL it is reference − pad, because there the price is a FLOOR.
+const reference = live.upPrice;                       // bps; use downPrice for DOWN
+if (reference === null) throw new Error("no quote to bound against — refusing to guess");
+const price = BigInt(Math.min(9999, Math.max(1, reference + 5 * 100)));  // +5c
+
 const typedData = buildOrderTypedData({
   cfg, settlementAddress,
   message: { maker: account.address, market: BigInt(marketId), option: BigInt(Option.UP),
-    side: OrderSide.BUY, type: OrderType.MARKET, price: 0n, amount, maxFee, nonce,
+    side: OrderSide.BUY, type: OrderType.MARKET, price, amount, maxFee, nonce,
     expiry: BigInt(live.endTime) },
 });
 const signature = await account.signTypedData(typedData);
 await api.postOrder({ maker: account.address, market: live.address, option: Option.UP,
-  side: OrderSide.BUY, type: OrderType.MARKET, price: 0, amount: amount.toString(),
+  side: OrderSide.BUY, type: OrderType.MARKET, price: Number(price), amount: amount.toString(),
   maxFee: maxFee.toString(), nonce: Number(nonce), expiry: live.endTime, signature });
 ```
 
@@ -330,7 +356,7 @@ number. `getPnl` assembles one, marking each position:
   flagged `markSource: "cost"` so you can tell it apart).
 
 ```ts
-const client = new UpDownHttpClient("https://api.demo-pulsepairs.rainwins.com");
+const client = new UpDownHttpClient("https://dev-api-updown.rain.trade");
 
 const pnl = await client.getPnl(wallet, { includeFees: true });
 console.log(pnl.unrealizedPnlUsdt, pnl.roiPct); // e.g. -3, -30

package/dist/eip712.d.ts

@@ -225,19 +225,24 @@ export declare function bpsToCents(bps: number): number;
  * 51¢. Lowered from $5 → $1 on 2026-07-23 (Polymarket parity).
  */
 export declare const MIN_STAKE_ATOMIC = 1000000n;
-export declare const MAX_STAKE_ATOMIC = 500000000n;
 /** Parse a USD string (e.g. "5", "5.50", "12.345") into atomic USDT.
  *  Rejects negatives + non-finite. */
 export declare function parseStake(usd: string | number): bigint;
 /**
  * Defense-in-depth stake clamp. Throws if `amountAtomic` (share face value)
- * is outside the documented `$1 ≤ stake ≤ $500` window; the backend applies
- * the same window at the API boundary. SDK callers should validate before
- * signing so a bad stake never produces a signed payload at all.
+ * is below the documented `$1` entry floor; the backend applies the same
+ * floor at the API boundary. SDK callers should validate before signing so a
+ * bad stake never produces a signed payload at all.
  *
  * Pass `side: "SELL"` for exits: the minimum is ENTRY-ONLY, so a holder left
  * with a sub-$1 position (routine after a partial fill) can always sell it.
  * The default stays "BUY" so existing callers keep the strict branch.
+ *
+ * 2026-08-03: the $500 ceiling was REMOVED (backend `lib/stakeBounds.ts` did
+ * the same). Size is bounded by collateral — the venue's pre-match gate reads
+ * balance AND allowance on-chain and refuses a cross it cannot settle — so the
+ * cap was never what limited risk, only what limited legitimate size. Callers
+ * upgrading from <=0.7.0 will find previously-rejected amounts now sign.
  */
 export declare function assertStakeBounds(amountAtomic: bigint, side?: "BUY" | "SELL"): void;
 /**

package/dist/eip712.js

@@ -227,7 +227,6 @@ export function bpsToCents(bps) {
  * 51¢. Lowered from $5 → $1 on 2026-07-23 (Polymarket parity).
  */
 export const MIN_STAKE_ATOMIC = 1000000n;
-export const MAX_STAKE_ATOMIC = 500000000n;
 /** Parse a USD string (e.g. "5", "5.50", "12.345") into atomic USDT.
  *  Rejects negatives + non-finite. */
 export function parseStake(usd) {
@@ -239,21 +238,24 @@ export function parseStake(usd) {
 }
 /**
  * Defense-in-depth stake clamp. Throws if `amountAtomic` (share face value)
- * is outside the documented `$1 ≤ stake ≤ $500` window; the backend applies
- * the same window at the API boundary. SDK callers should validate before
- * signing so a bad stake never produces a signed payload at all.
+ * is below the documented `$1` entry floor; the backend applies the same
+ * floor at the API boundary. SDK callers should validate before signing so a
+ * bad stake never produces a signed payload at all.
  *
  * Pass `side: "SELL"` for exits: the minimum is ENTRY-ONLY, so a holder left
  * with a sub-$1 position (routine after a partial fill) can always sell it.
  * The default stays "BUY" so existing callers keep the strict branch.
+ *
+ * 2026-08-03: the $500 ceiling was REMOVED (backend `lib/stakeBounds.ts` did
+ * the same). Size is bounded by collateral — the venue's pre-match gate reads
+ * balance AND allowance on-chain and refuses a cross it cannot settle — so the
+ * cap was never what limited risk, only what limited legitimate size. Callers
+ * upgrading from <=0.7.0 will find previously-rejected amounts now sign.
  */
 export function assertStakeBounds(amountAtomic, side = "BUY") {
     if (side === "BUY" && amountAtomic < MIN_STAKE_ATOMIC) {
         throw new Error(`stake below $${Number(MIN_STAKE_ATOMIC) / 1e6} minimum`);
     }
-    if (amountAtomic > MAX_STAKE_ATOMIC) {
-        throw new Error(`stake above $${Number(MAX_STAKE_ATOMIC) / 1e6} maximum`);
-    }
 }
 /**
  * Probability-weighted fee in atomic USDT. Mirrors the backend / contract

package/dist/http.d.ts

@@ -10,8 +10,20 @@ export declare class UpDownHttpClient {
         uptime?: number;
     }>;
     getConfig(): Promise<ApiConfig>;
+    /**
+     * List markets.
+     *
+     * `timeframe` narrowed from `300 | 900 | 3600` to `300 | 900`: 60m was
+     * disabled on the cyclers 2026-08-18, so no new 3600s markets exist to list.
+     *
+     * The narrowing is a COMPILE-TIME steer, not a runtime break. The backend
+     * still accepts `?timeframe=3600` and returns the historical 60m markets, so
+     * a caller pinned to an older SDK keeps working and anything reading history
+     * can pass 3600 through a cast. New code gets a type error instead of a
+     * silently empty list, which is the failure that is hard to diagnose.
+     */
     getMarkets(opts?: {
-        timeframe?: 300 | 900 | 3600;
+        timeframe?: 300 | 900;
         pair?: PairSymbol;
     }): Promise<MarketListItem[]>;
     getMarket(address: string): Promise<MarketDetail>;

package/dist/http.js

@@ -46,6 +46,18 @@ export class UpDownHttpClient {
         const res = await fetch(buildUrl(this.baseUrl, "/config"));
         return parseJson(res);
     }
+    /**
+     * List markets.
+     *
+     * `timeframe` narrowed from `300 | 900 | 3600` to `300 | 900`: 60m was
+     * disabled on the cyclers 2026-08-18, so no new 3600s markets exist to list.
+     *
+     * The narrowing is a COMPILE-TIME steer, not a runtime break. The backend
+     * still accepts `?timeframe=3600` and returns the historical 60m markets, so
+     * a caller pinned to an older SDK keeps working and anything reading history
+     * can pass 3600 through a cast. New code gets a type error instead of a
+     * silently empty list, which is the failure that is hard to diagnose.
+     */
     async getMarkets(opts) {
         const res = await fetch(buildUrl(this.baseUrl, "/markets", {
             timeframe: opts?.timeframe,

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 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, freshNonce, 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 { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_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, DEFAULT_APPROVAL_AMOUNT, type EnsureAllowanceResult, } from "./approve.js";
 export { readOnChainHolderShares, reconcileFills, reportedFromPositions, type OnChainHolderShares, type ShareReconciliation, type ReconcileStatus, type FillReconciliationReport, } from "./reconcile.js";

package/dist/index.js

@@ -2,7 +2,11 @@
 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, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, MIN_STAKE_ATOMIC, MAX_STAKE_ATOMIC, } from "./eip712.js";
+export { ORDER_TYPES, CANCEL_TYPES, WS_AUTH_TYPES, buildOrderTypedData, buildCancelTypedData, buildWsAuthTypedData, freshSessionId, freshNonce, domainForSettlement, findPairBySettlement, parseCompositeMarketKey, centsToBps, bpsToCents, parseStake, assertStakeBounds, feeAtomic, 
+// MAX_STAKE_ATOMIC was removed in 0.8.0 — the venue no longer caps order
+// size. Importing it is now a compile error rather than a silent behaviour
+// change, which is the intended way for a consumer to learn the cap is gone.
+MIN_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

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * 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
+ * one-to-one. Keep field names and casing in sync with `docs/archive/api-superseded-2026-08-12.md`; if a
  * shape drifts, update both in the same commit.
  */
 export type PairSymbol = "BTC-USD" | "ETH-USD";

package/dist/types.js

@@ -1,6 +1,6 @@
 /**
  * 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
+ * one-to-one. Keep field names and casing in sync with `docs/archive/api-superseded-2026-08-12.md`; if a
  * shape drifts, update both in the same commit.
  */
 /** Numeric enum values match the backend's on-chain encoding. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pulsepairs/sdk",
-  "version": "0.7.0",
-  "description": "Standalone SDK for the UpDown (PulsePairs) up/down prediction markets \u2014 matcher REST/WS client, EIP-712 order signing, trade-math, and Alchemy Account Kit (smart-account) order signing for rain.trade integration.",
+  "version": "0.8.0",
+  "description": "Standalone SDK for the UpDown (PulsePairs) up/down prediction markets — matcher REST/WS client, EIP-712 order signing, trade-math, and Alchemy Account Kit (smart-account) order signing for rain.trade integration.",
   "license": "UNLICENSED",
   "type": "module",
   "main": "dist/index.js",
@@ -62,6 +62,10 @@
     }
   },
   "devDependencies": {
+    "@aa-sdk/core": "^4.88.5",
+    "@account-kit/infra": "^4.88.5",
+    "@account-kit/smart-contracts": "^4.88.5",
+    "@account-kit/wallet-client": "^4.88.5",
     "@types/node": "^22.10.0",
     "typescript": "^5.9.3",
     "viem": "^2.47.0"