@alpha-arcade/sdk 0.3.0 → 0.3.5

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript SDK for trading on **Alpha Market** — Algorand prediction markets.
 
-Place orders, manage positions, read orderbooks, and build automated trading bots — all directly on-chain.
+Place orders, manage positions, read orderbooks from the API or chain, and build automated trading bots.
 
 ## Installation
 
@@ -246,7 +246,7 @@ for (const pos of positions) {
 
 #### `getOrderbook(marketAppId)`
 
-Fetches the full on-chain orderbook.
+Fetches the full on-chain orderbook for a single market app.
 
 ```typescript
 const book = await client.getOrderbook(123456789);
@@ -263,6 +263,24 @@ if (book.yes.bids.length > 0) {
 }
 ```
 
+#### `getFullOrderbookFromApi(marketId)`
+
+Fetches the full processed orderbook snapshot for a market from the Alpha REST API. Requires `apiKey`.
+
+This returns the same shape as websocket `orderbook_changed.orderbook`: a record keyed by `marketAppId`, where each value includes:
+- top-level aggregated `bids`, `asks`, and `spread`
+- detailed `yes` and `no` bid/ask orders with `escrowAppId` and `owner`
+
+```typescript
+const snapshot = await client.getFullOrderbookFromApi('market-uuid-here');
+
+for (const [appId, book] of Object.entries(snapshot)) {
+  console.log(`App ${appId}: spread=${book.spread}`);
+  console.log('Top-level bids:', book.bids);
+  console.log('Detailed YES bids:', book.yes.bids);
+}
+```
+
 #### `getOpenOrders(marketAppId, walletAddress?)`
 
 Gets open orders for a wallet on a specific market (from on-chain data).
@@ -337,6 +355,150 @@ for (const m of rewardMarkets) {
 
 ---
 
+### WebSocket Streams
+
+Real-time data streams via WebSocket. No API key or auth required. Replaces polling with push-based updates.
+
+The SDK connects to the public platform websocket at `wss://wss.platform.alphaarcade.com`. The first
+subscription is sent in the connection query string, and any later subscribe or unsubscribe calls use the
+server's control-message envelope:
+
+```json
+{
+  "id": "request-id",
+  "method": "SUBSCRIBE",
+  "params": [
+    { "stream": "get-orderbook", "slug": "will-btc-hit-100k" }
+  ]
+}
+```
+
+Supported public streams:
+
+- `get-live-markets`
+- `get-market` with `slug`
+- `get-orderbook` with `slug`
+- `get-wallet-orders` with `wallet`
+
+```typescript
+import { AlphaWebSocket } from '@alpha-arcade/sdk';
+
+// Node.js 22+ and browsers — native WebSocket, nothing extra needed
+const ws = new AlphaWebSocket();
+
+// Node.js < 22 — install `ws` and pass it in:
+// npm install ws
+import WebSocket from 'ws';
+const ws = new AlphaWebSocket({ WebSocket });
+
+// Subscribe to orderbook updates (~5s snapshots)
+const unsub = ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+  console.log('Orderbook:', event.orderbook);
+});
+
+// Unsubscribe when done
+unsub();
+
+// Close the connection
+ws.close();
+```
+
+#### `subscribeLiveMarkets(callback)`
+
+Receive incremental diffs whenever market probabilities change.
+
+```typescript
+ws.subscribeLiveMarkets((event) => {
+  console.log('Markets changed at', event.ts, event);
+});
+```
+
+#### `subscribeMarket(slug, callback)`
+
+Receive change events for a single market. Uses the market **slug** (not `marketAppId`) — see note on `subscribeOrderbook` below.
+
+```typescript
+ws.subscribeMarket('will-btc-hit-100k', (event) => {
+  console.log('Market update:', event);
+});
+```
+
+#### `subscribeOrderbook(slug, callback)`
+
+Receive full orderbook snapshots on every change (~5s interval). The payload matches `getFullOrderbookFromApi(marketId)`.
+
+**Note:** The WebSocket API uses market **slugs** (URL-friendly names like `"will-btc-hit-100k"`), not `marketAppId` numbers. You can get a market's slug from the `slug` field on `Market` objects returned by `getLiveMarkets()` or `getMarket()`.
+
+```typescript
+ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+  // Top-level bids/asks use decimal prices (cents)
+  // Nested yes/no use raw microunit prices with escrowAppId and owner
+  for (const [appId, book] of Object.entries(event.orderbook)) {
+    console.log(`App ${appId}: spread=${book.spread}`);
+    console.log('  Bids:', book.bids);
+    console.log('  Yes bids:', book.yes.bids);
+  }
+});
+```
+
+#### `subscribeWalletOrders(wallet, callback)`
+
+Receive updates when orders for a wallet are created or modified.
+
+```typescript
+ws.subscribeWalletOrders('MMU6X...', (event) => {
+  console.log('Wallet orders changed:', event);
+});
+```
+
+#### Unsubscribing
+
+Each `subscribe*` method returns an unsubscribe function. Call it to stop receiving events for that stream:
+
+```typescript
+const unsub = ws.subscribeOrderbook('my-market', (event) => { /* ... */ });
+
+// Later, stop listening
+unsub();
+```
+
+#### Control Methods
+
+```typescript
+// List active subscriptions on this connection
+const subs = await ws.listSubscriptions();
+
+// Query server properties (`heartbeat` or `limits`)
+const props = await ws.getProperty('heartbeat');
+```
+
+#### Configuration
+
+```typescript
+import WebSocket from 'ws'; // Only needed on Node.js < 22
+
+const ws = new AlphaWebSocket({
+  WebSocket,                                  // Pass `ws` on Node.js < 22 (not needed in browsers or Node 22+)
+  url: 'wss://custom-endpoint.example.com',   // Override default URL
+  reconnect: true,                            // Auto-reconnect (default: true)
+  maxReconnectAttempts: 10,                   // Give up after 10 retries (default: Infinity)
+  heartbeatIntervalMs: 60_000,                // Ping interval in ms (default: 60000)
+});
+```
+
+#### Connection Details
+
+| Setting | Value |
+|---------|-------|
+| Heartbeat | 60s (auto-handled) |
+| Idle timeout | 180s |
+| Rate limit | 5 messages/sec/connection |
+| Reconnect | Exponential backoff (1s → 30s max) |
+
+The client automatically responds to server pings, sends keepalive pings, and reconnects with exponential backoff on unexpected disconnects. All active subscriptions are restored after reconnect.
+
+---
+
 ### Utility Functions
 
 These are exported for advanced users: