@alpha-arcade/sdk 0.2.6 → 0.2.8

package/README.md

@@ -12,6 +12,24 @@ npm install @alpha-arcade/sdk algosdk @algorandfoundation/algokit-utils
 
 `algosdk` and `@algorandfoundation/algokit-utils` are peer dependencies.
 
+## Getting an API key
+
+An API key is **optional**. Without it, you can still fetch markets on-chain, place orders, and use most SDK features. With an API key, you get richer market data, liquidity rewards information, and wallet order lookups, and more.
+
+To get an API key:
+
+1. Go to [alphaarcade.com](https://alphaarcade.com) and **sign up** with your email or Google account.
+2. Open the **Account** page 
+3. Open the **Partners** tab.
+4. Click **Create API key** and copy the key.
+5. Add it to your environment (e.g. a `.env` file in the project root):
+
+```bash
+ALPHA_API_KEY=your_api_key_here
+```
+
+Then pass it when creating the client: `apiKey: process.env.ALPHA_API_KEY`.
+
 ## Quick Start
 
 ```typescript
@@ -53,6 +71,21 @@ const result = await client.createLimitOrder({
 console.log(`Order created! Escrow app ID: ${result.escrowAppId}`);
 ```
 
+## Examples
+
+The repo includes runnable examples (use `npx tsx examples/<script>.ts`). Scripts that call the API (e.g. `get-orders.ts`, `get-reward-markets.ts`) need `ALPHA_API_KEY` in your `.env` — see [Getting an API key](#getting-an-api-key). Trading examples also need `TEST_MNEMONIC`.
+
+| Script | Description |
+|--------|-------------|
+| `get-orders.ts` | Fetch all open orders for a wallet via the API (`getWalletOrdersFromApi`) |
+| `get-reward-markets.ts` | Fetch reward markets and show liquidity reward info (`getRewardMarkets`) |
+| `get-positions.ts` | List token positions across markets (`getPositions`) |
+| `place-limit-order.ts` | Place a limit order |
+| `place-market-order.ts` | Place a market order |
+| `cancel-order.ts` | Cancel an open order |
+| `split-merge.ts` | Split USDC into YES/NO and merge back |
+| `simple-trading-bot.ts` | Example bot that scans markets and places market orders |
+
 ## API Reference
 
 ### AlphaClient
@@ -71,8 +104,8 @@ new AlphaClient(config: AlphaClientConfig)
 | `activeAddress` | `string` | Yes | Your Algorand address |
 | `matcherAppId` | `number` | Yes | Matcher contract app ID (mainnet: `3078581851`) |
 | `usdcAssetId` | `number` | Yes | USDC ASA ID (mainnet: `31566704`) |
-| `apiKey` | `string` | No | Alpha partners API key. If provided, `getLiveMarkets()` uses the API for richer data (images, categories, volume). If omitted, markets are discovered on-chain. |
-| `apiBaseUrl` | `string` | No | API base URL (default: `https://partners.alphaarcade.com/api`) |
+| `apiKey` | `string` | No | Alpha API key. If provided, `getLiveMarkets()` and related API methods use the platform for richer data (images, categories, volume, reward markets, wallet orders). If omitted, markets are discovered on-chain. |
+| `apiBaseUrl` | `string` | No | API base URL (default: `https://platform.alphaarcade.com/api`) |
 | `marketCreatorAddress` | `string` | No | Market creator address for on-chain discovery (defaults to Alpha Arcade mainnet) |
 
 ---
@@ -211,7 +244,7 @@ if (book.yes.bids.length > 0) {
 
 #### `getOpenOrders(marketAppId, walletAddress?)`
 
-Gets open orders for a wallet on a specific market.
+Gets open orders for a wallet on a specific market (from on-chain data).
 
 ```typescript
 const orders = await client.getOpenOrders(123456789);
@@ -222,6 +255,17 @@ for (const order of orders) {
 }
 ```
 
+#### `getWalletOrdersFromApi(walletAddress)`
+
+Gets all open orders for a wallet across every live market via the Alpha REST API. Requires `apiKey`. Paginates automatically.
+
+```typescript
+const orders = await client.getWalletOrdersFromApi('ALGO_ADDRESS...');
+for (const order of orders) {
+  console.log(`Market ${order.marketAppId} | Escrow ${order.escrowAppId} | ${order.quantityFilled / 1e6} filled`);
+}
+```
+
 ---
 
 ### Markets
@@ -259,6 +303,17 @@ const markets = await client.getLiveMarketsFromApi();
 const market = await client.getMarketFromApi('uuid-here');
 ```
 
+#### `getRewardMarkets()`
+
+Fetches markets that have liquidity rewards from the Alpha REST API. Requires `apiKey`. Returns the same `Market[]` shape with reward fields populated: `totalRewards`, `rewardsPaidOut`, `rewardsSpreadDistance`, `rewardsMinContracts`, `lastRewardAmount`, `lastRewardTs`.
+
+```typescript
+const rewardMarkets = await client.getRewardMarkets();
+for (const m of rewardMarkets) {
+  console.log(`${m.title}: $${(m.totalRewards ?? 0) / 1e6} total rewards`);
+}
+```
+
 ---
 
 ### Utility Functions

package/dist/index.cjs

@@ -1427,6 +1427,12 @@ var calculateMatchingOrders = (orderbook, isBuying, isYes, quantity, price, slip
   }
   return matches;
 };
+
+// src/constants.ts
+var DEFAULT_API_BASE_URL = "https://platform.alphaarcade.com/api";
+var DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
+
+// src/modules/orderbook.ts
 var getAllCreatedApplications = async (indexerClient, address, limit = 100) => {
   let applications = [];
   let nextToken;
@@ -1520,6 +1526,49 @@ var getOpenOrders = async (config, marketAppId, walletAddress) => {
     owner: o.globalState.owner ?? ""
   }));
 };
+var normalizeApiOrder = (raw) => ({
+  escrowAppId: Number(raw.escrowAppId ?? raw.orderId),
+  marketAppId: Number(raw.marketAppId),
+  position: raw.orderPosition ?? 0,
+  side: raw.orderSide === "BUY" ? 1 : 0,
+  price: raw.orderPrice ?? 0,
+  quantity: raw.orderQuantity ?? 0,
+  quantityFilled: raw.orderQuantityFilled ?? 0,
+  slippage: raw.slippage ?? 0,
+  owner: raw.senderWallet ?? ""
+});
+var getWalletOrdersFromApi = async (config, walletAddress) => {
+  if (!config.apiKey) {
+    throw new Error("apiKey is required for API-based market 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 allOrders = [];
+  let cursor;
+  let hasMore = true;
+  while (hasMore) {
+    const params = new URLSearchParams({ wallet: walletAddress, limit: "300" });
+    if (cursor) {
+      params.set("cursor", cursor);
+    }
+    const url = `${baseUrl}/get-wallet-orders?${params.toString()}`;
+    const response = await fetch(url, { headers: { "x-api-key": config.apiKey } });
+    if (!response.ok) {
+      throw new Error(`Alpha API error: ${response.status} ${response.statusText}`);
+    }
+    const data = await response.json();
+    if (Array.isArray(data)) {
+      allOrders.push(...data.map(normalizeApiOrder));
+      hasMore = false;
+    } else if (data.orders) {
+      allOrders.push(...data.orders.map(normalizeApiOrder));
+      cursor = data.nextCursor ?? void 0;
+      hasMore = data.hasMore === true && !!cursor;
+    } else {
+      hasMore = false;
+    }
+  }
+  return allOrders;
+};
 
 // src/modules/trading.ts
 var extractEscrowAppId = async (algodClient, indexerClient, targetTxId) => {
@@ -1981,8 +2030,6 @@ var getPositions = async (config, walletAddress) => {
 };
 
 // src/modules/markets.ts
-var DEFAULT_API_BASE_URL = "https://partners.alphaarcade.com/api";
-var DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
 var toSeconds = (ts) => ts > 1e10 ? Math.floor(ts / 1e3) : ts;
 var groupMultiChoiceMarkets = (flatMarkets) => {
   const parentMap = /* @__PURE__ */ new Map();
@@ -2096,7 +2143,7 @@ var getMarketOnChain = async (config, marketAppId) => {
 };
 var getLiveMarketsFromApi = async (config) => {
   if (!config.apiKey) {
-    throw new Error("apiKey is required for API-based market fetching. Use getMarketsOnChain() instead, or pass an apiKey.");
+    throw new Error("apiKey is required for API-based market fetching. Use getMarketsOnChain() instead, or 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 allMarkets = [];
@@ -2133,7 +2180,7 @@ var getLiveMarketsFromApi = async (config) => {
 };
 var getMarketFromApi = async (config, marketId) => {
   if (!config.apiKey) {
-    throw new Error("apiKey is required for API-based market fetching. Use getMarketOnChain() instead, or pass an apiKey.");
+    throw new Error("apiKey is required for API-based market fetching. Use getMarketOnChain() instead, or 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-market?marketId=${encodeURIComponent(marketId)}`;
@@ -2150,6 +2197,13 @@ var getMarketFromApi = async (config, marketId) => {
   }
   return market;
 };
+var getRewardMarkets = async (config) => {
+  if (!config.apiKey) {
+    throw new Error("apiKey is required for API-based market fetching. Retrieve an API key from the Alpha Arcade platform via the Account page and pass it to the client.");
+  }
+  const markets = await getLiveMarketsFromApi(config);
+  return markets.filter((m) => m.totalRewards && m.totalRewards > 0);
+};
 var getLiveMarkets = async (config) => {
   if (config.apiKey) {
     return getLiveMarketsFromApi(config);
@@ -2175,7 +2229,7 @@ var AlphaClient = class {
     if (!config.usdcAssetId) throw new Error("usdcAssetId is required");
     this.config = {
       ...config,
-      apiBaseUrl: config.apiBaseUrl ?? "https://partners.alphaarcade.com/api"
+      apiBaseUrl: config.apiBaseUrl ?? DEFAULT_API_BASE_URL
     };
   }
   // ============================================
@@ -2307,6 +2361,15 @@ var AlphaClient = class {
   async getOpenOrders(marketAppId, walletAddress) {
     return getOpenOrders(this.config, marketAppId, walletAddress);
   }
+  /**
+   * Gets all open orders for a wallet across every live market using the Alpha REST API.
+   *
+   * @param walletAddress - The wallet address
+   * @returns Array of open orders for the wallet
+   */
+  async getWalletOrdersFromApi(walletAddress) {
+    return getWalletOrdersFromApi(this.config, walletAddress);
+  }
   // ============================================
   // Markets
   // ============================================
@@ -2364,6 +2427,14 @@ var AlphaClient = class {
   async getLiveMarketsFromApi() {
     return getLiveMarketsFromApi(this.config);
   }
+  /**
+   * Fetches the reward markets from the Alpha REST API (requires API key).
+   *
+   * @returns Array of reward markets
+   */
+  async getRewardMarkets() {
+    return getRewardMarkets(this.config);
+  }
   /**
    * Fetches a single market by ID from the Alpha REST API (requires API key).
    *
@@ -2376,6 +2447,7 @@ var AlphaClient = class {
 };
 
 exports.AlphaClient = AlphaClient;
+exports.DEFAULT_API_BASE_URL = DEFAULT_API_BASE_URL;
 exports.DEFAULT_MARKET_CREATOR_ADDRESS = DEFAULT_MARKET_CREATOR_ADDRESS;
 exports.calculateFee = calculateFee;
 exports.calculateFeeFromTotal = calculateFeeFromTotal;