@pulsepairs/sdk 0.5.2 → 0.6.0

package/DOCUMENTATION.md

@@ -0,0 +1,1487 @@
+# `@pulsepairs/sdk` — Reference Documentation
+
+**Version:** 0.6.0 · **License:** UNLICENSED · **Runtime:** Node ≥ 18 or a modern browser
+
+Complete reference for the UpDown (PulsePairs) 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
+exhaustive reference — read it when you need to know exactly what a function
+returns, what unit a number is in, or why a signature is being rejected.
+
+---
+
+## Table of contents
+
+1. [What this SDK is](#1-what-this-sdk-is)
+2. [Installation and module layout](#2-installation-and-module-layout)
+3. [Core concepts](#3-core-concepts)
+   - [3.1 Units — the load-bearing table](#31-units--the-load-bearing-table)
+   - [3.2 Market identity: composite keys](#32-market-identity-composite-keys)
+   - [3.3 Options, sides, order types](#33-options-sides-order-types)
+   - [3.4 Fees and `maxFee`](#34-fees-and-maxfee)
+   - [3.5 Match geometry: NORMAL vs MINT vs MERGE](#35-match-geometry-normal-vs-mint-vs-merge)
+4. [The order lifecycle](#4-the-order-lifecycle)
+5. [`UpDownHttpClient` — REST client](#5-updownhttpclient--rest-client)
+6. [`UpDownWsClient` — WebSocket client](#6-updownwsclient--websocket-client)
+7. [EIP-712 signing (`src/eip712.ts`)](#7-eip-712-signing-srceip712ts)
+8. [Trade math helpers](#8-trade-math-helpers)
+9. [PnL (`src/pnl.ts`)](#9-pnl-srcpnlts)
+10. [ERC-20 allowance (`src/approve.ts`)](#10-erc-20-allowance-srcapprovets)
+11. [On-chain reconciliation (`src/reconcile.ts`)](#11-on-chain-reconciliation-srcreconcilets)
+12. [Account Kit / smart-account signing (`src/accountKit.ts`)](#12-account-kit--smart-account-signing-srcaccountkitts)
+13. [Raw-tx tier — bring your own AA send path](#13-raw-tx-tier--bring-your-own-aa-send-path)
+14. [L2 HMAC auth (`src/auth.ts`)](#14-l2-hmac-auth-srcauthts)
+15. [Type reference](#15-type-reference)
+16. [Security checklist for a funded key](#16-security-checklist-for-a-funded-key)
+17. [Troubleshooting](#17-troubleshooting)
+18. [Testing and schema-drift guards](#18-testing-and-schema-drift-guards)
+19. [Compatibility notes](#19-compatibility-notes)
+
+---
+
+## 1. What this SDK is
+
+UpDown is a binary prediction market: *will BTC-USD (or ETH-USD) be UP or DOWN at
+the end of this 5-minute / 15-minute / 1-hour cycle?* Trading is an **off-chain
+central limit order book** (the "matcher"); settlement is **on-chain** on
+Arbitrum.
+
+The SDK gives you three layers, usable independently:
+
+| Layer | Modules | What it does |
+|---|---|---|
+| **Transport** | `http.ts`, `ws.ts` | Typed REST + WebSocket clients for the matcher |
+| **Signing / math** | `eip712.ts`, `auth.ts`, `pnl.ts` | EIP-712 payloads, fee/stake/price math, PnL — all pure, transport-free |
+| **Custody** | `accountKit.ts`, `approve.ts`, `reconcile.ts` | Smart-account (ERC-1271) signing, allowance management, on-chain audit |
+
+The critical thing to internalise: **placing an order is not a transaction.** It
+is an EIP-712 signature POSTed to the matcher over HTTP. The relayer submits the
+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
+
+A full stack runs 24/7 on Arbitrum One with a mock oracle and mintable test USDT:
+
+```
+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)
+```
+
+Mint to the **smart-account** address if you are on the Account Kit path, not the
+owner EOA.
+
+---
+
+## 2. Installation and module layout
+
+```bash
+npm install @pulsepairs/sdk viem
+```
+
+`viem` is a **required** peer dependency (`^2.21.0`).
+
+For smart-account signing, add the optional peers (the same versions rain.trade
+already ships):
+
+```bash
+npm install @account-kit/wallet-client@^4.88 @account-kit/infra@^4.88 \
+            @account-kit/smart-contracts@^4.88 @aa-sdk/core@^4.88
+```
+
+These four are **lazy-imported**. A pure-EOA bot never loads them, and merely
+`import`ing the SDK does not require them to be installed — they are only
+resolved when you construct and connect `UpDownAccountKitSigner` or call a
+raw-tx-tier builder.
+
+### Entry points
+
+The package is ESM-only (`"type": "module"`), side-effect free, and ships four
+subpath exports:
+
+```ts
+import { /* everything */ }        from "@pulsepairs/sdk";
+import { UpDownWsClient }          from "@pulsepairs/sdk/ws";
+import { buildOrderTypedData }     from "@pulsepairs/sdk/eip712";
+import { UpDownHttpClient }        from "@pulsepairs/sdk/http";
+```
+
+The root export re-exports everything; the subpaths exist for callers who want
+to pull in a single module. There is no `./pnl` or `./accountKit` subpath — use
+the root export for those.
+
+### Source layout
+
+```
+src/
+  index.ts        barrel — the full public surface
+  types.ts        wire shapes mirroring the backend's REST/WS responses
+  http.ts         UpDownHttpClient + wsUrlFromHttpBase
+  ws.ts           UpDownWsClient (auto-reconnect, auth handshake)
+  eip712.ts       typed-data builders, nonce/session-id, price/stake/fee math
+  auth.ts         L2 HMAC credentials + ClobAuth typed data (Node-only)
+  approve.ts      ensureSettlementAllowance (EOA path)
+  pnl.ts          BigInt-exact PnL math
+  reconcile.ts    on-chain userShares vs matcher-reported diff
+  accountKit.ts   Alchemy SCA signer + raw-tx tier
+examples/         runnable scripts (NOT shipped in the npm tarball)
+scripts/          the test suite (`npm test`)
+```
+
+> **Note:** `files: ["dist", "README.md"]` — if you installed from npm without
+> repo access, `examples/` is not on disk. The safe patterns are inlined in the
+> README and in this document on purpose.
+
+---
+
+## 3. Core concepts
+
+### 3.1 Units — the load-bearing table
+
+Getting a unit wrong here produces a silently-wrong number or a signature the
+chain rejects. Nothing in this table is negotiable.
+
+| Quantity | Unit | Scale | Appears as |
+|---|---|---|---|
+| `amount`, `shares`, `costBasis`, `markValue`, fees | **atomic USDT** | 1 USDT = `1_000_000` (6 dp) | decimal `string` in JSON, `bigint` in signed messages |
+| `price`, `avgPrice`, `markBps`, `takerPrice` | **basis points** | `10000` = full face = $1.00 | `number` |
+| `platformFeeBps`, `makerFeeBps`, `dmmRebateBps` | basis points | `10000` = 100% | `number` |
+| `nonce`, `expiry` (in `OrderRow`) | uint256 | — | JSON **string** (precision) |
+| `nonce` (in `PostOrderBody`) | uint48-ish | must stay under 2^53 | JSON `number` |
+| `startTime`, `endTime`, `expiry` | unix **seconds** | — | `number` / `bigint` |
+| `option` | enum | `1` = UP, `2` = DOWN | `number` |
+
+**Shares ≡ face value.** A share's atomic count *is* the USDT it redeems for if
+it wins. 5,000,000 shares of UP redeem for 5 USDT if UP wins, and 0 if it loses.
+That identity is what makes `markValueAtomic(shares, 10000) === shares` correct.
+
+**Prices are bps, not 1e18.** 55¢ is `5500`, not `0.55e18`. Partial cents are
+legal on the wire — 49.5¢ is `4950`. The UI often clamps to whole cents; the
+book does not.
+
+**Money math is BigInt.** Every atomic value crossing the SDK's own math stays a
+`bigint` and is returned as a decimal string. The `*Usdt` floats and `roiPct`
+are derived once at the end, for display only. Never feed a display float back
+into money math.
+
+### 3.2 Market identity: composite keys
+
+A market is identified two different ways depending on where you are:
+
+```
+composite key   0xBF119B…53ed-1234        ← REST paths, POST body `market`, WS channels
+on-chain id     1234n                     ← the signed `Order.market` (uint256)
+```
+
+`parseCompositeMarketKey` splits them:
+
+```ts
+const parsed = parseCompositeMarketKey(market.address);
+// → { settlementAddress: "0xbf119b…53ed", marketId: "1234" } | null
+if (!parsed) throw new Error(`bad composite key: ${market.address}`);
+```
+
+Note the returned `settlementAddress` is **lowercased**. Use it to look up the
+EIP-712 domain (§7), and use `BigInt(parsed.marketId)` as the signed
+`Order.market`. Putting the composite string into the signed message, or the
+bare id into the POST body, are both rejections.
+
+### 3.3 Options, sides, order types
+
+```ts
+Option.UP   === 1        Option.DOWN === 2       // NOT 0/1
+OrderSide.BUY  === 0     OrderSide.SELL === 1
+OrderType.LIMIT === 0    OrderType.MARKET === 1
+OrderType.POST_ONLY === 2  OrderType.IOC === 3
+```
+
+These numeric values match the on-chain encoding — they are what goes in the
+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`).
+
+### 3.4 Fees and `maxFee`
+
+The backend runs a **probability-weighted** fee model: a fill at price `p` (bps)
+pays
+
+```
+effectiveBps = totalBps × 4 × p × (10000 − p) / 10000²
+fee          = notional × effectiveBps / 10000
+```
+
+where `totalBps = platformFeeBps + makerFeeBps`. The weight peaks at 50¢
+(`4 × 0.5 × 0.5 = 1`, so `effectiveBps = totalBps`) and falls to zero at either
+extreme — cheap tails, expensive coin-flips. `feeAtomic()` implements exactly
+this, and falls back to flat `totalBps` if `cfg.feeModel` is set to anything
+other than `"probability-weighted"`.
+
+**`maxFee` is mandatory on every order** (Hacken finding F-2026-17731). It sits
+between `amount` and `nonce` in the signed `Order`, and the contract's
+`ORDER_TYPEHASH` includes it — omit it and you produce a signature the on-chain
+`SignatureChecker` rejects, so the fill reverts. Always sign the **peak** fee:
+
+```ts
+const maxFee = (amount * BigInt(cfg.platformFeeBps + cfg.makerFeeBps)) / 10000n;
+```
+
+Signing the peak means a legitimate probability-weighted fill can never breach
+the cap (`FeeExceedsTakerCap`). The contract enforces the *actual* cumulative fee
+under this cap across partial fills, so a generous cap costs you nothing.
+
+The same value must appear in the POST body as a decimal string. If the two
+disagree by one atomic unit, signature recovery fails.
+
+### 3.5 Match geometry: NORMAL vs MINT vs MERGE
+
+The book supports complementary matching — "buy UP" and "buy DOWN" can cross by
+**minting a set** rather than transferring existing shares. That means a `Trade`
+row's two legs may be on *opposite options*, and it changes how you read prices.
+
+| `matchType` | Legs | `price` field is… | Taker executed at |
+|---|---|---|---|
+| `NORMAL` | same option, buyer ↔ seller | the execution price | `price` |
+| `MINT` | opposite options, both buying | the resting **maker's** price | `10000 − price` |
+| `MERGE` | opposite options, both selling | the resting **maker's** price | `10000 − price` |
+
+On a `Trade` row:
+
+- `option` is the **taker's** option. The maker leg is the opposite option on
+  MINT/MERGE.
+- `buyer` is the aggressor on MINT/MERGE (a buyer on MINT, a *seller* on MERGE);
+  `seller` is the resting maker.
+- `price` is the **maker's** pegged price. Rendering a wallet's own taker fill
+  with this number is the single most common display bug in this system.
+
+Always use the helper:
+
+```ts
+import { takerPriceBps } from "@pulsepairs/sdk";
+
+const shown = takerPriceBps(trade);   // trade.takerPrice, else 10000 − price on MINT/MERGE, else price
+```
+
+`matchType` and `takerPrice` are optional on the type so a pre-2026-07-17 backend
+(which omits them) degrades instead of breaking; the helper's fallback covers
+that case.
+
+---
+
+## 4. The order lifecycle
+
+```
+ 1. GET /config                       → chainId, addresses, fee bps, per-pair EIP-712 domains
+ 2. GET /markets?pair&timeframe       → find an ACTIVE market, take its composite address
+ 3. parseCompositeMarketKey(address)  → { settlementAddress, marketId }
+ 4. ensureSettlementAllowance(...)    → ONE on-chain tx, EOA path only, idempotent
+    (Account Kit path: ak.onboard(...) — deploy + approve + session in one UserOp)
+ 5. maxFee = amount × totalBps / 10000
+    nonce  = freshNonce()
+ 6. buildOrderTypedData({ cfg, settlementAddress, message })
+ 7. sign  → EOA: account.signTypedData(td)
+           SCA: ak.signTypedDataBare(td)  /  signWithOrderSession({ ... })
+ 8. POST /orders  { maker, market: <composite>, …, maxFee, nonce, expiry, signature }
+ 9. watch: WS `orders:<wallet>` (push) or GET /orders/:wallet (poll)
+10. cancel: buildCancelTypedData → sign → DELETE /orders/:id
+```
+
+Steps 1–4 are once per session. Steps 5–8 are per order and involve **no chain
+interaction at all**.
+
+`expiry` on an order is normally the market's `endTime` — an order cannot
+outlive its market. The cancel signature carries its own, much shorter expiry
+(60s is typical) plus its own nonce, because a captured cancel signature would
+otherwise be replayable forever.
+
+---
+
+## 5. `UpDownHttpClient` — REST client
+
+```ts
+import { UpDownHttpClient } from "@pulsepairs/sdk";
+const api = new UpDownHttpClient("https://api.demo-pulsepairs.rainwins.com");
+```
+
+A thin, dependency-free wrapper over `fetch`. Trailing slashes on the base URL
+are normalised. Query params that are `undefined` or `""` are omitted.
+
+### Error behaviour
+
+Every method routes through one parser. On a non-2xx response it throws
+`new Error(msg)` where `msg` is the JSON body's `error` field when present,
+otherwise the raw body text, otherwise `res.statusText`. An empty 2xx body
+resolves to `undefined`.
+
+There is **no** built-in retry, timeout, backoff, or auth header injection. If
+you need those, wrap the client or supply your own `fetch` at the platform level.
+Network-level failures surface as whatever `fetch` throws (`TypeError` on most
+runtimes) — they are not normalised.
+
+### Read methods
+
+| Method | Endpoint | Returns |
+|---|---|---|
+| `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"` |
+| `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` |
+| `getPositions(wallet)` | `GET /positions/:wallet` | `Position[]` |
+| `getPositionsWithRealized(wallet)` | `GET /positions/:wallet?includeRealized=1` | `{ positions: Position[]; realizedFromSells: string }` — a pre-0.6 backend's bare array degrades to `realizedFromSells: "0"` |
+| `getTrades(wallet, opts?)` | `GET /trades/:wallet` | `Trade[]`; `opts.limit`, `opts.offset` |
+| `getOrders(wallet, opts?)` | `GET /orders/:wallet` | `OrdersResponse`; `opts.status` is an array, sent as repeated `?status=` params |
+| `getStats()` | `GET /stats` | `Stats` — `totalVolume`, `activeMarketsCount`, `totalTraders` |
+| `getPnl(wallet, opts?)` | *(composite)* | `PortfolioPnl` — see below |
+
+`getConfig()` is the source of truth for `chainId`, `usdtAddress`,
+`relayerAddress`, fee bps, `usdtDecimals`, and the per-pair `settlementAddress` +
+EIP-712 domain. Hardcoding any of these into a process that holds a funded key is
+how you end up signing for the wrong chain.
+
+Note `ApiConfig.settlementAddress` and `ApiConfig.eip712` (top-level) are
+**deprecated** — they carry the *first* pair's values for one release cycle of
+overlap. Use `cfg.pairs[]` with `findPairBySettlement` / `domainForSettlement`.
+
+### `getPnl(wallet, opts?)`
+
+Not a backend endpoint — a client-side composition:
+
+1. `GET /positions/:wallet?includeRealized=1` (via `getPositionsWithRealized`) —
+   yields the open positions plus `realizedFromSells`, the wallet's realized P&L
+   from manual sells (atomic USDT string, fee-exclusive, average-cost; includes
+   positions sold fully to zero, which `/positions` alone omits).
+2. One `GET /markets/:address` per **distinct** market (deduped, issued in
+   parallel). A failed read degrades *that position* to a cost-basis mark rather
+   than aborting the report.
+3. Optionally `GET /trades/:wallet?limit=500` when `opts.includeFees` is set.
+4. `computePortfolioPnl(...)` over the result.
+
+```ts
+const pnl = await api.getPnl(wallet, { includeFees: true, usdtDecimals: 6 });
+console.log(pnl.unrealizedPnlUsdt, pnl.roiPct);
+for (const p of pnl.positions) console.log(p.optionLabel, p.markSource, p.unrealizedPnlUsdt);
+```
+
+An empty position list short-circuits to a zeroed report with no market reads.
+`includeFees` defaults to `false` because it costs an extra request; fees are
+*reported*, never netted into `unrealizedPnl` (cost basis is fee-exclusive). The
+500-trade cap on the fee query means a very high-volume wallet's `fees` line is a
+partial tally.
+
+### Write methods
+
+#### `postOrder(body: PostOrderBody)`
+
+```ts
+const result = await api.postOrder({
+  maker: account.address,
+  market: live.address,          // COMPOSITE key — routing only
+  option: Option.UP,             // 1 | 2
+  side: OrderSide.BUY,           // 0 | 1, or "BUY" | "SELL"
+  type: OrderType.LIMIT,         // 0..3, or "LIMIT" | "MARKET" | "POST_ONLY" | "IOC"
+  price: 5500,                   // bps; 0 for MARKET
+  amount: amount.toString(),     // atomic USDT
+  maxFee: maxFee.toString(),     // atomic USDT — MUST equal the signed value
+  nonce: Number(nonce),          // JSON number — must equal the signed value
+  expiry: live.endTime,          // unix seconds
+  signature,
+});
+// → { id, status, market, option, side, type, price, amount, createdAt }
+```
+
+The backend re-verifies the signature against the per-pair domain on receipt.
+Note the asymmetry: `nonce` here is a JSON **number** (hence `freshNonce()`'s
+48-bit design, so `Number(nonce)` is lossless), while `OrderRow.nonce` coming
+*back* is a **string** to preserve full uint256 precision.
+
+#### `cancelOrder(orderId, body: CancelOrderBody)`
+
+```ts
+const cancelNonce  = freshNonce();
+const cancelExpiry = BigInt(Math.floor(Date.now() / 1000) + 60);
+const td = buildCancelTypedData({
+  cfg, settlementAddress,
+  message: { maker: account.address, orderId: placed.id, nonce: cancelNonce, expiry: cancelExpiry },
+});
+const res = await api.cancelOrder(placed.id, {
+  maker: account.address,
+  signature: await account.signTypedData(td),
+  nonce:  cancelNonce.toString(),   // strings preserve uint256 precision
+  expiry: cancelExpiry.toString(),
+});
+// → { id, status: "CANCEL_PENDING" | … }
+```
+
+The backend caches `(maker, nonce)` for 5 minutes and rejects past-expiry
+signatures. `CANCEL_PENDING` is the normal immediate response — the order leaves
+the book asynchronously.
+
+### `wsUrlFromHttpBase(httpBase)`
+
+```ts
+wsUrlFromHttpBase("https://api.demo-pulsepairs.rainwins.com")
+// → "wss://api.demo-pulsepairs.rainwins.com/stream"
+```
+
+Swaps `https:`→`wss:` / `http:`→`ws:`, forces the path to `/stream`, and strips
+any query and hash.
+
+---
+
+## 6. `UpDownWsClient` — WebSocket client
+
+```ts
+import { UpDownWsClient, wsUrlFromHttpBase } from "@pulsepairs/sdk";
+
+const ws = new UpDownWsClient(wsUrlFromHttpBase(API), (msg) => {
+  // msg: { type: string; channel?: string; data?: unknown }
+});
+```
+
+The client uses the global `WebSocket`. That is native in browsers and in Node
+≥ 22; on Node 18–21 either run with `--experimental-websocket` or polyfill
+`globalThis.WebSocket` (e.g. from `ws`) before constructing.
+
+### Channels
+
+| Channel | Auth | Payload |
+|---|---|---|
+| `markets` | public | market list updates |
+| `orderbook:<compositeKey>` | public | book deltas for one market |
+| `trades:<compositeKey>` | public | fills for one market |
+| `orders:<wallet>` | **signed** | your order status transitions |
+| `balance:<wallet>` | **signed** | your balance changes |
+
+Wallet and market keys in channel names are **lowercased**. On the smart-account
+path the private channels are keyed by the **SCA** address (the trading
+identity), not the owner EOA.
+
+### Public connection
+
+```ts
+ws.connectPublic(["markets", `orderbook:${market.address.toLowerCase()}`]);
+```
+
+Sends `{ type: "subscribe", channels }` immediately on open. No signature.
+
+### Authenticated connection
+
+`orders:*` and `balance:*` are gated behind a verified EIP-712 `WsAuth`
+signature. An unauthenticated client that asks for them has those subscriptions
+silently dropped by the server.
+
+```ts
+ws.connectAuthed({
+  channels: [`orders:${wallet.toLowerCase()}`, "markets"],   // public channels may be mixed in
+  signAuth: async () => {
+    const timestamp = BigInt(Math.floor(Date.now() / 1000));
+    const sessionId = freshSessionId();
+    const td = buildWsAuthTypedData({ cfg, wallet, timestamp, sessionId });
+    const signature = await account.signTypedData(td);
+    return { wallet, timestamp, sessionId, signature };
+  },
+  onAuthError: (reason) => console.error("ws auth failed:", reason),
+});
+```
+
+On the Account Kit path, `ak.signWsAuth(cfg.chainId)` returns the whole
+`WsAuthCredentials` object for you:
+
+```ts
+ws.connectAuthed({ channels: [`orders:${sca.toLowerCase()}`], signAuth: () => ak.signWsAuth(cfg.chainId) });
+```
+
+### Handshake protocol
+
+```
+client → { type: "auth", wallet, timestamp, sessionId, signature }
+server → { type: "auth_ok", wallet, token, expiresAt }        (token TTL 24h)
+       | { type: "auth_error" }                               (no reason — anti-probe)
+
+client → { type: "auth", token }                              (replay on reconnect)
+server → { type: "auth_ok", wallet, token }
+```
+
+The server accepts a `timestamp` within **±60s** of its own clock and rejects
+`sessionId` reuse inside that window — so generate a fresh one with
+`freshSessionId()` for every signed handshake (token replay carries no
+sessionId).
+
+The client caches the `auth_ok` token and its `expiresAt` internally and replays
+it on reconnect, so your `signAuth` callback is only re-invoked when the cache is
+empty, expired, or rejected. It is therefore safe for that callback to sign
+fresh every time it is called. You may also pre-seed a token by returning one on
+`WsAuthCredentials.token` — the client tries replay first and falls back to a
+fresh sign if the server rejects it.
+
+**`auth_ok` and `auth_error` are consumed internally and are NOT delivered to
+your `onMessage` handler.** Everything else is.
+
+### State machine and reconnect
+
+```
+idle → authenticating → subscribing → live
+                     ↘ unauthed-failure   (terminal — no further reconnects)
+```
+
+Reconnect backoff on an unexpected close is `1s, 2s, 4s, 8s, 16s, 30s`, then
+capped at 30s; after 12 attempts it is a flat 30s. The counter resets on a
+successful open. Sockets superseded by a newer connect are defensively torn down,
+and their late `onopen`/`onmessage`/`onclose` events are ignored — a rapid
+connect/reconnect churn cannot leave a zombie socket streaming.
+
+Two cases deliberately **stop** reconnecting: an explicit `disconnect()`, and a
+terminal auth failure (a freshly-signed signature rejected, or `signAuth`
+throwing). The second avoids a hot loop against a wallet that keeps declining.
+
+### Dynamic subscriptions
+
+```ts
+ws.subscribe([`orderbook:${key}`, `trades:${key}`]);   // adds; sends immediately if OPEN
+ws.unsubscribe([`trades:${key}`]);                      // removes; won't be replayed
+ws.disconnect();                                        // terminal; stops reconnect
+```
+
+Both merge into the connect-time channel set, so additions survive a reconnect
+(and are replayed *after* the auth handshake on an authed client). Duplicate adds
+and unknown removes are no-ops. Safe to call before the socket opens — the
+channels queue and go out on connect.
+
+Private channels still require the client to have been created via
+`connectAuthed`; adding `orders:*` to a public client does not authenticate it.
+
+### Deprecated
+
+`connect(payload: SubscribePayload)` routes to `connectPublic(payload.channels)`.
+Its `wallet` field is **ignored** — pre-PR-19 the server auto-attached
+`orders:<wallet>` to anonymous clients, and that gate is now closed. Migrate to
+`connectPublic` / `connectAuthed`.
+
+### Field-name gotcha
+
+The WS `order_update` payload uses **`orderType`**; the REST `OrderRow` uses
+**`type`**. Same value, different key.
+
+---
+
+## 7. EIP-712 signing (`src/eip712.ts`)
+
+### Domain resolution
+
+There is one settlement contract (and therefore one EIP-712 domain) **per pair**.
+Today's deployment makes `cfg.pairs` a one-entry array, but code that hardcodes
+`pairs[0]` breaks silently the moment a second settlement deploys. Always look up
+by address:
+
+```ts
+findPairBySettlement(cfg.pairs, settlementAddress): PairConfig | null
+domainForSettlement(cfg, settlementAddress): Eip712Domain     // throws if unresolvable
+```
+
+`findPairBySettlement` is case-insensitive and returns `null` for the zero
+address or an empty string. `domainForSettlement` prefers `cfg.pairs[]`, falls
+back to the deprecated top-level `cfg.eip712.domain` **only** when that domain's
+`verifyingContract` matches the requested settlement, and otherwise throws with
+the available pairs listed — a misconfiguration produces a loud error rather
+than a silently-wrong signature.
+
+The order domain is `{ name: "UpDown Exchange", version, chainId, verifyingContract: <settlement> }`
+as served by `/config`. Never hand-build it.
+
+### `ORDER_TYPES` / `buildOrderTypedData`
+
+```ts
+Order {
+  maker   address
+  market  uint256     // BARE marketId, not the composite key
+  option  uint256     // 1 = UP, 2 = DOWN
+  side    uint8       // 0 = BUY, 1 = SELL
+  type    uint8       // 0 = LIMIT, 1 = MARKET, 2 = POST_ONLY, 3 = IOC
+  price   uint256     // bps; 0 for MARKET
+  amount  uint256     // atomic USDT
+  maxFee  uint256     // atomic USDT — F-2026-17731
+  nonce   uint256
+  expiry  uint256     // unix seconds
+}
+```
+
+Field order is part of the type hash. It must match `ORDER_TYPEHASH` in
+`UpDownSettlement.sol` exactly — `maxFee` sits between `amount` and `nonce`.
+
+```ts
+const typedData = buildOrderTypedData({
+  cfg,
+  settlementAddress: parsed.settlementAddress,
+  message: {
+    maker: account.address,
+    market: BigInt(parsed.marketId),
+    option: BigInt(Option.UP),
+    side: OrderSide.BUY,
+    type: OrderType.LIMIT,
+    price: 5500n,
+    amount,
+    maxFee,
+    nonce,
+    expiry: BigInt(live.endTime),
+  },
+});
+const signature = await account.signTypedData(typedData);   // viem takes it verbatim
+```
+
+The returned object is `{ domain, types, primaryType, message }` — pass it
+straight to viem's `signTypedData`, or to `ak.signTypedDataBare` /
+`signWithOrderSession` on the smart-account path.
+
+### `CANCEL_TYPES` / `buildCancelTypedData`
+
+```ts
+Cancel { maker address, orderId string, nonce uint256, expiry uint256 }
+```
+
+Same per-pair domain as the order. `nonce` + `expiry` were added in PR-13 so a
+captured cancel signature cannot replay forever; the backend caches
+`(maker, nonce)` for 5 minutes and rejects past-expiry signatures. Drift in this
+schema surfaces as a **404** from the DELETE, not a 400.
+
+### `WS_AUTH_TYPES` / `buildWsAuthTypedData`
+
+```ts
+WsAuth { wallet address, timestamp uint256, sessionId bytes32 }
+```
+
+Deliberately a **different domain** from orders:
+`{ name: "PulsePairs WebSocket Auth", version: "1", chainId, verifyingContract: 0x0 }`.
+Domain separation means an order signature can never be replayed as a WS-auth
+signature or vice versa. It does not depend on the settlement address, so
+`buildWsAuthTypedData` needs only `{ chainId }` from the config.
+
+### `freshSessionId(): 0x${string}`
+
+32 CSPRNG bytes, hex-encoded, for the WS-auth handshake. Throws if
+`globalThis.crypto.getRandomValues` is unavailable rather than degrading to a
+weak source.
+
+### `freshNonce(): bigint`
+
+CSPRNG order/cancel nonce. Two design points worth understanding:
+
+**Why CSPRNG.** The nonce is the only thing between your order and the backend's
+replay store. A *predictable* nonce lets anyone pre-burn your next one and grief
+your order flow — a liveness attack (the signature itself is still unforgeable).
+`Math.random()` is not a CSPRNG and `Date.now()` is public knowledge; neither is
+acceptable.
+
+**Why 48 bits, not 256.** `PostOrderBody.nonce` is a JSON `number`, so the value
+must survive `Number(nonce)` losslessly. Anything above 2^53 silently rounds and
+the posted nonce stops matching the signed one — signature recovery fails.
+
+Across 2^48 values, the *cumulative* birthday-bound probability that any two of
+one maker's ~750k orders collide is ≈1e-3 — about one in a thousand, not
+vanishing. (The often-quoted ~1-in-10⁹ is only the *marginal* odds for a single
+new draw.) Either way a collision is a rejected order, not a loss: retry with a
+fresh nonce. Single-writer bots may prefer a monotonic counter — seed it from
+`freshNonce()` rather than from the clock.
+
+---
+
+## 8. Trade math helpers
+
+```ts
+centsToBps(cents: number): number      // 55 → 5500; 49.5 → 4950. Throws outside (0,100)
+bpsToCents(bps: number): number        // 5500 → 55. Throws outside (0,10000)
+parseStake(usd: string | number): bigint   // "5.50" → 5_500_000n. Rejects negative/non-finite
+assertStakeBounds(amountAtomic: bigint): void
+feeAtomic(notionalAtomic, priceBps, cfg): bigint
+
+MIN_STAKE_ATOMIC = 5_000_000n     // $5
+MAX_STAKE_ATOMIC = 500_000_000n   // $500
+```
+
+Both `centsToBps` and `bpsToCents` are exclusive at both ends — 0¢ and 100¢ are
+not tradeable prices, and passing either throws.
+
+`assertStakeBounds` is defence in depth. The frontend gates these bounds and the
+backend enforces only the upper one today, so validating **before signing**
+means a bad stake never becomes a signed payload at all.
+
+`feeAtomic` mirrors the backend and contract formula (§3.4). Treats a missing
+`cfg.feeModel` as probability-weighted:
+
+```ts
+feeAtomic(5_000_000n, 5000, cfg)   // peak weight at 50¢ → notional × totalBps / 10000
+feeAtomic(5_000_000n,  950, cfg)   // ≈0.34 × totalBps — cheap tail
+```
+
+Use `feeAtomic` to *estimate* what a fill will cost. Use the flat peak formula
+(§3.4) for the signed `maxFee` cap — they are different jobs.
+
+---
+
+## 9. PnL (`src/pnl.ts`)
+
+The matcher exposes the ingredients for PnL but never a PnL number. This module
+computes one in exactly the units the backend already uses, so the result
+reconciles with the backend's own position fold instead of drifting from it.
+
+### Marking rules
+
+| Situation | `markBps` | `markSource` |
+|---|---|---|
+| Market resolved, you hold the winner | `10000` | `"settled"` |
+| Market resolved, you hold the loser | `0` | `"settled"` |
+| Live, both sides quoted | `round((bestBid + bestAsk) / 2)` | `"orderbook-mid"` |
+| Live, only a bid | `bestBid` | `"orderbook-bid"` |
+| Live, only an ask | `bestAsk` | `"orderbook-ask"` |
+| Caller supplied `markBps` | as given | `"explicit"` |
+| No signal at all | the position's own `avgPrice` | `"cost"` |
+
+**Resolution always wins** over any supplied mark: a settled market is worth
+exactly full face or nothing, never a stale quote. The `"cost"` fallback is a
+deliberately honest 0-PnL mark — flagged so you can tell a real
+mark-to-market from "we had nothing to price this with".
+
+`isResolvedWinner(winner)` is `winner === 1 || winner === 2`. The contract's
+`resolve` rejects any other value, so there is no draw or void state.
+
+### Core math
+
+```
+markValue     = shares × markBps / 10000        (floor division, matching the backend)
+unrealizedPnl = markValue − costBasis           (signed)
+roiPct        = 100 × unrealizedPnl / costBasis (null when costBasis is 0)
+```
+
+### API
+
+```ts
+positionPnl(position: Position, opts?: PositionPnlOptions): PositionPnl
+portfolioPnl(items: PositionPnl[], opts?: { fees?, usdtDecimals? }): PortfolioPnl
+computePortfolioPnl(positions, marketsByKey, opts?): PortfolioPnl
+feesPaidByWallet(wallet: string, trades: Trade[]): string
+markValueAtomic(sharesAtomic: bigint, markBps: number): bigint
+midBps(side: OrderBookSide | null | undefined): { bps, source } | null
+markForOption(orderBook, option: number): { bps, source } | null
+isResolvedWinner(winner): winner is 1 | 2
+atomicToUsdt(atomic: bigint | string, decimals?): number
+```
+
+All of these are pure and transport-free — hand them data you already fetched:
+
+```ts
+positionPnl(position, { markBps: 7000 });            // explicit mark
+positionPnl(position, { winner: 1 });                // settled: full-face or zero
+computePortfolioPnl(positions, marketsByKey);        // roll-up; missing market → cost mark
+```
+
+`marketsByKey` maps a position's `market` composite key to
+`Pick<MarketDetail, "winner" | "orderBook">`. A missing entry degrades that
+position to a cost mark rather than dropping it from the report.
+
+`feesPaidByWallet` sums `platformFee + makerFee` across every trade the wallet
+appears in on either leg. It makes no maker/taker attribution — treat it as an
+**upper bound** on the wallet's fee drag.
+
+Fees are never netted into `unrealizedPnl`, because cost basis is fee-exclusive
+(matching the backend's fold). They stay a separate, explicit `fees` line.
+
+`PortfolioPnl.realizedFromSells` (0.6.0) follows the same carried-not-netted
+rule: it is the backend-computed realized P&L from manual sells (atomic USDT
+string, signed, fee-exclusive), reported alongside `unrealizedPnl` rather than
+folded into it. `getPnl` fills it automatically; the pure helpers accept it via
+`opts.realizedFromSells` and default to `"0"`. Per-sell attribution is
+average-cost (buys fold before sells), so only the combined total
+(settlement outcomes + `realizedFromSells`) is order-invariant — do not present
+it as a per-trade breakdown.
+
+### Constants
+
+```ts
+PRICE_BPS_SCALE = 10_000n     WIN_MARK_BPS = 10_000
+LOSE_MARK_BPS   = 0           DEFAULT_USDT_DECIMALS = 6
+```
+
+---
+
+## 10. ERC-20 allowance (`src/approve.ts`)
+
+Settlement pulls USDT directly from the maker via `transferFrom` inside
+`enterPosition`. Without an allowance the first BUY reverts with
+`ERC20: insufficient allowance`.
+
+```ts
+const result = await ensureSettlementAllowance({
+  publicClient,                     // viem PublicClient
+  walletClient,                     // viem WalletClient with an account, funded with ETH
+  usdt: cfg.usdtAddress,
+  settlement: parsed.settlementAddress,
+  amount: stake * 20n,              // HOW MUCH to approve  (default 100k USDT)
+  threshold: stake,                 // WHEN to top up       (default 10k USDT)
+});
+// → { status: "already_ok", allowance } | { status: "approved", txHash, allowance }
+```
+
+Idempotent: reads the current allowance and only sends a tx when it is below
+`threshold`.
+
+**`amount` and `threshold` are different questions.** `threshold` is *when* to
+top up; `amount` is *how much* to approve when you do. The helper throws up-front
+if `amount < threshold`, because that configuration re-approves on every single
+call.
+
+### Why the default is bounded
+
+`DEFAULT_APPROVAL_AMOUNT` is **100,000 USDT**, not `MAX_UINT256`. The
+`settlement` address is routinely sourced from a server-supplied `/config` or
+market list — an unlimited approval would grant a server-named spender unbounded
+reach into a funded hot wallet. The bounded default caps that blast radius while
+sitting comfortably above `DEFAULT_THRESHOLD` (10k) so a continuously-quoting bot
+isn't re-approving constantly.
+
+`MAX_UINT256` is exported for the rare caller who explicitly opts into unlimited.
+
+### Operational note
+
+A bounded allowance is **consumed by fills**. A bot that quotes continuously will
+run it down. This helper only tops up when called — call it inside your quoting
+loop, not just at startup, or fills start reverting mid-session.
+
+To confirm before trading:
+
+```ts
+if (result.status === "approved") await publicClient.waitForTransactionReceipt({ hash: result.txHash });
+```
+
+---
+
+## 11. On-chain reconciliation (`src/reconcile.ts`)
+
+`UpDownSettlement.userShares[marketId][holder][option]` is the **authoritative**
+record of what a holder owns — it is the number `redeem`/`redeemFor` pays
+against. The matcher's off-chain ledger is a *report* of that. A bot that trusts
+only the API cannot see a ledger-integrity failure in its own book.
+
+This module closes that gap with a read-only ABI slice (no write surface):
+
+```ts
+const chain = await readOnChainHolderShares({ publicClient, settlement, marketId, holder });
+// → { marketId, holder, up, down, resolved, winner }   winner: 1 | 2 | 0
+
+const reported = reportedFromPositions(
+  positions.filter((p) => p.market === compositeKey),
+);
+// → { up: bigint, down: bigint }
+
+const report = await reconcileFills({ publicClient, settlement, marketId, holder, reported });
+// → { marketId, holder, resolved, winner, lines, ok, hasPhantom }
+```
+
+Each line is `{ option, optionLabel, onChain, reported, drift, status }` where
+`drift = reported − onChain` and `status` is:
+
+- `"match"` — exact agreement
+- `"reported_over"` — the matcher claims **more** than the chain backs. The
+  dangerous direction: a phantom position you would price against but cannot
+  redeem.
+- `"reported_under"` — the matcher claims less than the chain backs.
+
+`ok` is true when every option matches; `hasPhantom` is true when any line is
+`reported_over`.
+
+**Before alerting on `hasPhantom`, check `resolved` and `winner`.** After a
+redemption the holder has already been paid and `userShares` is zeroed, so a
+winner-side `reported_over` is benign — it just means the off-chain ledger hasn't
+caught up.
+
+Run this on a timer against your own positions. It is an independent detector,
+not a courtesy check.
+
+---
+
+## 12. Account Kit / smart-account signing (`src/accountKit.ts`)
+
+### Why this module exists
+
+rain.trade custody is an Alchemy Account Kit smart-contract account (SCA). The
+UpDown settlement verifies order signatures with OpenZeppelin
+`SignatureChecker.isValidSignatureNow(maker, digest, sig)` (OZ 5.6.1), which
+routes to `IERC1271(maker).isValidSignature(...)` when `maker` is a contract.
+
+Account Kit derives the SCA address deterministically from (owner, factory), so
+**the same owner EOA + the same config ⇒ the same SCA address ⇒ one wallet
+across both products**. This module mirrors rain's `RainAA` *config*, not its
+code — `RainAA` is a published, unpatchable package that exposes no
+`signTypedData`.
+
+### The two rules you cannot break
+
+Both come from the on-chain verifier, which is **not** EIP-6492-aware:
+
+1. **Deploy the SCA before its first fill.** A counterfactual (undeployed)
+   account cannot be verified via ERC-1271 — the fill reverts. `onboard()` does
+   the deploy; `isDeployed(publicClient)` checks it.
+2. **Bare ERC-1271, never 6492.** `signTypedData` on an undeployed account can
+   return a 6492-wrapped blob the settlement cannot parse. Every signature this
+   SDK produces passes through `stripErc6492Wrapper(...)`.
+
+> Confirmed live on Arbitrum One (2026-07-05/06): a real SCA was deployed,
+> `isValidSignature` over the full Order typed-data returned the `0x1626ba7e`
+> magic on-chain, a real `enterPosition` fill settled with `maker = SCA`, and the
+> negative control (undeployed SCA) reverted as expected. The MA-v2 / ERC-7739
+> question is resolved — sign the **full typed data** through the account client
+> (which this SDK does); handing the SCA a bare `bytes32` silently fails.
+
+### Constructing
+
+```ts
+import { UpDownAccountKitSigner } from "@pulsepairs/sdk";
+import { arbitrum } from "viem/chains";
+
+const ak = new UpDownAccountKitSigner({
+  walletClient: window.ethereum,          // owner EOA EIP-1193 provider
+  alchemyApiKey: ALCHEMY_KEY,             // SAME key rain.trade uses
+  paymasterPolicyId: POLICY_ID,           // SAME policy rain.trade uses (optional)
+  chain: arbitrum,                        // SAME chain (42161) — required for address parity
+  // gasToken: { tokenAddress },          // only for an ERC-20-type Gas Manager policy
+  // rpcUrl,                              // node RPC override
+  // orderSessions: true,                 // default; false forces owner-key signing
+  // orderSessionStorage,                 // default: localStorage, else in-memory
+});
+```
+
+Gas semantics follow the policy:
+
+| Config | Who pays gas |
+|---|---|
+| Sponsorship-type `paymasterPolicyId` | the app (sponsored) |
+| ERC-20-type `paymasterPolicyId` + `gasToken` | the user, in that token (must be allowlisted and held by the SCA) |
+| No `paymasterPolicyId` | self-paid — the SCA must hold ETH |
+
+The constructor validates `walletClient`, `alchemyApiKey` and `chain` eagerly and
+throws on any missing.
+
+### Lifecycle
+
+```ts
+const sca = await ak.connect();                        // → SCA address; this is order.maker
+await ak.onboard({ usdt: cfg.usdtAddress, settlement, amount });   // ONE UserOp
+const sig = await ak.signTypedDataBare(typedData);     // bare ERC-1271
+```
+
+`connect()` lazily imports the peer deps, builds the owner smart-wallet client,
+resolves the SCA, and caches the address under `rain:sa:<eoa>` in `localStorage`
+(the same cache key rain.trade's `useRain` uses). It does **not** prompt for a
+session. Order signing works immediately via the owner key.
+
+`onboard()` batches **deploy + `approve(settlement)` + order-session install**
+into a single UserOp — still exactly one owner signature. Deployment is carried
+by the account init-code. If the order-session prep fails it degrades gracefully
+to plain deploy+approve, and orders fall back to owner-key signing.
+
+> ⚠️ `onboard()` and `approve()` default `amount` to `MAX_UINT256`. Unlike
+> `ensureSettlementAllowance`, whose default is bounded, these are unlimited for
+> backwards compatibility. Pass an explicit `amount` — `settlement` came from the
+> matcher's own config.
+
+### Methods and properties
+
+| Member | Description |
+|---|---|
+| `connect()` | Build the client, resolve + return the SCA address. Idempotent. |
+| `address` | The SCA — `order.maker`, deposit address, ERC-1271 signer. Throws before `connect()`. |
+| `ownerEoa` | The owner EOA behind it. Throws before `connect()`. |
+| `ownerClient` | The raw Alchemy smart-wallet client (escape hatch). |
+| `signTypedDataBare(td)` | **The only signing path** for orders/cancels/WS-auth. Order-session-signed when active, else owner-signed with the 6492 wrapper stripped. |
+| `signWsAuth(chainId)` | Builds + signs a WS-auth handshake, returns `WsAuthCredentials` ready for `connectAuthed`. |
+| `isDeployed(publicClient)` | Bytecode check — the deploy-before-fill precondition. |
+| `onboard({ usdt, settlement, amount? })` | Deploy + approve + install session in one UserOp. Returns the tx hash. |
+| `approve({ usdt, settlement, amount? })` | Idempotent gasless approve. |
+| `withdraw({ usdt, to, amount })` | Transfer USDT out of the SCA. |
+| `sendCall({ to, data, value? })` | Arbitrary call from the SCA as a UserOp. Returns the tx hash. |
+| `grantSession()` | 24h **send** session (one popup). Safe to call when one is active. |
+| `hasActiveSession` | Whether a send session is live. |
+| `ensureOrderSession()` | Install an order session on an already-onboarded account. → `"disabled" \| "active" \| "installed"` |
+| `revokeOrderSession()` | Drop the **local** session key (no on-chain uninstall). |
+| `hasOrderSession` | Whether an unexpired order session exists for this SCA. |
+| `disconnect()` | Clear in-memory state. Persisted sessions survive. |
+
+### The two session mechanisms — do not conflate them
+
+**1. Send session** (`grantSession()`, Alchemy `grantPermissions({type:'root'})`)
+authorizes UserOp **execution** only — gasless `onboard`/`approve`/`withdraw`,
+mirroring RainAA. Its signatures pack the *owner* validation entity, so it is
+**verified incapable** of ERC-1271 order signing (`isValidSignature` returns
+`0xffffffff`).
+
+**2. Order session** (default **ON**) is a locally-generated key installed on the
+MA-v2 SCA as a `SingleSignerValidationModule` entity with
+`isSignatureValidation: true, isUserOpValidation: false`. It can **only** answer
+`isValidSignature` — orders, cancels, WS-auth, popup-less — and can **never**
+move funds or execute a UserOp. `onboard()` batches the install into the same
+single UserOp as deploy+approve.
+
+Behaviour:
+
+- `signTypedDataBare` prefers the order-session key and **falls back to the owner
+  key automatically on any failure** — enabling this can never break signing.
+- Storage defaults to browser `localStorage` under `updown:oskey:<sca>`, an
+  in-memory map in Node (session lives for the process), or bring your own via
+  `orderSessionStorage`.
+- The installed entity id is a CSPRNG-drawn 4-byte value ≥ 2 (0 is the owner
+  entity; installing an existing id reverts). Randomness prevents an observer
+  from front-running the install and bricking onboarding by burning the id.
+- Opt out entirely with `orderSessions: false` — every order then prompts the
+  owner wallet.
+
+**Known limitations** (fine for integration/demo; review before launch):
+expiry is **client-side only** (24h, not enforced on-chain), and
+`revokeOrderSession()` does not uninstall the validation entity on-chain.
+
+### Standalone helpers
+
+```ts
+isErc6492Signature(sig: Hex): boolean
+stripErc6492Wrapper(sig: Hex): Hex        // returns input unchanged if not wrapped
+bareErc1271Signer(raw: RawTypedDataSigner): RawTypedDataSigner
+```
+
+If the host app already owns an Alchemy client (e.g. rain.trade's shared
+session), skip the signer class entirely and just make its output
+UpDown-correct:
+
+```ts
+const signOrder = bareErc1271Signer((td) => rainSmartWalletClient.signTypedData(td));
+const signature = await signOrder(buildOrderTypedData({ cfg, settlementAddress, message }));
+```
+
+---
+
+## 13. Raw-tx tier — bring your own AA send path
+
+If you run your own Account-Abstraction send path (rain.trade's `sendTxs` through
+their root session), use these transport-free primitives instead of the signer
+class. They emit **byte-identical** calldata to what the class sends — the class
+delegates to the same internals.
+
+```ts
+export type RawTransaction = { to: Address; data: Hex; value?: bigint };
+```
+
+That is rain's exact `RawTransaction` shape, so these drop straight into
+`sendTxs`/`sendCalls` with no adapter.
+
+```ts
+import {
+  buildApproveSettlementTx, buildInstallOrderSessionTx, signWithOrderSession,
+} from "@pulsepairs/sdk";
+
+// ── Onboard once: batch both raw txs into ONE userOp through YOUR session ──
+const approveTx = buildApproveSettlementTx({ usdt: cfg.usdtAddress, settlement, amount });
+const { tx: installTx, session } = await buildInstallOrderSessionTx({ sca, chain: arbitrum });
+await sendTxs([approveTx, installTx]);
+persist(session);              // { v: 1, privateKey, entityId, expirySec }
+
+// ── Every order after that: no chain, no gas, no popup ──
+const typedData = buildOrderTypedData({ cfg, settlementAddress, message /* maker: sca, … */ });
+const signature = await signWithOrderSession({ session, sca, chain: arbitrum, alchemyApiKey, typedData });
+await api.postOrder({ maker: sca, /* … */ signature });
+```
+
+| Function | Sync? | Peer deps? | Notes |
+|---|---|---|---|
+| `buildApproveSettlementTx` | yes | no | Pure calldata. `amount` defaults to `MAX_UINT256` — pass a bound. |
+| `buildInstallOrderSessionTx` | async | yes | Generates the key locally; no network, gas, or popup. |
+| `signWithOrderSession` | async | yes | Pure local ECDSA over the MA-v2 `signerEntity`. No bundler. |
+
+**The one mental-model flip:** placing an order is not a transaction, so there is
+no `buildPlaceOrderTx`. You sign and POST.
+
+**Adoption path.** MVP = `approve` (1 raw tx) + `bareErc1271Signer` owner path
+(1 popup per order, zero new code). Production = `approve` + install (batched) +
+`signWithOrderSession` (popup-less). The on-chain acceptance of these exact bytes
+on rain's MA-v2 implementation is proven by
+`updown-contracts/test/OrderSessionForkTest.t.sol`.
+
+The `sca` must be deployed and carry the session entity before a
+`signWithOrderSession` signature is used in a fill.
+
+---
+
+## 14. L2 HMAC auth (`src/auth.ts`)
+
+An API-key auth layer for bots, structurally identical to Polymarket's
+`clob-client` HMAC scheme (bytes-level compatible).
+
+> **Node-only.** This module imports `crypto` from Node. It is not
+> browser-safe, and **`apiSecret` must never reach client-side code.**
+
+```ts
+import { buildHmacSignature, HMAC_HEADERS, buildClobAuthTypedData } from "@pulsepairs/sdk";
+
+// One-time: obtain credentials (store apiSecret + passphrase out-of-band — env, KMS).
+const { apiKey, apiSecret, passphrase } = await (await fetch("/auth/credentials", { … })).json();
+
+// Every subsequent request:
+const ts  = Math.floor(Date.now() / 1000);              // SECONDS, not ms
+const sig = buildHmacSignature(apiSecret, ts, "DELETE", "/orders/abc");
+
+await fetch("/orders/abc", {
+  method: "DELETE",
+  headers: {
+    [HMAC_HEADERS.ADDRESS]:    address,
+    [HMAC_HEADERS.API_KEY]:    apiKey,
+    [HMAC_HEADERS.PASSPHRASE]: passphrase,
+    [HMAC_HEADERS.TIMESTAMP]:  String(ts),
+    [HMAC_HEADERS.SIGNATURE]:  sig,
+  },
+});
+```
+
+### `buildHmacSignature(secretBase64, timestamp, method, requestPath, body?)`
+
+Signs `${timestamp}${method}${requestPath}${body ?? ""}` with HMAC-SHA256 over
+the base64-decoded secret, and returns **base64url** (`+`→`-`, `/`→`_`).
+
+- `timestamp` — unix **seconds**.
+- `method` — uppercase.
+- `requestPath` — path **with query string**, no host (`"/orders/abc?foo=1"`).
+- `body` — the raw JSON-stringified body, byte-for-byte what you send; omit for
+  GET/DELETE.
+
+Any divergence in these — ms instead of seconds, a re-serialized body, a missing
+query string — produces a signature the server rejects.
+
+### `buildClobAuthTypedData(domain, address, timestamp, nonce)`
+
+The EIP-712 `ClobAuth` payload a bot signs once at session open, to obtain
+credentials.
+
+```ts
+ClobAuth { address address, timestamp string, nonce uint256, message string }
+CLOB_AUTH_MESSAGE = "This message attests that I control the given wallet"
+```
+
+`domain` is `{ name, version, chainId }` — `"PulsePairsAuthDomain"` on this
+backend. Note `timestamp` is a **string** in this schema (unlike `WsAuth`, where
+it is a uint256).
+
+### Header constants
+
+```ts
+HMAC_HEADERS = {
+  ADDRESS:    "X-PP-ADDRESS",
+  API_KEY:    "X-PP-API-KEY",
+  PASSPHRASE: "X-PP-PASSPHRASE",
+  TIMESTAMP:  "X-PP-TIMESTAMP",
+  SIGNATURE:  "X-PP-SIGNATURE",
+}
+```
+
+Use the constants, not literals.
+
+---
+
+## 15. Type reference
+
+### Config
+
+```ts
+type ApiConfig = {
+  chainId: number;
+  usdtAddress: `0x${string}`;
+  relayerAddress: `0x${string}`;
+  platformFeeBps: number;
+  makerFeeBps: number;
+  feeModel?: "probability-weighted" | string;
+  peakFeeBps?: number;              // platformFeeBps + makerFeeBps
+  dmmRebateBps: number;
+  usdtDecimals: number;
+  pairs: PairConfig[];              // ← use this
+  settlementAddress: `0x${string}`; // @deprecated — first pair's value
+  eip712: { domain: Eip712Domain }; // @deprecated — first pair's domain
+};
+
+type PairConfig = {
+  pairId: "BTC-USD" | "ETH-USD";
+  settlementAddress: `0x${string}`;
+  autocyclerAddress: `0x${string}` | "";   // "" when read-only (no autocycler wired)
+  eip712: { domain: Eip712Domain };
+};
+
+type Eip712Domain = { name: string; version: string; chainId: number; verifyingContract: `0x${string}` };
+```
+
+### Markets
+
+```ts
+type MarketListItem = {
+  address: string;                  // COMPOSITE key
+  marketId?: string;
+  settlementAddress?: `0x${string}`;
+  pairId: string;
+  pairSymbol?: "BTC-USD" | "ETH-USD";
+  chartSymbol?: "BTC" | "ETH";
+  startTime: number;                // unix sec
+  endTime: number;                  // unix sec
+  duration: number;                 // sec
+  status: "ACTIVE" | "TRADING_ENDED" | "RESOLVED" | "CLAIMED" | string;
+  winner: number | null;            // 1 = UP, 2 = DOWN, null = unresolved
+  upPrice: string;
+  downPrice: string;
+  strikePrice?: string;
+  settlementPrice?: string;
+  volume: string;
+};
+
+type MarketDetail = MarketListItem & {
+  timeRemainingSeconds: number;
+  orderBook: { up: OrderBookSide; down: OrderBookSide };   // top of book only
+};
+
+type OrderBookSide  = { bestBid: { price: number; depth: string } | null;
+                        bestAsk: { price: number; depth: string } | null };
+type OrderBookFull  = { up: { bids: OrderBookLevel[]; asks: OrderBookLevel[] };
+                        down: { bids: OrderBookLevel[]; asks: OrderBookLevel[] } };
+type OrderBookLevel = { price: number; depth: string; count: number };
+```
+
+`getMarket` gives top-of-book; `getOrderbook` gives full depth.
+
+### Account
+
+```ts
+type Balance = {
+  wallet: string; smartAccountAddress: string;
+  available: string; inOrders: string;            // atomic USDT
+  cachedBalance: string; balanceLastSyncedAt: string;
+  withdrawNonce: number;
+};
+
+type Position = {
+  market: string;                   // composite key
+  marketStatus: string;
+  option: number;                   // 1 | 2
+  optionLabel: "UP" | "DOWN";
+  shares: string;                   // atomic — also the face value at settlement
+  avgPrice: number;                 // bps
+  costBasis: string;                // atomic, FEE-EXCLUSIVE = shares × avgPrice / 10000
+};
+
+type OrderRow = {
+  orderId: string; maker: string; market: string;
+  option: number; side: number; type: number;     // numeric enums
+  price: number;                                  // bps
+  amount: string; filledAmount: string;           // atomic
+  nonce: string; expiry: string;                  // uint256 as STRINGS
+  signature: string;
+  status: OrderStatus; reason?: string;
+  createdAt: string; updatedAt?: string;
+};
+
+type OrderStatus = "OPEN" | "PARTIALLY_FILLED" | "FILLED" | "CANCEL_PENDING" | "CANCELLED" | string;
+type OrdersResponse = { orders: OrderRow[]; total: number; limit: number; offset: number };
+```
+
+`OrderRow.nonce` / `expiry` are JSON strings because the backend stores them as
+`String` to preserve full uint256 precision — a `number` would silently truncate
+above 2^53. Parse with `BigInt(row.nonce)`, or pass the string straight to
+`signTypedData` (viem accepts string-form bigints).
+
+### Trades
+
+See §3.5 for the `matchType` / `takerPrice` semantics — the fields most likely to
+be misread.
+
+```ts
+type Trade = {
+  tradeId: string; market: string;
+  option: number;                   // the TAKER's option
+  buyOrderId: string; sellOrderId: string;
+  buyer: string;                    // NORMAL: buyer. MINT/MERGE: the aggressor
+  seller: string;                   // NORMAL: seller. MINT/MERGE: the resting maker
+  price: number;                    // bps — the resting MAKER's price
+  amount: string;
+  platformFee: string; makerFee: string;
+  settlementStatus: string; createdAt: string;
+  matchType?: "NORMAL" | "MINT" | "MERGE";   // optional: pre-2026-07-17 backends omit
+  takerPrice?: number;                       // optional: bps the taker actually paid
+};
+
+takerPriceBps(trade): number        // always use this to render a taker fill
+```
+
+### Request bodies
+
+```ts
+type PostOrderBody = {
+  maker: string;
+  market: string;                   // COMPOSITE key — routing only
+  option: number;
+  side: number | "BUY" | "SELL";
+  type: number | "LIMIT" | "MARKET" | "POST_ONLY" | "IOC";
+  price?: number;                   // bps; 0 for MARKET
+  amount: string;                   // atomic
+  maxFee: string;                   // atomic — REQUIRED, must equal the signed value
+  nonce: number;                    // JSON number (< 2^53)
+  expiry: number;                   // unix sec
+  signature: string;
+};
+
+type CancelOrderBody = {
+  maker: string;
+  signature: string;
+  nonce: string | number;           // send as STRING for uint256 precision
+  expiry: string | number;
+};
+```
+
+---
+
+## 16. Security checklist for a funded key
+
+This SDK is normally driven by a hot key holding real USDT. Each of these exists
+because the corresponding failure is **silent**.
+
+**1. Never default your endpoints.** A bot signs orders for whatever matcher you
+point it at, then grants that matcher's *server-supplied* settlement address a
+USDT allowance. A defaulted API URL plus a defaulted mainnet RPC means a real
+funded key trading against a box you never chose.
+
+```ts
+const API = process.env.UPND_API;
+if (!API) throw new Error("Set UPND_API — refusing to default a funded key to a third-party endpoint");
+const RPC = process.env.ARBITRUM_RPC_URL;
+if (!RPC) throw new Error("Set ARBITRUM_RPC_URL");
+```
+
+**2. Assert the matcher and the RPC agree on the chain — before the approve.**
+This single check kills the whole class; a demo matcher paired with a mainnet key
+cannot survive it.
+
+```ts
+const cfg = await api.getConfig();
+const rpcChainId = await publicClient.getChainId();
+if (cfg.chainId !== rpcChainId) {
+  throw new Error(`chain mismatch: matcher says ${cfg.chainId}, RPC says ${rpcChainId}`);
+}
+```
+
+**3. Bound every allowance.** Pass an explicit `amount` to
+`ensureSettlementAllowance` (EOA), `onboard`/`approve` (Account Kit), and
+`buildApproveSettlementTx` (raw-tx). The Account Kit and raw-tx paths still
+default to `MAX_UINT256` for backwards compatibility — that default is an
+unbounded claim on your balance by an address the server named. Re-run the helper
+on a timer, since fills consume the allowance.
+
+**4. Use `freshNonce()`.** Never `Math.random()` or `Date.now()` — a guessable
+nonce lets anyone pre-burn it against the replay store and block your order flow.
+
+**5. Never put `apiSecret` (§14) in client-side code**, and never hold an order
+session key anywhere you wouldn't hold a signing key — its blast radius is
+narrow (signature-only, cannot move funds) but it is still your trading identity.
+
+**6. Validate before signing.** `assertStakeBounds` and `centsToBps` throw on
+out-of-range input, so a bad value never becomes a signed payload.
+
+---
+
+## 17. Troubleshooting
+
+| Symptom | Likely cause |
+|---|---|
+| Fill reverts, on-chain signature rejected | `maxFee` missing from the signed message, or the posted `maxFee` ≠ the signed one. It sits between `amount` and `nonce` in `ORDER_TYPES`. |
+| Posted nonce doesn't match the signed nonce | A nonce ≥ 2^53 rounded through `Number()`. Use `freshNonce()`. |
+| `ERC20: insufficient allowance` mid-session | A bounded allowance ran dry. Call `ensureSettlementAllowance` inside your loop, not just at startup. |
+| Fill reverts on a smart account | The SCA is not deployed, or a 6492-wrapped signature reached the matcher. Check `isDeployed()`; all SDK signing paths strip 6492. |
+| `isValidSignature` returns `0xffffffff` | You signed with a **send** session (root permissions). Send sessions cannot do ERC-1271 — use an order session or the owner key. |
+| Order rejected, `domainForSettlement` throws | The settlement address isn't in `cfg.pairs[]`. Don't hardcode a domain; re-fetch `/config`. |
+| DELETE `/orders/:id` returns **404** | Cancel-signature schema drift — `CANCEL_TYPES` must carry `nonce` + `expiry`. |
+| No `orders:` / `balance:` events | The connection is unauthenticated. `connectPublic` silently drops private channels; use `connectAuthed`. |
+| WS auth fails immediately | Clock skew > ±60s, or a reused `sessionId`. Call `freshSessionId()` per handshake. |
+| WS stops reconnecting | Terminal auth failure (`unauthed-failure`) or an explicit `disconnect()`. Both are intentional. |
+| `WebSocket is not defined` | Node 18–21 without the global. Run Node ≥ 22, use `--experimental-websocket`, or polyfill `globalThis.WebSocket`. |
+| Displayed fill price looks inverted | A MINT/MERGE row rendered with `price` (the maker's leg). Use `takerPriceBps(trade)`. |
+| PnL shows 0 on a live position | `markSource: "cost"` — no book signal was available, so it marked at `avgPrice`. |
+| `Cannot find module '@account-kit/...'` | Optional peers not installed. Only needed for `UpDownAccountKitSigner` / raw-tx builders. |
+| `approve amount is below the re-approve threshold` | `amount < threshold` in `ensureSettlementAllowance` — that would re-approve on every call. Raise `amount` or lower `threshold`. |
+| `getRandomValues unavailable` | Node < 18 or a non-standard runtime. The SDK throws rather than degrading to a weak RNG. |
+
+---
+
+## 18. Testing and schema-drift guards
+
+```bash
+npm run build     # clean + tsc → dist/
+npm test          # the guard suite (also runs on prepublishOnly)
+```
+
+`npm test` runs six scripts in `scripts/`:
+
+| Script | Guards |
+|---|---|
+| `eip712-golden.test.mjs` | The EIP-712 golden vector — digest + signature derived **independently** from the backend and contract definitions. This is the primary drift alarm. |
+| `rawtx-tier.test.mjs` | Raw-tx builders emit the same bytes as the signer class. |
+| `hot-key-safety.test.mjs` | The funded-key guardrails (§16). |
+| `reconcile.test.mjs` | On-chain reconciliation math. |
+| `pnl.test.mjs` | PnL math against known vectors. |
+| `ws-subscribe.test.mjs` | WS subscribe/unsubscribe/replay semantics. |
+
+**If `eip712-golden.test.mjs` fails, do not "fix" the test.** It means
+`ORDER_TYPES`, `CANCEL_TYPES` or the domain has drifted from the backend or the
+contract, and every signature this SDK produces is being rejected on-chain.
+Reconcile against `UpDownSettlement.sol`'s `ORDER_TYPEHASH` first.
+
+Runnable examples (repo only, not in the npm tarball):
+
+```bash
+npm run example:taker    # examples/simple-taker.ts   — one MARKET order, poll for fill
+npm run example:maker    # examples/simple-maker.ts   — LIMIT order + authed WS + cancel
+npm run example:dmm      # examples/full-dmm-bot.ts   — two-sided quoting loop
+#                          examples/account-kit-taker.ts — SCA end-to-end
+#                          examples/rain-taker.ts        — raw-tx tier walkthrough
+```
+
+All examples require `UPND_API` and `ARBITRUM_RPC_URL` explicitly, or
+`UPND_DEMO=1` to opt into the public demo stack. There is no silent default —
+see `examples/_env.ts`.
+
+---
+
+## 19. Compatibility notes
+
+**Package.** ESM-only, `sideEffects: false`, Node ≥ 18. `viem ^2.21` is a
+required peer; the four `@account-kit/*` / `@aa-sdk/core` packages are optional
+peers, lazy-imported.
+
+**Versioning.** This package is deliberately **segregated** from `rain-sdk-v2` —
+bump it independently, no release coupling.
+
+**Deprecated but still present:**
+
+- `ApiConfig.settlementAddress` and `ApiConfig.eip712` (top-level) — first pair's
+  values, kept for one release cycle. Use `cfg.pairs[]`.
+- `UpDownWsClient.connect(SubscribePayload)` — routes to `connectPublic`; the
+  `wallet` field is ignored.
+
+**Optional fields that mean "older backend":** `Trade.matchType` and
+`Trade.takerPrice` are absent on backends predating 2026-07-17.
+`takerPriceBps()` handles both.
+
+**External references:**
+
+- Wire shapes / REST / WS / rate limits — `docs/api.md` in `updown-backend`
+  (branch `audit/hacken-remediation-v2`).
+- On-chain spec — `src/UpDownSettlement.sol` in `updown-contracts` (same branch):
+  `ORDER_TYPEHASH`, `enterPosition`, fee-cap enforcement.
+- Raw-tx tier rationale — `UPDOWN_RAIN_RAWTX_SDK_DESIGN.md`.
+- Order-session on-chain proof — `updown-contracts/test/OrderSessionForkTest.t.sol`.
+</content>
+</invoke>