Skip to main content

​
Overview

The AlphaClientConfig type defines all configuration options for initializing the AlphaClient. It includes required fields for Algorand connectivity and optional fields for API access and advanced features.

​
Type Definition

export type AlphaClientConfig = {
  algodClient: Algodv2;
  indexerClient: Indexer;
  signer: TransactionSigner;
  activeAddress: string;
  matcherAppId: number;
  usdcAssetId: number;
  apiBaseUrl?: string;
  apiKey?: string;
  marketCreatorAddress?: string;
};

​
Required Fields

These fields must be provided when creating a new AlphaClient instance.
​
algodClient
Algodv2
required
Algorand algod client instance for submitting transactions and reading blockchain state.
import algosdk from 'algosdk';

const algodClient = new algosdk.Algodv2(
  '',
  'https://mainnet-api.algonode.cloud',
  443
);
​
indexerClient
Indexer
required
Algorand indexer client instance for querying historical blockchain data and account information.
import algosdk from 'algosdk';

const indexerClient = new algosdk.Indexer(
  '',
  'https://mainnet-idx.algonode.cloud',
  443
);
​
signer
TransactionSigner
required
Transaction signer function that signs transactions. Can be a wallet signer or account signer.
import algosdk from 'algosdk';

// Option 1: Basic account signer
const account = algosdk.mnemonicToSecretKey('your mnemonic here');
const signer = algosdk.makeBasicAccountTransactionSigner(account);

// Option 2: Wallet signer (e.g., Pera, Defly)
// const signer = walletClient.signer;
​
activeAddress
string
required
The active Algorand address that will sign transactions. This is the user’s wallet address.
const activeAddress = account.addr.toString();
// Or from wallet: walletClient.activeAddress
​
matcherAppId
number
required
Matcher contract application ID. This is the smart contract that facilitates order matching on Alpha Markets.Network values:
  • Mainnet: 3078581851
  • Testnet: Contact Alpha team for testnet app ID
matcherAppId: 3078581851 // Mainnet
​
usdcAssetId
number
required
USDC ASA (Algorand Standard Asset) ID. This is the stablecoin used as collateral for trading.Network values:
  • Mainnet: 31566704 (USDC)
  • Testnet: Contact Alpha team for testnet USDC asset ID
usdcAssetId: 31566704 // Mainnet USDC

​
Optional Fields

These fields are optional and provide additional functionality.
​
apiBaseUrl
string
Base URL for the Alpha REST API. If not provided, defaults to https://partners.alphaarcade.com/api.You typically don’t need to set this unless:
  • Using a custom API endpoint
  • Testing against a staging environment
  • Using a self-hosted Alpha API instance
apiBaseUrl: 'https://partners.alphaarcade.com/api' // Default
​
apiKey
string
API key for the Alpha partners API. Optional — if not provided, markets are loaded directly from on-chain data.With API key:
  • Richer market data (images, categories, volume, probabilities)
  • Faster market discovery
  • Access to historical data and analytics
Without API key:
  • Markets discovered on-chain via market creator address
  • Core data only (title, asset IDs, resolution time, fees)
  • No images, categories, or volume data
apiKey: 'your-api-key-here'
To obtain an API key, contact the Alpha Arcade team.
​
marketCreatorAddress
string
Market creator address for on-chain market discovery. Used when loading markets without an API key.Defaults to the Alpha Arcade mainnet creator address if not provided.When to set this:
  • Testing on a different network
  • Using a custom market creator
  • Filtering markets by a specific creator
marketCreatorAddress: 'CREATOR_ADDRESS_HERE'

​
Configuration Examples

​
Mainnet Configuration

Standard configuration for mainnet with API access: 
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 here');
const signer = algosdk.makeBasicAccountTransactionSigner(account);

const client = new AlphaClient({
  algodClient,
  indexerClient,
  signer,
  activeAddress: account.addr.toString(),
  matcherAppId: 3078581851,
  usdcAssetId: 31566704,
  apiKey: 'your-api-key-here', // Optional
});

​
Mainnet Without API Key

Configuration for mainnet using on-chain market discovery: 
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 here');
const signer = algosdk.makeBasicAccountTransactionSigner(account);

const client = new AlphaClient({
  algodClient,
  indexerClient,
  signer,
  activeAddress: account.addr.toString(),
  matcherAppId: 3078581851,
  usdcAssetId: 31566704,
  // No apiKey - markets loaded on-chain
});

​
Testnet Configuration

Configuration for testnet development: 
import { AlphaClient } from '@alpha-arcade/sdk';
import algosdk from 'algosdk';

const algodClient = new algosdk.Algodv2(
  '',
  'https://testnet-api.algonode.cloud',
  443
);

const indexerClient = new algosdk.Indexer(
  '',
  'https://testnet-idx.algonode.cloud',
  443
);

const account = algosdk.mnemonicToSecretKey('your testnet mnemonic');
const signer = algosdk.makeBasicAccountTransactionSigner(account);

const client = new AlphaClient({
  algodClient,
  indexerClient,
  signer,
  activeAddress: account.addr.toString(),
  matcherAppId: 123456789, // Contact Alpha team for testnet app ID
  usdcAssetId: 987654321, // Contact Alpha team for testnet USDC ID
});

​
Wallet Integration

Configuration using a wallet provider (e.g., Pera, Defly): 
import { AlphaClient } from '@alpha-arcade/sdk';
import algosdk from 'algosdk';
import { PeraWalletConnect } from '@perawallet/connect';

const peraWallet = new PeraWalletConnect();

// Connect wallet
const accounts = await peraWallet.connect();
const activeAddress = accounts[0];

const algodClient = new algosdk.Algodv2(
  '',
  'https://mainnet-api.algonode.cloud',
  443
);

const indexerClient = new algosdk.Indexer(
  '',
  'https://mainnet-idx.algonode.cloud',
  443
);

// Create wallet signer
const signer = async (txnGroup: algosdk.Transaction[]) => {
  const signedTxns = await peraWallet.signTransaction([
    txnGroup.map(txn => ({ txn })),
  ]);
  return signedTxns;
};

const client = new AlphaClient({
  algodClient,
  indexerClient,
  signer,
  activeAddress,
  matcherAppId: 3078581851,
  usdcAssetId: 31566704,
  apiKey: 'your-api-key-here',
});

​
Network Reference

​
Mainnet

ParameterValue
Algod URLhttps://mainnet-api.algonode.cloud
Indexer URLhttps://mainnet-idx.algonode.cloud
Matcher App ID3078581851
USDC Asset ID31566704
API Base URLhttps://partners.alphaarcade.com/api

​
Testnet

ParameterValue
Algod URLhttps://testnet-api.algonode.cloud
Indexer URLhttps://testnet-idx.algonode.cloud
Matcher App IDContact Alpha team
USDC Asset IDContact Alpha team
API Base URLContact Alpha team

​
Validation

The AlphaClient constructor validates all required fields and throws an error if any are missing: 
// Missing required field
const client = new AlphaClient({
  algodClient,
  indexerClient,
  signer,
  activeAddress,
  // Missing matcherAppId - will throw error
  usdcAssetId: 31566704,
});

// Error: matcherAppId is required
Validation errors:
  • algodClient is required
  • indexerClient is required
  • signer is required
  • activeAddress is required
  • matcherAppId is required
  • usdcAssetId is required

​
Best Practices

​
Use Environment Variables

Store sensitive configuration in environment variables: 
const client = new AlphaClient({
  algodClient,
  indexerClient,
  signer,
  activeAddress,
  matcherAppId: parseInt(process.env.ALPHA_MATCHER_APP_ID!),
  usdcAssetId: parseInt(process.env.ALPHA_USDC_ASSET_ID!),
  apiKey: process.env.ALPHA_API_KEY, // Optional
});

​
Reuse Client Instances

Create one client instance and reuse it throughout your application: 
// client.ts
export const alphaClient = new AlphaClient({
  // ... config
});

// app.ts
import { alphaClient } from './client';

const markets = await alphaClient.getLiveMarkets();
const orderbook = await alphaClient.getOrderbook(marketAppId);

​
Handle Network Switching

If your app supports multiple networks, create separate client instances: 
const mainnetClient = new AlphaClient({
  algodClient: mainnetAlgod,
  indexerClient: mainnetIndexer,
  signer,
  activeAddress,
  matcherAppId: 3078581851,
  usdcAssetId: 31566704,
});

const testnetClient = new AlphaClient({
  algodClient: testnetAlgod,
  indexerClient: testnetIndexer,
  signer,
  activeAddress,
  matcherAppId: testnetMatcherAppId,
  usdcAssetId: testnetUsdcAssetId,
});

const client = isMainnet ? mainnetClient : testnetClient;

​
Exported Constants

The SDK exports default configuration constants that you can use:

​
DEFAULT_API_BASE_URL

The default API base URL for the Alpha platform: 
import { DEFAULT_API_BASE_URL } from '@alpha-arcade/sdk';

console.log(DEFAULT_API_BASE_URL); // "https://platform.alphaarcade.com/api"

// Use in client config
const client = new AlphaClient({
  // ... other config
  apiBaseUrl: DEFAULT_API_BASE_URL, // or omit to use this default
});

​
DEFAULT_MARKET_CREATOR_ADDRESS

The default market creator address used for on-chain market discovery on mainnet: 
import { DEFAULT_MARKET_CREATOR_ADDRESS } from '@alpha-arcade/sdk';

console.log(DEFAULT_MARKET_CREATOR_ADDRESS); 
// "5P5Y6HTWUNG2E3VXBQDZN3ENZD3JPAIR5PKT3LOYJAPAUKOLFD6KANYTRY"

// Use in client config for custom market creator filtering
const client = new AlphaClient({
  // ... other config
  marketCreatorAddress: DEFAULT_MARKET_CREATOR_ADDRESS, // or omit to use this default
});
These constants are automatically used as defaults if you don’t provide apiBaseUrl or marketCreatorAddress in your configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us