@alpha-arcade/sdk 0.3.0 → 0.4.0

package/dist/index.d.cts

@@ -147,6 +147,18 @@ type ProposeMatchParams = {
     /** Quantity to match in microunits */
     quantityMatched: number;
 };
+/**
+ * Parameters for matching two existing limit orders (e.g. after an amend).
+ * The taker is the order placed last and pays the fee; the maker is the counterparty.
+ */
+type ProcessMatchParams = {
+    /** Market app ID */
+    marketAppId: number;
+    /** Maker escrow app ID (existing order — was on the book first) */
+    makerEscrowAppId: number;
+    /** Taker escrow app ID (existing order — placed last, pays the fee) */
+    takerEscrowAppId: number;
+};
 /** Parameters for amending (editing) an existing unfilled order */
 type AmendOrderParams = {
     /** Market app ID */
@@ -202,6 +214,15 @@ type ProposeMatchResult = {
     /** Confirmed round number */
     confirmedRound: number;
 };
+/** Result of processing a match between two existing orders */
+type ProcessMatchResult = {
+    /** Whether the match succeeded */
+    success: boolean;
+    /** Transaction IDs */
+    txIds: string[];
+    /** Confirmed round number */
+    confirmedRound: number;
+};
 /** Result of amending an order */
 type AmendOrderResult = {
     /** Whether the amendment succeeded */
@@ -210,6 +231,10 @@ type AmendOrderResult = {
     txIds: string[];
     /** Confirmed round number */
     confirmedRound: number;
+    /** Total quantity matched against counterparty orders (if matching was performed) */
+    matchedQuantity?: number;
+    /** Volume-weighted average fill price in microunits (if any matches) */
+    matchedPrice?: number;
 };
 /** A single entry in the orderbook (one price level, one order) */
 type OrderbookEntry = {
@@ -337,6 +362,76 @@ type EscrowGlobalState = {
     asset_listed?: number;
     fee_timer_start?: number;
 };
+/** Configuration for AlphaWebSocket */
+type AlphaWebSocketConfig = {
+    /** WebSocket URL override (default: wss://wss.platform.alphaarcade.com) */
+    url?: string;
+    /** Enable auto-reconnect on unexpected disconnect (default: true) */
+    reconnect?: boolean;
+    /** Maximum reconnect attempts before giving up (default: Infinity) */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in ms (default: 60000) */
+    heartbeatIntervalMs?: number;
+    /**
+     * WebSocket constructor to use. Defaults to the global `WebSocket`.
+     * On Node.js < 22, pass the `ws` package: `import WebSocket from 'ws'; new AlphaWebSocket({ WebSocket })`
+     */
+    WebSocket?: unknown;
+};
+/** Orderbook bid/ask entry at the top level (decimal cents) */
+type WsOrderbookAggregatedEntry = {
+    price: number;
+    quantity: number;
+    total: number;
+};
+/** Orderbook bid/ask entry with escrow details (raw microunit prices) */
+type WsOrderbookDetailEntry = {
+    price: number;
+    quantity: number;
+    total: number;
+    escrowAppId: number;
+    owner: string;
+};
+/** Per-side orderbook detail (yes or no) */
+type WsOrderbookDetailSide = {
+    bids: WsOrderbookDetailEntry[];
+    asks: WsOrderbookDetailEntry[];
+};
+/** Orderbook data for a single app within the orderbook payload */
+type WsOrderbookApp = {
+    bids: WsOrderbookAggregatedEntry[];
+    asks: WsOrderbookAggregatedEntry[];
+    spread: number;
+    yes: WsOrderbookDetailSide;
+    no: WsOrderbookDetailSide;
+};
+/** Payload for orderbook_changed events */
+type OrderbookChangedEvent = {
+    type: 'orderbook_changed';
+    ts: number;
+    marketId: string;
+    orderbook: Record<string, WsOrderbookApp>;
+};
+/** Payload for markets_changed events (incremental diffs) */
+type MarketsChangedEvent = {
+    type: 'markets_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Payload for market_changed events (single market) */
+type MarketChangedEvent = {
+    type: 'market_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Payload for wallet_orders_changed events */
+type WalletOrdersChangedEvent = {
+    type: 'wallet_orders_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Discriminated union of all WebSocket stream events */
+type WebSocketStreamEvent = MarketsChangedEvent | MarketChangedEvent | OrderbookChangedEvent | WalletOrdersChangedEvent;
 
 /**
  * The main client for interacting with Alpha Market prediction markets on Algorand.
@@ -423,6 +518,17 @@ declare class AlphaClient {
      * @returns Whether the match succeeded
      */
     proposeMatch(params: ProposeMatchParams): Promise<ProposeMatchResult>;
+    /**
+     * Matches two existing limit orders (no create-escrow in the group).
+     *
+     * Calls the market app's process_potential_match(maker, taker). Use this
+     * after amending an order: the amended order is the taker (pays the fee),
+     * the counterparty is the maker.
+     *
+     * @param params - Process match params (marketAppId, makerEscrowAppId, takerEscrowAppId)
+     * @returns Whether the match succeeded
+     */
+    processMatch(params: ProcessMatchParams): Promise<ProcessMatchResult>;
     /**
      * Amends (edits) an existing unfilled order in-place.
      *
@@ -561,6 +667,93 @@ declare class AlphaClient {
     getMarketFromApi(marketId: string): Promise<Market | null>;
 }
 
+/**
+ * Real-time WebSocket client for Alpha Market platform streams.
+ *
+ * Connects to `wss://wss.platform.alphaarcade.com` and provides typed,
+ * callback-based subscriptions for live market data. No auth required.
+ *
+ * @example
+ * ```typescript
+ * // Node.js 22+ or browser (native WebSocket)
+ * const ws = new AlphaWebSocket();
+ *
+ * // Node.js < 22 — pass the `ws` package
+ * import WebSocket from 'ws';
+ * const ws = new AlphaWebSocket({ WebSocket });
+ *
+ * const unsub = ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+ *   console.log('Orderbook:', event.orderbook);
+ * });
+ *
+ * // Later
+ * unsub();
+ * ws.close();
+ * ```
+ */
+declare class AlphaWebSocket {
+    private url;
+    private reconnectEnabled;
+    private maxReconnectAttempts;
+    private heartbeatIntervalMs;
+    private WebSocketImpl;
+    private ws;
+    private subscriptions;
+    private pendingRequests;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private intentionallyClosed;
+    private connectPromise;
+    constructor(config?: AlphaWebSocketConfig);
+    /** Whether the WebSocket is currently open and connected */
+    get connected(): boolean;
+    /**
+     * Subscribe to live market probability updates (incremental diffs).
+     * @returns An unsubscribe function
+     */
+    subscribeLiveMarkets(callback: (event: MarketsChangedEvent) => void): () => void;
+    /**
+     * Subscribe to change events for a single market.
+     * @param slug - The market slug
+     * @returns An unsubscribe function
+     */
+    subscribeMarket(slug: string, callback: (event: MarketChangedEvent) => void): () => void;
+    /**
+     * Subscribe to full orderbook snapshots (~5s interval on changes).
+     * @param slug - The market slug
+     * @returns An unsubscribe function
+     */
+    subscribeOrderbook(slug: string, callback: (event: OrderbookChangedEvent) => void): () => void;
+    /**
+     * Subscribe to wallet order updates.
+     * @param wallet - The wallet address
+     * @returns An unsubscribe function
+     */
+    subscribeWalletOrders(wallet: string, callback: (event: WalletOrdersChangedEvent) => void): () => void;
+    /** Query the server for the list of active subscriptions on this connection */
+    listSubscriptions(): Promise<unknown>;
+    /** Query a server property (e.g. "heartbeat", "limits") */
+    getProperty(property: string): Promise<unknown>;
+    /** Open the WebSocket connection. Called automatically on first subscribe. */
+    connect(): Promise<void>;
+    /** Close the connection and clean up all resources */
+    close(): void;
+    private buildStreamKey;
+    private buildQueryString;
+    private subscribe;
+    private doConnect;
+    private handleMessage;
+    private sendSubscribe;
+    private sendUnsubscribe;
+    private sendRequest;
+    private send;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private clearTimers;
+}
+
 /**
  * Fetches all live, tradeable markets directly from the Algorand blockchain.
  *
@@ -603,6 +796,7 @@ declare const getLiveMarketsFromApi: (config: AlphaClientConfig) => Promise<Mark
 declare const getMarketFromApi: (config: AlphaClientConfig, marketId: string) => Promise<Market | null>;
 
 declare const DEFAULT_API_BASE_URL = "https://platform.alphaarcade.com/api";
+declare const DEFAULT_WSS_BASE_URL = "wss://wss.platform.alphaarcade.com";
 declare const DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
 
 /**
@@ -684,4 +878,4 @@ declare const getEscrowGlobalState: (indexerClient: algosdk.Indexer, escrowAppId
  */
 declare const checkAssetOptIn: (algodClient: algosdk.Algodv2, address: string, assetId: number) => Promise<boolean>;
 
-export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, type AmendOrderParams, type AmendOrderResult, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateOrderResult, DEFAULT_API_BASE_URL, DEFAULT_MARKET_CREATOR_ADDRESS, type EscrowGlobalState, type Market, type MarketGlobalState, type MarketOption, type MergeSharesParams, type OpenOrder, type OrderSide, type Orderbook, type OrderbookEntry, type OrderbookSide, type Position, type ProposeMatchParams, type ProposeMatchResult, type SplitMergeResult, type SplitSharesParams, type WalletPosition, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getLiveMarketsFromApi, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsOnChain };
+export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, AlphaWebSocket, type AlphaWebSocketConfig, type AmendOrderParams, type AmendOrderResult, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateOrderResult, DEFAULT_API_BASE_URL, DEFAULT_MARKET_CREATOR_ADDRESS, DEFAULT_WSS_BASE_URL, type EscrowGlobalState, type Market, type MarketChangedEvent, type MarketGlobalState, type MarketOption, type MarketsChangedEvent, type MergeSharesParams, type OpenOrder, type OrderSide, type Orderbook, type OrderbookChangedEvent, type OrderbookEntry, type OrderbookSide, type Position, type ProcessMatchParams, type ProcessMatchResult, type ProposeMatchParams, type ProposeMatchResult, type SplitMergeResult, type SplitSharesParams, type WalletOrdersChangedEvent, type WalletPosition, type WebSocketStreamEvent, type WsOrderbookAggregatedEntry, type WsOrderbookApp, type WsOrderbookDetailEntry, type WsOrderbookDetailSide, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getLiveMarketsFromApi, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsOnChain };

package/dist/index.d.ts

@@ -147,6 +147,18 @@ type ProposeMatchParams = {
     /** Quantity to match in microunits */
     quantityMatched: number;
 };
+/**
+ * Parameters for matching two existing limit orders (e.g. after an amend).
+ * The taker is the order placed last and pays the fee; the maker is the counterparty.
+ */
+type ProcessMatchParams = {
+    /** Market app ID */
+    marketAppId: number;
+    /** Maker escrow app ID (existing order — was on the book first) */
+    makerEscrowAppId: number;
+    /** Taker escrow app ID (existing order — placed last, pays the fee) */
+    takerEscrowAppId: number;
+};
 /** Parameters for amending (editing) an existing unfilled order */
 type AmendOrderParams = {
     /** Market app ID */
@@ -202,6 +214,15 @@ type ProposeMatchResult = {
     /** Confirmed round number */
     confirmedRound: number;
 };
+/** Result of processing a match between two existing orders */
+type ProcessMatchResult = {
+    /** Whether the match succeeded */
+    success: boolean;
+    /** Transaction IDs */
+    txIds: string[];
+    /** Confirmed round number */
+    confirmedRound: number;
+};
 /** Result of amending an order */
 type AmendOrderResult = {
     /** Whether the amendment succeeded */
@@ -210,6 +231,10 @@ type AmendOrderResult = {
     txIds: string[];
     /** Confirmed round number */
     confirmedRound: number;
+    /** Total quantity matched against counterparty orders (if matching was performed) */
+    matchedQuantity?: number;
+    /** Volume-weighted average fill price in microunits (if any matches) */
+    matchedPrice?: number;
 };
 /** A single entry in the orderbook (one price level, one order) */
 type OrderbookEntry = {
@@ -337,6 +362,76 @@ type EscrowGlobalState = {
     asset_listed?: number;
     fee_timer_start?: number;
 };
+/** Configuration for AlphaWebSocket */
+type AlphaWebSocketConfig = {
+    /** WebSocket URL override (default: wss://wss.platform.alphaarcade.com) */
+    url?: string;
+    /** Enable auto-reconnect on unexpected disconnect (default: true) */
+    reconnect?: boolean;
+    /** Maximum reconnect attempts before giving up (default: Infinity) */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in ms (default: 60000) */
+    heartbeatIntervalMs?: number;
+    /**
+     * WebSocket constructor to use. Defaults to the global `WebSocket`.
+     * On Node.js < 22, pass the `ws` package: `import WebSocket from 'ws'; new AlphaWebSocket({ WebSocket })`
+     */
+    WebSocket?: unknown;
+};
+/** Orderbook bid/ask entry at the top level (decimal cents) */
+type WsOrderbookAggregatedEntry = {
+    price: number;
+    quantity: number;
+    total: number;
+};
+/** Orderbook bid/ask entry with escrow details (raw microunit prices) */
+type WsOrderbookDetailEntry = {
+    price: number;
+    quantity: number;
+    total: number;
+    escrowAppId: number;
+    owner: string;
+};
+/** Per-side orderbook detail (yes or no) */
+type WsOrderbookDetailSide = {
+    bids: WsOrderbookDetailEntry[];
+    asks: WsOrderbookDetailEntry[];
+};
+/** Orderbook data for a single app within the orderbook payload */
+type WsOrderbookApp = {
+    bids: WsOrderbookAggregatedEntry[];
+    asks: WsOrderbookAggregatedEntry[];
+    spread: number;
+    yes: WsOrderbookDetailSide;
+    no: WsOrderbookDetailSide;
+};
+/** Payload for orderbook_changed events */
+type OrderbookChangedEvent = {
+    type: 'orderbook_changed';
+    ts: number;
+    marketId: string;
+    orderbook: Record<string, WsOrderbookApp>;
+};
+/** Payload for markets_changed events (incremental diffs) */
+type MarketsChangedEvent = {
+    type: 'markets_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Payload for market_changed events (single market) */
+type MarketChangedEvent = {
+    type: 'market_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Payload for wallet_orders_changed events */
+type WalletOrdersChangedEvent = {
+    type: 'wallet_orders_changed';
+    ts: number;
+    [key: string]: unknown;
+};
+/** Discriminated union of all WebSocket stream events */
+type WebSocketStreamEvent = MarketsChangedEvent | MarketChangedEvent | OrderbookChangedEvent | WalletOrdersChangedEvent;
 
 /**
  * The main client for interacting with Alpha Market prediction markets on Algorand.
@@ -423,6 +518,17 @@ declare class AlphaClient {
      * @returns Whether the match succeeded
      */
     proposeMatch(params: ProposeMatchParams): Promise<ProposeMatchResult>;
+    /**
+     * Matches two existing limit orders (no create-escrow in the group).
+     *
+     * Calls the market app's process_potential_match(maker, taker). Use this
+     * after amending an order: the amended order is the taker (pays the fee),
+     * the counterparty is the maker.
+     *
+     * @param params - Process match params (marketAppId, makerEscrowAppId, takerEscrowAppId)
+     * @returns Whether the match succeeded
+     */
+    processMatch(params: ProcessMatchParams): Promise<ProcessMatchResult>;
     /**
      * Amends (edits) an existing unfilled order in-place.
      *
@@ -561,6 +667,93 @@ declare class AlphaClient {
     getMarketFromApi(marketId: string): Promise<Market | null>;
 }
 
+/**
+ * Real-time WebSocket client for Alpha Market platform streams.
+ *
+ * Connects to `wss://wss.platform.alphaarcade.com` and provides typed,
+ * callback-based subscriptions for live market data. No auth required.
+ *
+ * @example
+ * ```typescript
+ * // Node.js 22+ or browser (native WebSocket)
+ * const ws = new AlphaWebSocket();
+ *
+ * // Node.js < 22 — pass the `ws` package
+ * import WebSocket from 'ws';
+ * const ws = new AlphaWebSocket({ WebSocket });
+ *
+ * const unsub = ws.subscribeOrderbook('will-btc-hit-100k', (event) => {
+ *   console.log('Orderbook:', event.orderbook);
+ * });
+ *
+ * // Later
+ * unsub();
+ * ws.close();
+ * ```
+ */
+declare class AlphaWebSocket {
+    private url;
+    private reconnectEnabled;
+    private maxReconnectAttempts;
+    private heartbeatIntervalMs;
+    private WebSocketImpl;
+    private ws;
+    private subscriptions;
+    private pendingRequests;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private intentionallyClosed;
+    private connectPromise;
+    constructor(config?: AlphaWebSocketConfig);
+    /** Whether the WebSocket is currently open and connected */
+    get connected(): boolean;
+    /**
+     * Subscribe to live market probability updates (incremental diffs).
+     * @returns An unsubscribe function
+     */
+    subscribeLiveMarkets(callback: (event: MarketsChangedEvent) => void): () => void;
+    /**
+     * Subscribe to change events for a single market.
+     * @param slug - The market slug
+     * @returns An unsubscribe function
+     */
+    subscribeMarket(slug: string, callback: (event: MarketChangedEvent) => void): () => void;
+    /**
+     * Subscribe to full orderbook snapshots (~5s interval on changes).
+     * @param slug - The market slug
+     * @returns An unsubscribe function
+     */
+    subscribeOrderbook(slug: string, callback: (event: OrderbookChangedEvent) => void): () => void;
+    /**
+     * Subscribe to wallet order updates.
+     * @param wallet - The wallet address
+     * @returns An unsubscribe function
+     */
+    subscribeWalletOrders(wallet: string, callback: (event: WalletOrdersChangedEvent) => void): () => void;
+    /** Query the server for the list of active subscriptions on this connection */
+    listSubscriptions(): Promise<unknown>;
+    /** Query a server property (e.g. "heartbeat", "limits") */
+    getProperty(property: string): Promise<unknown>;
+    /** Open the WebSocket connection. Called automatically on first subscribe. */
+    connect(): Promise<void>;
+    /** Close the connection and clean up all resources */
+    close(): void;
+    private buildStreamKey;
+    private buildQueryString;
+    private subscribe;
+    private doConnect;
+    private handleMessage;
+    private sendSubscribe;
+    private sendUnsubscribe;
+    private sendRequest;
+    private send;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private clearTimers;
+}
+
 /**
  * Fetches all live, tradeable markets directly from the Algorand blockchain.
  *
@@ -603,6 +796,7 @@ declare const getLiveMarketsFromApi: (config: AlphaClientConfig) => Promise<Mark
 declare const getMarketFromApi: (config: AlphaClientConfig, marketId: string) => Promise<Market | null>;
 
 declare const DEFAULT_API_BASE_URL = "https://platform.alphaarcade.com/api";
+declare const DEFAULT_WSS_BASE_URL = "wss://wss.platform.alphaarcade.com";
 declare const DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
 
 /**
@@ -684,4 +878,4 @@ declare const getEscrowGlobalState: (indexerClient: algosdk.Indexer, escrowAppId
  */
 declare const checkAssetOptIn: (algodClient: algosdk.Algodv2, address: string, assetId: number) => Promise<boolean>;
 
-export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, type AmendOrderParams, type AmendOrderResult, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateOrderResult, DEFAULT_API_BASE_URL, DEFAULT_MARKET_CREATOR_ADDRESS, type EscrowGlobalState, type Market, type MarketGlobalState, type MarketOption, type MergeSharesParams, type OpenOrder, type OrderSide, type Orderbook, type OrderbookEntry, type OrderbookSide, type Position, type ProposeMatchParams, type ProposeMatchResult, type SplitMergeResult, type SplitSharesParams, type WalletPosition, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getLiveMarketsFromApi, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsOnChain };
+export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, AlphaWebSocket, type AlphaWebSocketConfig, type AmendOrderParams, type AmendOrderResult, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateOrderResult, DEFAULT_API_BASE_URL, DEFAULT_MARKET_CREATOR_ADDRESS, DEFAULT_WSS_BASE_URL, type EscrowGlobalState, type Market, type MarketChangedEvent, type MarketGlobalState, type MarketOption, type MarketsChangedEvent, type MergeSharesParams, type OpenOrder, type OrderSide, type Orderbook, type OrderbookChangedEvent, type OrderbookEntry, type OrderbookSide, type Position, type ProcessMatchParams, type ProcessMatchResult, type ProposeMatchParams, type ProposeMatchResult, type SplitMergeResult, type SplitSharesParams, type WalletOrdersChangedEvent, type WalletPosition, type WebSocketStreamEvent, type WsOrderbookAggregatedEntry, type WsOrderbookApp, type WsOrderbookDetailEntry, type WsOrderbookDetailSide, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getLiveMarketsFromApi, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsOnChain };