Skip to main content

​
Overview

The Alpha SDK provides multiple methods to discover and fetch prediction markets:
  • getLiveMarkets() - Smart default that uses API if key is configured, otherwise on-chain
  • getMarket(marketId) - Fetch a single market by ID (API or on-chain)
  • getMarketsOnChain() - Direct on-chain discovery (no API key needed)
  • getMarketOnChain(marketAppId) - Fetch single market from blockchain
See On-Chain vs API Comparison for guidance on which method to use.

​
getLiveMarkets

Fetches all live, tradeable markets using the best available data source. Behavior:
  • If apiKey is configured → uses Alpha REST API (richer data)
  • If no apiKey → falls back to on-chain discovery
const markets = await client.getLiveMarkets();

console.log(`Found ${markets.length} live markets`);
markets.forEach(m => {
  console.log(`${m.title} - App ID: ${m.marketAppId}`);
});

​
Returns

​
markets
Market[]
Array of live prediction markets

​
getMarket

Fetches a single market by its ID. Behavior:
  • If apiKey is configured → fetches from Alpha REST API using UUID
  • If no apiKey → reads from blockchain using app ID
// With API key (use UUID)
const market = await client.getMarket('abc123-def456-...');

// Without API key (use app ID as string)
const market = await client.getMarket('1234567890');

if (market) {
  console.log(`Market: ${market.title}`);
  console.log(`Ends: ${new Date(market.endTs * 1000).toISOString()}`);
}

​
Parameters

​
marketId
string
required
Market identifier:
  • With API key: Use the market UUID (e.g. 'abc123-def456-...')
  • Without API key: Use the market app ID as a string (e.g. '1234567890')

​
Returns

​
market
Market | null
The market data, or null if not found. See Market type above for field details.

​
getMarketsOnChain

Fetches all live markets directly from the Algorand blockchain. No API key required. Discovers markets by querying all applications created by the market creator address, then reads their global state. Includes:
  • Market title
  • App ID and token ASAs
  • Resolution time
  • Fee structure
  • Resolved status
Does NOT include:
  • Images
  • Categories
  • Volume
  • Probabilities
// No API key needed - reads directly from blockchain
const markets = await client.getMarketsOnChain();

markets.forEach(m => {
  console.log(`${m.title}`);
  console.log(`  App ID: ${m.marketAppId}`);
  console.log(`  YES ASA: ${m.yesAssetId}`);
  console.log(`  NO ASA: ${m.noAssetId}`);
  console.log(`  Ends: ${new Date(m.endTs * 1000).toISOString()}`);
});

​
Returns

​
markets
Market[]
Array of markets with on-chain data only. See Market type above for field details.Note: Fields like yesProb, noProb, volume, image, and categories will be undefined.

​
getMarketOnChain

Fetches a single market by its app ID directly from the blockchain. No API key required. 
const market = await client.getMarketOnChain(1234567890);

if (market) {
  console.log(`Market: ${market.title}`);
  console.log(`YES ASA: ${market.yesAssetId}`);
  console.log(`NO ASA: ${market.noAssetId}`);
}

​
Parameters

​
marketAppId
number
required
The Algorand application ID of the market contract

​
Returns

​
market
Market | null
The market data from blockchain, or null if not found. See Market type above for field details.Note: Only on-chain fields are populated. API-only fields like image, volume, etc. will be undefined.

​
Multi-Choice Markets

Multi-choice markets are automatically grouped by the SDK. Options use the title format "Parent Title : Option Name". 
const markets = await client.getLiveMarkets();

// Find a multi-choice market
const multiChoice = markets.find(m => m.options && m.options.length > 0);

if (multiChoice) {
  console.log(`Market: ${multiChoice.title}`);
  console.log('Options:');
  multiChoice.options?.forEach(opt => {
    console.log(`  - ${opt.title} (${opt.yesProb}% YES)`);
  });
}
Each option has its own:
  • marketAppId - Separate market contract
  • yesAssetId / noAssetId - Separate outcome tokens
  • yesProb / noProb - Independent probabilities

​
When to Use Each Method

Best for: General use
const markets = await client.getLiveMarkets();
  • Automatically uses best available data source
  • Falls back gracefully if no API key
  • Recommended for most applications

Build docs developers (and LLMs) love

Get started for freeTalk to us