@alpha-arcade/sdk 0.1.2 → 0.2.1

package/dist/index.d.cts

@@ -10,17 +10,20 @@ type AlphaClientConfig = {
     signer: TransactionSigner;
     /** The active Algorand address that will sign transactions */
     activeAddress: string;
-    /** Matcher contract app ID (mainnet: 741347297) */
+    /** Matcher contract app ID (mainnet: 3078581851) */
     matcherAppId: number;
     /** USDC ASA ID on Algorand (mainnet: 31566704) */
     usdcAssetId: number;
     /** Base URL for the Alpha REST API (default: https://partners.alphaarcade.com/api) */
     apiBaseUrl?: string;
-    /** API key for the Alpha partners API (passed as x-api-key header) */
-    apiKey: string;
+    /** API key for the Alpha partners API. Optional -- if not provided, markets are loaded on-chain. */
+    apiKey?: string;
+    /** Market creator address for on-chain market discovery. Defaults to the Alpha Arcade mainnet creator. */
+    marketCreatorAddress?: string;
 };
-/** A prediction market returned from the Alpha API */
+/** A prediction market (from the Alpha API or on-chain discovery) */
 type Market = {
+    /** Market ID (app ID as string for on-chain, UUID for API) */
     id: string;
     title: string;
     slug?: string;
@@ -28,9 +31,13 @@ type Market = {
     marketAppId: number;
     yesAssetId: number;
     noAssetId: number;
-    yesProb: number;
-    noProb: number;
-    volume: number;
+    /** YES probability (API only -- not available from on-chain lookup) */
+    yesProb?: number;
+    /** NO probability (API only -- not available from on-chain lookup) */
+    noProb?: number;
+    /** Trading volume (API only -- not available from on-chain lookup) */
+    volume?: number;
+    /** End/resolution timestamp in seconds */
     endTs: number;
     resolution?: number;
     isResolved?: boolean;
@@ -39,6 +46,8 @@ type Market = {
     featured?: boolean;
     options?: MarketOption[];
     feeBase?: number;
+    /** Data source: 'onchain' or 'api' */
+    source?: 'onchain' | 'api';
     [key: string]: unknown;
 };
 /** An option within a multi-choice market */
@@ -316,7 +325,6 @@ type EscrowGlobalState = {
  *   activeAddress: account.addr,
  *   matcherAppId: 3078581851,
  *   usdcAssetId: 31566704,
- *   apiKey: 'YOUR_API_KEY',
  * });
  *
  * // Fetch markets
@@ -436,9 +444,10 @@ declare class AlphaClient {
      */
     getOpenOrders(marketAppId: number, walletAddress?: string): Promise<OpenOrder[]>;
     /**
-     * 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
      */
@@ -446,12 +455,90 @@ declare class AlphaClient {
     /**
      * 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
      */
     getMarket(marketId: string): Promise<Market | null>;
+    /**
+     * 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
+     */
+    getMarketsOnChain(): Promise<Market[]>;
+    /**
+     * 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
+     */
+    getMarketOnChain(marketAppId: number): Promise<Market | null>;
+    /**
+     * 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
+     */
+    getMarketsFromApi(): Promise<Market[]>;
+    /**
+     * 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
+     */
+    getMarketFromApi(marketId: string): Promise<Market | null>;
 }
 
+/** The default Alpha Arcade mainnet market creator address */
+declare const DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
+/**
+ * Fetches all live, tradeable markets directly from the Algorand blockchain.
+ *
+ * Discovers markets by looking up all applications created by the market creator
+ * address, then reading their global state. No API key required.
+ *
+ * @param config - Alpha client config
+ * @param options - Optional filters
+ * @returns Array of live markets
+ */
+declare const getMarketsOnChain: (config: AlphaClientConfig, options?: {
+    activeOnly?: boolean;
+}) => Promise<Market[]>;
+/**
+ * Fetches a single market by its app ID directly from the Algorand blockchain.
+ *
+ * @param config - Alpha client config
+ * @param marketAppId - The market app ID (number or string)
+ * @returns The market data, or null if not found
+ */
+declare const getMarketOnChain: (config: AlphaClientConfig, marketAppId: number | string) => Promise<Market | null>;
+/**
+ * Fetches all live, tradeable markets from the Alpha REST API.
+ *
+ * Paginates automatically through all results. Requires an API key.
+ * Returns richer data than on-chain lookup (images, categories, volume, probabilities).
+ *
+ * @param config - Alpha client config
+ * @returns Array of live markets
+ */
+declare const getMarketsFromApi: (config: AlphaClientConfig) => Promise<Market[]>;
+/**
+ * Fetches a single market by its ID from the Alpha REST API.
+ * Requires an API key.
+ *
+ * @param config - Alpha client config
+ * @param marketId - The market ID
+ * @returns The market data, or null if not found
+ */
+declare const getMarketFromApi: (config: AlphaClientConfig, marketId: string) => Promise<Market | null>;
+
 /**
  * Calculates the required fee amount in microunits.
  *
@@ -530,4 +617,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 CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateMarketOrderResult, type CreateOrderResult, 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, getMarketGlobalState };
+export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateMarketOrderResult, type CreateOrderResult, 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, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsFromApi, getMarketsOnChain };

package/dist/index.d.ts

@@ -10,17 +10,20 @@ type AlphaClientConfig = {
     signer: TransactionSigner;
     /** The active Algorand address that will sign transactions */
     activeAddress: string;
-    /** Matcher contract app ID (mainnet: 741347297) */
+    /** Matcher contract app ID (mainnet: 3078581851) */
     matcherAppId: number;
     /** USDC ASA ID on Algorand (mainnet: 31566704) */
     usdcAssetId: number;
     /** Base URL for the Alpha REST API (default: https://partners.alphaarcade.com/api) */
     apiBaseUrl?: string;
-    /** API key for the Alpha partners API (passed as x-api-key header) */
-    apiKey: string;
+    /** API key for the Alpha partners API. Optional -- if not provided, markets are loaded on-chain. */
+    apiKey?: string;
+    /** Market creator address for on-chain market discovery. Defaults to the Alpha Arcade mainnet creator. */
+    marketCreatorAddress?: string;
 };
-/** A prediction market returned from the Alpha API */
+/** A prediction market (from the Alpha API or on-chain discovery) */
 type Market = {
+    /** Market ID (app ID as string for on-chain, UUID for API) */
     id: string;
     title: string;
     slug?: string;
@@ -28,9 +31,13 @@ type Market = {
     marketAppId: number;
     yesAssetId: number;
     noAssetId: number;
-    yesProb: number;
-    noProb: number;
-    volume: number;
+    /** YES probability (API only -- not available from on-chain lookup) */
+    yesProb?: number;
+    /** NO probability (API only -- not available from on-chain lookup) */
+    noProb?: number;
+    /** Trading volume (API only -- not available from on-chain lookup) */
+    volume?: number;
+    /** End/resolution timestamp in seconds */
     endTs: number;
     resolution?: number;
     isResolved?: boolean;
@@ -39,6 +46,8 @@ type Market = {
     featured?: boolean;
     options?: MarketOption[];
     feeBase?: number;
+    /** Data source: 'onchain' or 'api' */
+    source?: 'onchain' | 'api';
     [key: string]: unknown;
 };
 /** An option within a multi-choice market */
@@ -316,7 +325,6 @@ type EscrowGlobalState = {
  *   activeAddress: account.addr,
  *   matcherAppId: 3078581851,
  *   usdcAssetId: 31566704,
- *   apiKey: 'YOUR_API_KEY',
  * });
  *
  * // Fetch markets
@@ -436,9 +444,10 @@ declare class AlphaClient {
      */
     getOpenOrders(marketAppId: number, walletAddress?: string): Promise<OpenOrder[]>;
     /**
-     * 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
      */
@@ -446,12 +455,90 @@ declare class AlphaClient {
     /**
      * 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
      */
     getMarket(marketId: string): Promise<Market | null>;
+    /**
+     * 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
+     */
+    getMarketsOnChain(): Promise<Market[]>;
+    /**
+     * 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
+     */
+    getMarketOnChain(marketAppId: number): Promise<Market | null>;
+    /**
+     * 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
+     */
+    getMarketsFromApi(): Promise<Market[]>;
+    /**
+     * 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
+     */
+    getMarketFromApi(marketId: string): Promise<Market | null>;
 }
 
+/** The default Alpha Arcade mainnet market creator address */
+declare const DEFAULT_MARKET_CREATOR_ADDRESS = "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY";
+/**
+ * Fetches all live, tradeable markets directly from the Algorand blockchain.
+ *
+ * Discovers markets by looking up all applications created by the market creator
+ * address, then reading their global state. No API key required.
+ *
+ * @param config - Alpha client config
+ * @param options - Optional filters
+ * @returns Array of live markets
+ */
+declare const getMarketsOnChain: (config: AlphaClientConfig, options?: {
+    activeOnly?: boolean;
+}) => Promise<Market[]>;
+/**
+ * Fetches a single market by its app ID directly from the Algorand blockchain.
+ *
+ * @param config - Alpha client config
+ * @param marketAppId - The market app ID (number or string)
+ * @returns The market data, or null if not found
+ */
+declare const getMarketOnChain: (config: AlphaClientConfig, marketAppId: number | string) => Promise<Market | null>;
+/**
+ * Fetches all live, tradeable markets from the Alpha REST API.
+ *
+ * Paginates automatically through all results. Requires an API key.
+ * Returns richer data than on-chain lookup (images, categories, volume, probabilities).
+ *
+ * @param config - Alpha client config
+ * @returns Array of live markets
+ */
+declare const getMarketsFromApi: (config: AlphaClientConfig) => Promise<Market[]>;
+/**
+ * Fetches a single market by its ID from the Alpha REST API.
+ * Requires an API key.
+ *
+ * @param config - Alpha client config
+ * @param marketId - The market ID
+ * @returns The market data, or null if not found
+ */
+declare const getMarketFromApi: (config: AlphaClientConfig, marketId: string) => Promise<Market | null>;
+
 /**
  * Calculates the required fee amount in microunits.
  *
@@ -530,4 +617,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 CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateMarketOrderResult, type CreateOrderResult, 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, getMarketGlobalState };
+export { type AggregatedOrderbook, type AggregatedOrderbookEntry, type AggregatedOrderbookSide, AlphaClient, type AlphaClientConfig, type CancelOrderParams, type CancelOrderResult, type ClaimParams, type ClaimResult, type CounterpartyMatch, type CreateLimitOrderParams, type CreateMarketOrderParams, type CreateMarketOrderResult, type CreateOrderResult, 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, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsFromApi, getMarketsOnChain };

package/dist/index.js

@@ -1886,40 +1886,43 @@ var getPositions = async (config, walletAddress) => {
     const amount = Number(asset.amount);
     try {
       const assetInfo = await indexerClient.lookupAssetByID(assetId).do();
-      const creator = assetInfo.asset?.params?.creator;
-      if (!creator) continue;
-      const createdApps = await indexerClient.lookupAccountCreatedApplications(creator).limit(1).do();
-      if (!createdApps.applications?.length) continue;
-      const appId = createdApps.applications[0].id;
-      try {
-        const appInfo = await indexerClient.lookupApplications(appId).do();
-        const rawState = appInfo.application?.params?.["global-state"];
-        if (!rawState) continue;
-        let yesAssetIdOnChain = 0;
-        let noAssetIdOnChain = 0;
-        for (const item of rawState) {
-          const key = Buffer.from(item.key, "base64").toString();
-          if (key === "yes_asset_id") yesAssetIdOnChain = Number(item.value.uint);
-          if (key === "no_asset_id") noAssetIdOnChain = Number(item.value.uint);
-        }
-        if (yesAssetIdOnChain === 0 && noAssetIdOnChain === 0) continue;
-        const existing = positions.get(appId) ?? {
-          marketAppId: appId,
-          yesAssetId: yesAssetIdOnChain,
-          noAssetId: noAssetIdOnChain,
-          yesBalance: 0,
-          noBalance: 0
-        };
-        if (assetId === yesAssetIdOnChain) {
+      const assetName = assetInfo.asset?.params?.name ?? "";
+      const unitName = assetInfo.asset?.params?.["unit-name"] ?? "";
+      if (!unitName.startsWith("ALPHA-")) continue;
+      const match = assetName.match(/^Alpha Market (\d+) (Yes|No)$/);
+      if (!match) continue;
+      const marketAppId = Number(match[1]);
+      const side = match[2];
+      const existing = positions.get(marketAppId);
+      if (existing) {
+        if (side === "Yes") {
           existing.yesBalance = amount;
-        } else if (assetId === noAssetIdOnChain) {
-          existing.noBalance = amount;
         } else {
+          existing.noBalance = amount;
+        }
+      } else {
+        try {
+          const appInfo = await indexerClient.lookupApplications(marketAppId).do();
+          const rawState = appInfo.application?.params?.["global-state"];
+          if (!rawState) continue;
+          let yesAssetIdOnChain = 0;
+          let noAssetIdOnChain = 0;
+          for (const item of rawState) {
+            const key = Buffer.from(item.key, "base64").toString();
+            if (key === "yes_asset_id") yesAssetIdOnChain = Number(item.value.uint);
+            if (key === "no_asset_id") noAssetIdOnChain = Number(item.value.uint);
+          }
+          if (yesAssetIdOnChain === 0 && noAssetIdOnChain === 0) continue;
+          positions.set(marketAppId, {
+            marketAppId,
+            yesAssetId: yesAssetIdOnChain,
+            noAssetId: noAssetIdOnChain,
+            yesBalance: side === "Yes" ? amount : 0,
+            noBalance: side === "No" ? amount : 0
+          });
+        } catch {
           continue;
         }
-        positions.set(appId, existing);
-      } catch {
-        continue;
       }
     } catch {
       continue;
@@ -1930,7 +1933,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;
@@ -1947,10 +2064,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 {
@@ -1959,7 +2076,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 } });
@@ -1968,7 +2088,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
@@ -1981,7 +2115,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"
@@ -2120,9 +2253,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
    */
@@ -2132,14 +2266,57 @@ 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);
+  }
 };
 
-export { AlphaClient, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getMarketGlobalState };
+export { AlphaClient, DEFAULT_MARKET_CREATOR_ADDRESS, calculateFee, calculateFeeFromTotal, calculateMatchingOrders, checkAssetOptIn, decodeGlobalState, getEscrowGlobalState, getMarketFromApi, getMarketGlobalState, getMarketOnChain, getMarketsFromApi, getMarketsOnChain };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map