@alpha-arcade/sdk 0.4.0 → 0.4.2

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).
@@ -341,6 +359,27 @@ for (const m of rewardMarkets) {
 
 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';
 
@@ -386,7 +425,7 @@ ws.subscribeMarket('will-btc-hit-100k', (event) => {
 
 #### `subscribeOrderbook(slug, callback)`
 
-Receive full orderbook snapshots on every change (~5s interval). Replaces on-chain polling.
+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()`.
 
@@ -429,7 +468,7 @@ unsub();
 // List active subscriptions on this connection
 const subs = await ws.listSubscriptions();
 
-// Query server properties
+// Query server properties (`heartbeat` or `limits`)
 const props = await ws.getProperty('heartbeat');
 ```
 

package/dist/index.cjs

@@ -2266,6 +2266,18 @@ var getWalletOrdersFromApi = async (config, walletAddress) => {
   }
   return allOrders;
 };
+var getFullOrderbookFromApi = async (config, marketId) => {
+  if (!config.apiKey) {
+    throw new Error("apiKey is required for API-based orderbook fetching. Retrieve an API key from the Alpha Arcade platform via the Account page and pass it to the client.");
+  }
+  const baseUrl = config.apiBaseUrl ?? DEFAULT_API_BASE_URL;
+  const url = `${baseUrl}/get-full-orderbook?marketId=${encodeURIComponent(marketId)}`;
+  const response = await fetch(url, { headers: { "x-api-key": config.apiKey } });
+  if (!response.ok) {
+    throw new Error(`Alpha API error: ${response.status} ${response.statusText}`);
+  }
+  return response.json();
+};
 
 // src/modules/trading.ts
 var extractEscrowAppId = async (algodClient, indexerClient, targetTxId) => {
@@ -3272,6 +3284,19 @@ var AlphaClient = class {
   async getOrderbook(marketAppId) {
     return getOrderbook(this.config, marketAppId);
   }
+  /**
+   * Fetches the full processed orderbook snapshot for a market from the Alpha REST API.
+   *
+   * Returns the same shape as websocket `orderbook_changed.orderbook`: a record keyed by
+   * `marketAppId`, where each value includes aggregated bids/asks plus detailed yes/no orders.
+   * Requires `apiKey`.
+   *
+   * @param marketId - The Alpha market UUID
+   * @returns Full processed market orderbook keyed by marketAppId
+   */
+  async getFullOrderbookFromApi(marketId) {
+    return getFullOrderbookFromApi(this.config, marketId);
+  }
   /**
    * Gets open orders for a specific wallet on a market.
    *
@@ -3446,7 +3471,7 @@ var AlphaWebSocket = class {
   }
   /** Query a server property (e.g. "heartbeat", "limits") */
   getProperty(property) {
-    return this.sendRequest({ method: "GET_PROPERTY", property });
+    return this.sendRequest({ method: "GET_PROPERTY", params: [property] });
   }
   // ============================================
   // Lifecycle
@@ -3546,9 +3571,10 @@ var AlphaWebSocket = class {
       this.send({ method: "PONG" });
       return;
     }
-    if (msg.requestId && this.pendingRequests.has(msg.requestId)) {
-      const req = this.pendingRequests.get(msg.requestId);
-      this.pendingRequests.delete(msg.requestId);
+    const responseId = typeof msg.id === "string" ? msg.id : typeof msg.requestId === "string" ? msg.requestId : null;
+    if (responseId && this.pendingRequests.has(responseId)) {
+      const req = this.pendingRequests.get(responseId);
+      this.pendingRequests.delete(responseId);
       clearTimeout(req.timer);
       req.resolve(msg);
       return;
@@ -3565,10 +3591,10 @@ var AlphaWebSocket = class {
     }
   }
   sendSubscribe(stream, params) {
-    this.send({ method: "SUBSCRIBE", stream, ...params });
+    this.send({ method: "SUBSCRIBE", params: [{ stream, ...params }] });
   }
   sendUnsubscribe(stream, params) {
-    this.send({ method: "UNSUBSCRIBE", stream, ...params });
+    this.send({ method: "UNSUBSCRIBE", params: [{ stream, ...params }] });
   }
   sendRequest(payload, timeoutMs = 1e4) {
     const requestId = crypto.randomUUID();
@@ -3580,10 +3606,10 @@ var AlphaWebSocket = class {
       this.pendingRequests.set(requestId, { resolve, reject, timer });
       if (!this.connected) {
         this.connect().then(() => {
-          this.send({ ...payload, requestId });
+          this.send({ ...payload, id: requestId });
         }).catch(reject);
       } else {
-        this.send({ ...payload, requestId });
+        this.send({ ...payload, id: requestId });
       }
     });
   }
@@ -3598,7 +3624,7 @@ var AlphaWebSocket = class {
   startHeartbeat() {
     this.stopHeartbeat();
     this.heartbeatTimer = setInterval(() => {
-      this.send({ type: "ping" });
+      this.send({ method: "PING" });
     }, this.heartbeatIntervalMs);
   }
   stopHeartbeat() {