@alpha-arcade/sdk 0.1.2 → 0.2.0

package/README.md

@@ -26,7 +26,7 @@ const indexerClient = new algosdk.Indexer('', 'https://mainnet-idx.algonode.clou
 const account = algosdk.mnemonicToSecretKey('your twenty five word mnemonic ...');
 const signer = algosdk.makeBasicAccountTransactionSigner(account);
 
-// 3. Initialize the client
+// 3. Initialize the client (no API key needed!)
 const client = new AlphaClient({
   algodClient,
   indexerClient,
@@ -34,10 +34,9 @@ const client = new AlphaClient({
   activeAddress: account.addr,
   matcherAppId: 3078581851,
   usdcAssetId: 31566704,
-  apiKey: 'YOUR_API_KEY',
 });
 
-// 4. Fetch live markets
+// 4. Fetch live markets (reads directly from chain)
 const markets = await client.getMarkets();
 console.log(`Found ${markets.length} live markets`);
 
@@ -72,8 +71,9 @@ 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` | Yes | Alpha partners API key (x-api-key header) |
+| `apiKey` | `string` | No | Alpha partners API key. If provided, `getMarkets()` 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`) |
+| `marketCreatorAddress` | `string` | No | Market creator address for on-chain discovery (defaults to Alpha Arcade mainnet) |
 
 ---
 
@@ -226,26 +226,37 @@ for (const order of orders) {
 
 ### Markets
 
-#### `getMarkets()`
+Markets can be loaded **on-chain** (default, no API key) or via the **REST API** (richer data, requires API key).
 
-Fetches all live, tradeable markets.
+#### `getMarkets()` / `getMarket(marketId)`
+
+Smart defaults — uses the API if `apiKey` is set, otherwise reads from chain.
 
 ```typescript
 const markets = await client.getMarkets();
 for (const m of markets) {
-  console.log(`${m.title} — Yes: ${m.yesProb}%, Vol: $${m.volume}`);
+  console.log(`${m.title} — App ID: ${m.marketAppId}, source: ${m.source}`);
 }
+
+const market = await client.getMarket('12345'); // app ID string for on-chain, UUID for API
 ```
 
-#### `getMarket(marketId)`
+#### `getMarketsOnChain()` / `getMarketOnChain(marketAppId)`
 
-Fetches a single market by ID.
+Always reads from the blockchain. No API key needed. Returns core data: title, asset IDs, resolution time, fees.
 
 ```typescript
-const market = await client.getMarket('abc123');
-if (market) {
-  console.log(market.title, market.marketAppId);
-}
+const markets = await client.getMarketsOnChain();
+const market = await client.getMarketOnChain(3012345678);
+```
+
+#### `getMarketsFromApi()` / `getMarketFromApi(marketId)`
+
+Always uses the REST API. Requires `apiKey`. Returns richer data: images, categories, volume, probabilities.
+
+```typescript
+const markets = await client.getMarketsFromApi();
+const market = await client.getMarketFromApi('uuid-here');
 ```
 
 ---
@@ -296,13 +307,12 @@ const setup = () => {
     activeAddress: account.addr,
     matcherAppId: 3078581851,
     usdcAssetId: 31566704,
-    apiKey: 'YOUR_API_KEY',
   });
 };
 
 const run = async () => {
   const client = setup();
-  const markets = await client.getMarkets();
+  const markets = await client.getMarkets(); // Loads from chain, no API key needed
 
   for (const market of markets) {
     const book = await client.getOrderbook(market.marketAppId);

package/dist/index.cjs

@@ -1955,7 +1955,121 @@ var getPositions = async (config, walletAddress) => {
 
 // src/modules/markets.ts
 var DEFAULT_API_BASE_URL = "https://partners.alphaarcade.com/api";
-var getMarkets = async (config) => {
+var DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
+var groupMultiChoiceMarkets = (flatMarkets) => {
+  const parentMap = /* @__PURE__ */ new Map();
+  const result = [];
+  for (const m of flatMarkets) {
+    const separatorIdx = m.title.lastIndexOf(" : ");
+    if (separatorIdx === -1) {
+      result.push(m);
+      continue;
+    }
+    const parentTitle = m.title.substring(0, separatorIdx).trim();
+    const optionTitle = m.title.substring(separatorIdx + 3).trim();
+    let parent = parentMap.get(parentTitle);
+    if (!parent) {
+      parent = {
+        id: `group:${parentTitle}`,
+        title: parentTitle,
+        marketAppId: m.marketAppId,
+        // Use first option's app ID as the parent's
+        yesAssetId: 0,
+        noAssetId: 0,
+        endTs: m.endTs,
+        isResolved: m.isResolved,
+        isLive: m.isLive,
+        feeBase: m.feeBase,
+        source: "onchain",
+        options: []
+      };
+      parentMap.set(parentTitle, parent);
+      result.push(parent);
+    }
+    parent.options.push({
+      id: m.id,
+      title: optionTitle,
+      marketAppId: m.marketAppId,
+      yesAssetId: m.yesAssetId,
+      noAssetId: m.noAssetId,
+      yesProb: 0,
+      noProb: 0
+    });
+  }
+  return result;
+};
+var getMarketsOnChain = async (config, options) => {
+  const creatorAddress = config.marketCreatorAddress ?? DEFAULT_MARKET_CREATOR_ADDRESS;
+  const activeOnly = options?.activeOnly ?? true;
+  const allApps = [];
+  let nextToken;
+  let hasMore = true;
+  while (hasMore) {
+    let query = config.indexerClient.lookupAccountCreatedApplications(creatorAddress).limit(100);
+    if (nextToken) {
+      query = query.nextToken(nextToken);
+    }
+    const response = await query.do();
+    if (response.applications?.length) {
+      allApps.push(...response.applications);
+    }
+    if (response["next-token"]) {
+      nextToken = response["next-token"];
+    } else {
+      hasMore = false;
+    }
+  }
+  const flatMarkets = [];
+  for (const app of allApps) {
+    if (app.deleted) continue;
+    const rawState = app.params?.["global-state"];
+    if (!rawState) continue;
+    const state = decodeGlobalState(rawState);
+    if (activeOnly && !state.is_activated) continue;
+    if (activeOnly && state.is_resolved) continue;
+    if (activeOnly && state.resolution_time && state.resolution_time < Math.floor(Date.now() / 1e3)) continue;
+    const appId = Number(app.id);
+    flatMarkets.push({
+      id: String(appId),
+      title: state.title || "",
+      marketAppId: appId,
+      yesAssetId: state.yes_asset_id || 0,
+      noAssetId: state.no_asset_id || 0,
+      endTs: state.resolution_time || 0,
+      isResolved: !!state.is_resolved,
+      isLive: !!state.is_activated && !state.is_resolved,
+      feeBase: state.fee_base_percent,
+      source: "onchain"
+    });
+  }
+  return groupMultiChoiceMarkets(flatMarkets);
+};
+var getMarketOnChain = async (config, marketAppId) => {
+  try {
+    const appId = typeof marketAppId === "string" ? Number(marketAppId) : marketAppId;
+    const appInfo = await config.algodClient.getApplicationByID(appId).do();
+    const rawState = appInfo.params?.["global-state"] ?? appInfo["params"]?.["global-state"] ?? [];
+    const state = decodeGlobalState(rawState);
+    return {
+      id: String(appId),
+      title: state.title || "",
+      marketAppId: appId,
+      yesAssetId: state.yes_asset_id || 0,
+      noAssetId: state.no_asset_id || 0,
+      endTs: state.resolution_time || 0,
+      isResolved: !!state.is_resolved,
+      isLive: !!state.is_activated && !state.is_resolved,
+      feeBase: state.fee_base_percent,
+      source: "onchain"
+    };
+  } catch {
+    return null;
+  }
+};
+var getMarketsFromApi = async (config) => {
+  if (!config.apiKey) {
+    throw new Error("apiKey is required for API-based market fetching. Use getMarketsOnChain() instead, or pass an apiKey.");
+  }
   const baseUrl = config.apiBaseUrl ?? DEFAULT_API_BASE_URL;
   const allMarkets = [];
   let lastEvaluatedKey;
@@ -1972,10 +2086,10 @@ var getMarkets = async (config) => {
     }
     const data = await response.json();
     if (Array.isArray(data)) {
-      allMarkets.push(...data);
+      allMarkets.push(...data.map((m) => ({ ...m, source: "api" })));
       hasMore = false;
     } else if (data.markets) {
-      allMarkets.push(...data.markets);
+      allMarkets.push(...data.markets.map((m) => ({ ...m, source: "api" })));
       lastEvaluatedKey = data.lastEvaluatedKey;
       hasMore = !!lastEvaluatedKey;
     } else {
@@ -1984,7 +2098,10 @@ var getMarkets = async (config) => {
   }
   return allMarkets;
 };
-var getMarket = async (config, marketId) => {
+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.");
+  }
   const baseUrl = config.apiBaseUrl ?? DEFAULT_API_BASE_URL;
   const url = `${baseUrl}/get-market?marketId=${encodeURIComponent(marketId)}`;
   const response = await fetch(url, { headers: { "x-api-key": config.apiKey } });
@@ -1993,7 +2110,21 @@ var getMarket = async (config, marketId) => {
     throw new Error(`Alpha API error: ${response.status} ${response.statusText}`);
   }
   const data = await response.json();
-  return data.market ?? data ?? null;
+  const market = data.market ?? data ?? null;
+  if (market) market.source = "api";
+  return market;
+};
+var getMarkets = async (config) => {
+  if (config.apiKey) {
+    return getMarketsFromApi(config);
+  }
+  return getMarketsOnChain(config);
+};
+var getMarket = async (config, marketId) => {
+  if (config.apiKey) {
+    return getMarketFromApi(config, marketId);
+  }
+  return getMarketOnChain(config, marketId);
 };
 
 // src/client.ts
@@ -2006,7 +2137,6 @@ var AlphaClient = class {
     if (!config.activeAddress) throw new Error("activeAddress is required");
     if (!config.matcherAppId) throw new Error("matcherAppId is required");
     if (!config.usdcAssetId) throw new Error("usdcAssetId is required");
-    if (!config.apiKey) throw new Error("apiKey is required");
     this.config = {
       ...config,
       apiBaseUrl: config.apiBaseUrl ?? "https://partners.alphaarcade.com/api"
@@ -2145,9 +2275,10 @@ var AlphaClient = class {
   // Markets
   // ============================================
   /**
-   * Fetches all live, tradeable markets from the Alpha API.
+   * Fetches all live, tradeable markets.
    *
-   * Automatically paginates to retrieve all markets.
+   * If an API key is configured, uses the Alpha REST API (richer data: images, categories, volume).
+   * Otherwise, discovers markets on-chain from the market creator address (no API key needed).
    *
    * @returns Array of live markets
    */
@@ -2157,21 +2288,69 @@ var AlphaClient = class {
   /**
    * Fetches a single market by its ID.
    *
-   * @param marketId - The market ID
+   * If an API key is configured, uses the Alpha REST API.
+   * Otherwise, reads the market's on-chain global state (pass the market app ID as a string).
+   *
+   * @param marketId - The market ID (UUID for API, app ID string for on-chain)
    * @returns The market data, or null if not found
    */
   async getMarket(marketId) {
     return getMarket(this.config, marketId);
   }
+  /**
+   * Fetches all live markets directly from the blockchain (no API key needed).
+   *
+   * Discovers markets by looking up all apps created by the market creator address.
+   * Returns core data: title, asset IDs, resolution time, fees.
+   * Does NOT include images, categories, volume, or probabilities.
+   *
+   * @returns Array of live markets from on-chain data
+   */
+  async getMarketsOnChain() {
+    return getMarketsOnChain(this.config);
+  }
+  /**
+   * Fetches a single market by app ID directly from the blockchain (no API key needed).
+   *
+   * @param marketAppId - The market app ID
+   * @returns The market data, or null if not found
+   */
+  async getMarketOnChain(marketAppId) {
+    return getMarketOnChain(this.config, marketAppId);
+  }
+  /**
+   * Fetches all live markets from the Alpha REST API (requires API key).
+   *
+   * Returns richer data than on-chain: images, categories, volume, probabilities.
+   *
+   * @returns Array of live markets from the API
+   */
+  async getMarketsFromApi() {
+    return getMarketsFromApi(this.config);
+  }
+  /**
+   * Fetches a single market by ID from the Alpha REST API (requires API key).
+   *
+   * @param marketId - The market UUID
+   * @returns The market data, or null if not found
+   */
+  async getMarketFromApi(marketId) {
+    return getMarketFromApi(this.config, marketId);
+  }
 };
 
 exports.AlphaClient = AlphaClient;
+exports.DEFAULT_MARKET_CREATOR_ADDRESS = DEFAULT_MARKET_CREATOR_ADDRESS;
 exports.calculateFee = calculateFee;
 exports.calculateFeeFromTotal = calculateFeeFromTotal;
 exports.calculateMatchingOrders = calculateMatchingOrders;
 exports.checkAssetOptIn = checkAssetOptIn;
 exports.decodeGlobalState = decodeGlobalState;
 exports.getEscrowGlobalState = getEscrowGlobalState;
+exports.getMarketFromApi = getMarketFromApi;
 exports.getMarketGlobalState = getMarketGlobalState;
+exports.getMarketOnChain = getMarketOnChain;
+exports.getMarketsFromApi = getMarketsFromApi;
+exports.getMarketsOnChain = getMarketsOnChain;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map