Skip to main content

Overview

The AlphaClient is the main entry point for interacting with Alpha Market prediction markets on Algorand. It provides a comprehensive set of methods organized into four categories:
  • Trading: Create, modify, and cancel orders
  • Positions: Manage outcome token positions and claims
  • Orderbook: Read on-chain orderbook data
  • Markets: Fetch market information

Constructor

import { AlphaClient } from '@alpha-arcade/sdk';
import algosdk from 'algosdk';

const algodClient = new algosdk.Algodv2('', 'https://mainnet-api.algonode.cloud', 443);
const indexerClient = new algosdk.Indexer('', 'https://mainnet-idx.algonode.cloud', 443);
const account = algosdk.mnemonicToSecretKey('your mnemonic ...');
const signer = algosdk.makeBasicAccountTransactionSigner(account);

const client = new AlphaClient({
  algodClient,
  indexerClient,
  signer,
  activeAddress: account.addr.toString(),
  matcherAppId: 3078581851,
  usdcAssetId: 31566704,
});
config
AlphaClientConfig
required
Configuration object for initializing the client. See Configuration for details.

Trading Methods

Methods for creating, modifying, and canceling orders on prediction markets.

createLimitOrder

Creates a limit order on a market. A limit order sits on the orderbook at your specified price until matched or cancelled. Slippage is 0 — the order executes only at your exact price.
const result = await client.createLimitOrder({
  marketAppId: 123456789,
  position: 1, // 1 = Yes, 0 = No
  price: 500_000, // $0.50 in microunits
  quantity: 1_000_000, // 1 share in microunits
  isBuying: true,
});

console.log('Escrow App ID:', result.escrowAppId);
console.log('Transaction IDs:', result.txIds);
params
CreateLimitOrderParams
required
Order parameters
marketAppId
number
required
The market application ID on Algorand
position
0 | 1
required
Position to trade: 1 for Yes, 0 for No
price
number
required
Price in microunits (e.g., 500000 = $0.50)
quantity
number
required
Quantity in microunits (e.g., 1000000 = 1 share)
isBuying
boolean
required
Whether this is a buy order (true) or sell order (false)
feeBase
number
Fee base in microunits (e.g., 70000 = 7%). If omitted, reads from market global state.
CreateOrderResult
object
escrowAppId
number
The escrow app ID of the newly created order
txIds
string[]
Transaction IDs from the atomic group
confirmedRound
number
Confirmed round number

createMarketOrder

Creates a market order with automatic matching. Fetches the live orderbook, finds the best counterparty orders within your slippage tolerance, then creates the order and proposes matches in a single atomic transaction group.
const result = await client.createMarketOrder({
  marketAppId: 123456789,
  position: 1,
  price: 500_000,
  quantity: 5_000_000, // 5 shares
  isBuying: true,
  slippage: 50_000, // $0.05 slippage tolerance
});

console.log('Matched quantity:', result.matchedQuantity);
console.log('Matched price:', result.matchedPrice);
params
CreateMarketOrderParams
required
Order parameters
marketAppId
number
required
The market application ID
position
0 | 1
required
Position to trade: 1 for Yes, 0 for No
price
number
required
Price in microunits (e.g., 500000 = $0.50)
quantity
number
required
Quantity in microunits
isBuying
boolean
required
Whether this is a buy order
slippage
number
required
Slippage tolerance in microunits (e.g., 50000 = $0.05)
feeBase
number
Fee base in microunits. If omitted, reads from market global state.
matchingOrders
CounterpartyMatch[]
Pre-computed matching orders. If omitted, auto-fetches orderbook and computes matches.
CreateOrderResult
object
escrowAppId
number
The escrow app ID of the newly created order
txIds
string[]
Transaction IDs from the atomic group
confirmedRound
number
Confirmed round number
matchedQuantity
number
Total quantity that was matched
matchedPrice
number
Weighted average fill price in microunits (accounts for complementary matching)

cancelOrder

Cancels an open order by deleting its escrow app. Returns the escrowed funds (USDC or outcome tokens) to the order owner, and reclaims the ALGO minimum balance used by the escrow app.
const result = await client.cancelOrder({
  marketAppId: 123456789,
  escrowAppId: 987654321,
  orderOwner: 'WALLETADDRESS...'
});

console.log('Cancelled:', result.success);
params
CancelOrderParams
required
Cancel parameters
marketAppId
number
required
The market application ID
escrowAppId
number
required
The escrow app ID of the order to cancel
orderOwner
string
required
The owner address of the order
CancelOrderResult
object
success
boolean
Whether the cancellation succeeded
txIds
string[]
Transaction IDs
confirmedRound
number
Confirmed round number

proposeMatch

Proposes a match between an existing maker order and a new taker order. Use this for advanced matching scenarios where you want to explicitly specify which orders to match against.
const result = await client.proposeMatch({
  marketAppId: 123456789,
  makerEscrowAppId: 987654321,
  makerAddress: 'MAKERADDRESS...',
  quantityMatched: 1_000_000, // 1 share
});
params
ProposeMatchParams
required
Match parameters
marketAppId
number
required
The market application ID
makerEscrowAppId
number
required
The maker escrow app ID (existing order)
makerAddress
string
required
The maker’s Algorand address
quantityMatched
number
required
Quantity to match in microunits
ProposeMatchResult
object
success
boolean
Whether the match succeeded
txIds
string[]
Transaction IDs
confirmedRound
number
Confirmed round number

amendOrder

Amends (edits) an existing unfilled order in-place. Cheaper and faster than cancel + recreate. The escrow contract adjusts collateral automatically — sends you a refund if the new value is lower, or requires extra funds if higher. Note: Only works on orders with zero quantity filled.
const result = await client.amendOrder({
  marketAppId: 123456789,
  escrowAppId: 987654321,
  price: 600_000, // New price: $0.60
  quantity: 2_000_000, // New quantity: 2 shares
});
params
AmendOrderParams
required
Amend parameters
marketAppId
number
required
The market application ID
escrowAppId
number
required
The escrow app ID of the order to amend
price
number
required
New price in microunits (e.g., 500000 = $0.50)
quantity
number
required
New quantity in microunits
slippage
number
New slippage in microunits (default 0)
AmendOrderResult
object
success
boolean
Whether the amendment succeeded
txIds
string[]
Transaction IDs
confirmedRound
number
Confirmed round number

Position Methods

Methods for managing outcome token positions and claiming resolved markets.

splitShares

Splits USDC into equal amounts of YES and NO outcome tokens. For example, splitting 1 USDC gives you 1 YES token + 1 NO token. Together they’re always worth $1.00 — you can trade them independently.
const result = await client.splitShares({
  marketAppId: 123456789,
  amount: 10_000_000, // Split $10.00 USDC
});
params
SplitSharesParams
required
Split parameters
marketAppId
number
required
The market application ID
amount
number
required
Amount to split in microunits (e.g., 1000000 = $1.00 USDC)
SplitMergeResult
object
success
boolean
Whether the operation succeeded
txIds
string[]
Transaction IDs
confirmedRound
number
Confirmed round number

mergeShares

Merges equal amounts of YES and NO tokens back into USDC. The inverse of split. 1 YES + 1 NO = 1 USDC, always.
const result = await client.mergeShares({
  marketAppId: 123456789,
  amount: 5_000_000, // Merge 5 YES + 5 NO → $5.00 USDC
});
params
MergeSharesParams
required
Merge parameters
marketAppId
number
required
The market application ID
amount
number
required
Amount to merge in microunits
SplitMergeResult
object
success
boolean
Whether the operation succeeded
txIds
string[]
Transaction IDs
confirmedRound
number
Confirmed round number

claim

Claims USDC from a resolved market by redeeming outcome tokens:
  • Winning tokens: redeemed 1:1 for USDC
  • Voided market: redeemed at half value
  • Losing tokens: burned (no USDC returned)
const result = await client.claim({
  marketAppId: 123456789,
  assetId: 456789123, // YES or NO token ASA ID
  amount: 10_000_000, // Optional: claim 10 tokens (defaults to entire balance)
});

console.log('Claimed:', result.amountClaimed);
params
ClaimParams
required
Claim parameters
marketAppId
number
required
The market application ID
assetId
number
required
The outcome token ASA ID to redeem
amount
number
Amount to claim in microunits. If omitted, claims entire balance.
ClaimResult
object
success
boolean
Whether the claim succeeded
txIds
string[]
Transaction IDs
confirmedRound
number
Confirmed round number
amountClaimed
number
Amount of tokens claimed in microunits

getPositions

Gets all token positions for a wallet across all markets. Reads on-chain account info and maps ASA holdings to markets. Returns raw token balances (YES/NO amounts per market).
// Get positions for active wallet
const positions = await client.getPositions();

// Get positions for specific wallet
const positions = await client.getPositions('WALLETADDRESS...');

positions.forEach(pos => {
  console.log(`${pos.title}: ${pos.yesBalance} YES, ${pos.noBalance} NO`);
});
walletAddress
string
Optional wallet address. Defaults to the client’s activeAddress if not provided.
WalletPosition[]
array
Array of positions with market app IDs and token balances
marketAppId
number
Market application ID
title
string
Market title (fetched from on-chain global state)
yesAssetId
number
YES token ASA ID
noAssetId
number
NO token ASA ID
yesBalance
number
YES token balance in microunits
noBalance
number
NO token balance in microunits

Orderbook Methods

Methods for reading on-chain orderbook data.

getOrderbook

Fetches the full on-chain orderbook for a market. Reads all escrow apps created by the market contract, decodes their global state, and organizes into yes/no bids and asks. Only includes limit orders (slippage = 0) with unfilled quantity.
const orderbook = await client.getOrderbook(123456789);

console.log('YES bids:', orderbook.yes.bids);
console.log('YES asks:', orderbook.yes.asks);
console.log('NO bids:', orderbook.no.bids);
console.log('NO asks:', orderbook.no.asks);
marketAppId
number
required
The market application ID
Orderbook
object
yes
OrderbookSide
YES side of the orderbook
bids
OrderbookEntry[]
Buy orders for YES tokens
asks
OrderbookEntry[]
Sell orders for YES tokens
no
OrderbookSide
NO side of the orderbook
bids
OrderbookEntry[]
Buy orders for NO tokens
asks
OrderbookEntry[]
Sell orders for NO tokens

getOpenOrders

Gets open orders for a specific wallet on a market.
const orders = await client.getOpenOrders(123456789);
// Or for a specific wallet:
const orders = await client.getOpenOrders(123456789, 'WALLETADDRESS...');

orders.forEach(order => {
  console.log(`Order ${order.escrowAppId}: ${order.quantity} @ ${order.price}`);
});
marketAppId
number
required
The market application ID
walletAddress
string
Optional wallet address. Defaults to the client’s activeAddress if not provided.
OpenOrder[]
array
Array of open orders
escrowAppId
number
Escrow app ID
marketAppId
number
Market app ID
position
0 | 1
Position: 0=No, 1=Yes
side
number
Side: 0=Sell, 1=Buy
price
number
Price in microunits
quantity
number
Total quantity in microunits
quantityFilled
number
Filled quantity in microunits
slippage
number
Slippage in microunits (0 = limit order)
owner
string
Owner address

getWalletOrdersFromApi

Gets all open orders for a wallet across every live market using the Alpha REST API.
const allOrders = await client.getWalletOrdersFromApi('WALLETADDRESS...');
walletAddress
string
required
The wallet address
OpenOrder[]
array
Array of open orders for the wallet across all markets

Market Methods

Methods for fetching market information from the Alpha API or directly from the blockchain.

getLiveMarkets

Fetches all live, tradeable 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)
const markets = await client.getLiveMarkets();

markets.forEach(market => {
  console.log(`${market.title}: ${market.yesProb}% YES`);
});
Market[]
array
Array of live markets
id
string
Market ID (app ID as string for on-chain, UUID for API)
title
string
Market title
marketAppId
number
Market application ID on Algorand
yesAssetId
number
YES token ASA ID
noAssetId
number
NO token ASA ID
yesProb
number
YES probability (API only)
noProb
number
NO probability (API only)
volume
number
Trading volume (API only)
endTs
number
End/resolution timestamp in seconds
image
string
Market image URL (API only)
categories
string[]
Market categories (API only)

getMarket

Fetches a single market by its 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)
// Using API (UUID)
const market = await client.getMarket('uuid-here');

// Using on-chain (app ID as string)
const market = await client.getMarket('123456789');
marketId
string
required
The market ID (UUID for API, app ID string for on-chain)
Market | null
object
The market data, or null if not found

getMarketsOnChain

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.
const markets = await client.getMarketsOnChain();
Market[]
array
Array of live markets from on-chain data

getMarketOnChain

Fetches a single market by app ID directly from the blockchain (no API key needed).
const market = await client.getMarketOnChain(123456789);
marketAppId
number
required
The market application ID
Market | null
object
The market data, or null if not found

getLiveMarketsFromApi

Fetches all live markets from the Alpha REST API (requires API key). Returns richer data than on-chain: images, categories, volume, probabilities.
const markets = await client.getLiveMarketsFromApi();
Market[]
array
Array of live markets from the API

getRewardMarkets

Fetches the reward markets from the Alpha REST API (requires API key).
const rewardMarkets = await client.getRewardMarkets();
Market[]
array
Array of reward markets

getMarketFromApi

Fetches a single market by ID from the Alpha REST API (requires API key).
const market = await client.getMarketFromApi('market-uuid');
marketId
string
required
The market UUID
Market | null
object
The market data, or null if not found

Build docs developers (and LLMs) love