@alpha-arcade/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,535 @@
+import algosdk, { Algodv2, Indexer, TransactionSigner } from 'algosdk';
+
+/** Configuration for initializing the AlphaClient */
+type AlphaClientConfig = {
+    /** Algorand algod client instance */
+    algodClient: Algodv2;
+    /** Algorand indexer client instance */
+    indexerClient: Indexer;
+    /** Transaction signer (wallet or account signer) */
+    signer: TransactionSigner;
+    /** The active Algorand address that will sign transactions */
+    activeAddress: string;
+    /** Matcher contract app ID (mainnet: 741347297) */
+    matcherAppId: number;
+    /** USDC ASA ID on Algorand (mainnet: 31566704) */
+    usdcAssetId: number;
+    /** Platform fee collection address */
+    feeAddress: string;
+    /** 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;
+};
+/** A prediction market returned from the Alpha API */
+type Market = {
+    id: string;
+    title: string;
+    slug?: string;
+    image?: string;
+    marketAppId: number;
+    yesAssetId: number;
+    noAssetId: number;
+    yesProb: number;
+    noProb: number;
+    volume: number;
+    endTs: number;
+    resolution?: number;
+    isResolved?: boolean;
+    isLive?: boolean;
+    categories?: string[];
+    featured?: boolean;
+    options?: MarketOption[];
+    feeBase?: number;
+    [key: string]: unknown;
+};
+/** An option within a multi-choice market */
+type MarketOption = {
+    id: string;
+    title: string;
+    marketAppId: number;
+    yesAssetId: number;
+    noAssetId: number;
+    yesProb: number;
+    noProb: number;
+    [key: string]: unknown;
+};
+/** Global state of a market app read from on-chain */
+type MarketGlobalState = {
+    collateral_asset_id: number;
+    yes_asset_id: number;
+    no_asset_id: number;
+    yes_supply: number;
+    no_supply: number;
+    is_resolved: number;
+    is_activated: number;
+    outcome: number;
+    resolution_time: number;
+    fee_base_percent: number;
+    fee_timer_threshold: number;
+    title: string;
+    rules: string;
+    oracle_address: string;
+    fee_address: string;
+    market_friend_addr: string;
+    escrow_cancel_address: string;
+};
+/** Position: 1 = Yes, 0 = No */
+type Position = 0 | 1;
+/** Order side: 'BUY' or 'SELL' */
+type OrderSide = 'BUY' | 'SELL';
+/** Parameters for creating a limit order */
+type CreateLimitOrderParams = {
+    /** Market app ID */
+    marketAppId: number;
+    /** 1 for Yes, 0 for No */
+    position: Position;
+    /** Price in microunits (e.g. 500000 = $0.50) */
+    price: number;
+    /** Quantity in microunits (e.g. 1000000 = 1 share) */
+    quantity: number;
+    /** Whether this is a buy order */
+    isBuying: boolean;
+    /** Fee base in microunits (e.g. 70000 = 7%). If omitted, reads from market global state. */
+    feeBase?: number;
+};
+/** Parameters for creating a market order */
+type CreateMarketOrderParams = {
+    /** Market app ID */
+    marketAppId: number;
+    /** 1 for Yes, 0 for No */
+    position: Position;
+    /** Price in microunits (e.g. 500000 = $0.50) */
+    price: number;
+    /** Quantity in microunits (e.g. 1000000 = 1 share) */
+    quantity: number;
+    /** Whether this is a buy order */
+    isBuying: boolean;
+    /** Slippage tolerance in microunits (e.g. 50000 = $0.05) */
+    slippage: number;
+    /** Fee base in microunits. If omitted, reads from market global state. */
+    feeBase?: number;
+    /** Pre-computed matching orders. If omitted, auto-fetches orderbook and computes matches. */
+    matchingOrders?: CounterpartyMatch[];
+};
+/** Parameters for cancelling an order */
+type CancelOrderParams = {
+    /** Market app ID */
+    marketAppId: number;
+    /** The escrow app ID of the order to cancel */
+    escrowAppId: number;
+    /** The owner address of the order */
+    orderOwner: string;
+};
+/** Parameters for proposing a match between two existing orders */
+type ProposeMatchParams = {
+    /** Market app ID */
+    marketAppId: number;
+    /** The maker escrow app ID (existing order) */
+    makerEscrowAppId: number;
+    /** The maker's Algorand address */
+    makerAddress: string;
+    /** Quantity to match in microunits */
+    quantityMatched: number;
+};
+/** A counterparty order to match against */
+type CounterpartyMatch = {
+    /** Escrow app ID of the counterparty order */
+    escrowAppId: number;
+    /** Quantity available to match in microunits */
+    quantity: number;
+    /** Owner address of the counterparty order */
+    owner: string;
+};
+/** Result of creating an order */
+type CreateOrderResult = {
+    /** The escrow app ID of the newly created order */
+    escrowAppId: number;
+    /** Transaction IDs from the atomic group */
+    txIds: string[];
+    /** Confirmed round number */
+    confirmedRound: number;
+};
+/** Result of creating a market order (includes match info) */
+type CreateMarketOrderResult = CreateOrderResult & {
+    /** Total quantity that was matched */
+    matchedQuantity: number;
+};
+/** Result of cancelling an order */
+type CancelOrderResult = {
+    /** Whether the cancellation succeeded */
+    success: boolean;
+    /** Transaction IDs */
+    txIds: string[];
+};
+/** Result of proposing a match */
+type ProposeMatchResult = {
+    /** Whether the match succeeded */
+    success: boolean;
+    /** Transaction IDs */
+    txIds: string[];
+};
+/** A single entry in the orderbook (one price level, one order) */
+type OrderbookEntry = {
+    /** Price in microunits (e.g. 500000 = $0.50) */
+    price: number;
+    /** Remaining quantity in microunits */
+    quantity: number;
+    /** Escrow app ID for this order */
+    escrowAppId: number;
+    /** Owner address */
+    owner: string;
+};
+/** One side (bids or asks) of the orderbook */
+type OrderbookSide = {
+    bids: OrderbookEntry[];
+    asks: OrderbookEntry[];
+};
+/** Full orderbook for a market */
+type Orderbook = {
+    yes: OrderbookSide;
+    no: OrderbookSide;
+};
+/** Aggregated orderbook entry (multiple orders at same price) */
+type AggregatedOrderbookEntry = {
+    /** Price in microunits */
+    price: number;
+    /** Total quantity at this price level in microunits */
+    quantity: number;
+    /** Number of orders at this price level */
+    orderCount: number;
+};
+/** Aggregated orderbook side */
+type AggregatedOrderbookSide = {
+    bids: AggregatedOrderbookEntry[];
+    asks: AggregatedOrderbookEntry[];
+};
+/** Aggregated orderbook for display */
+type AggregatedOrderbook = {
+    yes: AggregatedOrderbookSide;
+    no: AggregatedOrderbookSide;
+};
+/** Parameters for split shares */
+type SplitSharesParams = {
+    /** Market app ID */
+    marketAppId: number;
+    /** Amount to split in microunits (e.g. 1000000 = $1.00 USDC) */
+    amount: number;
+};
+/** Parameters for merge shares */
+type MergeSharesParams = {
+    /** Market app ID */
+    marketAppId: number;
+    /** Amount to merge in microunits */
+    amount: number;
+};
+/** Parameters for claiming resolved tokens */
+type ClaimParams = {
+    /** Market app ID */
+    marketAppId: number;
+    /** The outcome token ASA ID to redeem */
+    assetId: number;
+    /** Amount to claim in microunits. If omitted, claims entire balance. */
+    amount?: number;
+};
+/** Result of a split or merge operation */
+type SplitMergeResult = {
+    success: boolean;
+    txIds: string[];
+    confirmedRound: number;
+};
+/** Result of a claim operation */
+type ClaimResult = {
+    success: boolean;
+    txIds: string[];
+    confirmedRound: number;
+};
+/** A wallet's token position in a market */
+type WalletPosition = {
+    /** Market app ID */
+    marketAppId: number;
+    /** YES token ASA ID */
+    yesAssetId: number;
+    /** NO token ASA ID */
+    noAssetId: number;
+    /** YES token balance in microunits */
+    yesBalance: number;
+    /** NO token balance in microunits */
+    noBalance: number;
+};
+/** An open order belonging to the wallet */
+type OpenOrder = {
+    /** Escrow app ID */
+    escrowAppId: number;
+    /** Market app ID */
+    marketAppId: number;
+    /** Position: 0=No, 1=Yes */
+    position: Position;
+    /** Side: 0=Sell, 1=Buy */
+    side: number;
+    /** Price in microunits */
+    price: number;
+    /** Total quantity in microunits */
+    quantity: number;
+    /** Filled quantity in microunits */
+    quantityFilled: number;
+    /** Slippage in microunits (0 = limit order) */
+    slippage: number;
+    /** Owner address */
+    owner: string;
+};
+/** Raw global state of an escrow app */
+type EscrowGlobalState = {
+    position?: number;
+    side?: number;
+    price?: number;
+    quantity?: number;
+    quantity_filled?: number;
+    slippage?: number;
+    owner?: string;
+    market_app_id?: number;
+    asset_listed?: number;
+    fee_timer_start?: number;
+};
+
+/**
+ * The main client for interacting with Alpha Market prediction markets on Algorand.
+ *
+ * Provides methods for:
+ * - **Trading**: Create limit/market orders, cancel orders, propose matches
+ * - **Positions**: Split/merge shares, claim resolved tokens, view positions
+ * - **Orderbook**: Read on-chain orderbook for any market
+ * - **Markets**: Fetch live markets from the Alpha API
+ *
+ * @example
+ * ```typescript
+ * import { AlphaClient } from '@alpha-market/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,
+ *   matcherAppId: 741347297,
+ *   usdcAssetId: 31566704,
+ *   feeAddress: 'FEE_ADDRESS_HERE',
+ * });
+ *
+ * // Fetch markets
+ * const markets = await client.getMarkets();
+ *
+ * // Place a limit order
+ * const result = await client.createLimitOrder({
+ *   marketAppId: markets[0].marketAppId,
+ *   position: 1, // Yes
+ *   price: 500_000, // $0.50
+ *   quantity: 1_000_000, // 1 share
+ *   isBuying: true,
+ * });
+ * ```
+ */
+declare class AlphaClient {
+    private config;
+    constructor(config: AlphaClientConfig);
+    /**
+     * 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.
+     *
+     * @param params - Order parameters (marketAppId, position, price, quantity, isBuying)
+     * @returns The created escrow app ID and transaction info
+     */
+    createLimitOrder(params: CreateLimitOrderParams): Promise<CreateOrderResult>;
+    /**
+     * 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.
+     *
+     * @param params - Order parameters (marketAppId, position, price, quantity, isBuying, slippage)
+     * @returns The created escrow app ID, matched quantity, and transaction info
+     */
+    createMarketOrder(params: CreateMarketOrderParams): Promise<CreateMarketOrderResult>;
+    /**
+     * 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.
+     *
+     * @param params - Cancel parameters (marketAppId, escrowAppId, orderOwner)
+     * @returns Whether the cancellation succeeded
+     */
+    cancelOrder(params: CancelOrderParams): Promise<CancelOrderResult>;
+    /**
+     * 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.
+     *
+     * @param params - Match parameters (marketAppId, makerEscrowAppId, makerAddress, quantityMatched)
+     * @returns Whether the match succeeded
+     */
+    proposeMatch(params: ProposeMatchParams): Promise<ProposeMatchResult>;
+    /**
+     * 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.
+     *
+     * @param params - Split parameters (marketAppId, amount in microunits)
+     * @returns Transaction result
+     */
+    splitShares(params: SplitSharesParams): Promise<SplitMergeResult>;
+    /**
+     * Merges equal amounts of YES and NO tokens back into USDC.
+     *
+     * The inverse of split. 1 YES + 1 NO = 1 USDC, always.
+     *
+     * @param params - Merge parameters (marketAppId, amount in microunits)
+     * @returns Transaction result
+     */
+    mergeShares(params: MergeSharesParams): Promise<SplitMergeResult>;
+    /**
+     * 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)
+     *
+     * @param params - Claim parameters (marketAppId, assetId, optional amount)
+     * @returns Transaction result
+     */
+    claim(params: ClaimParams): Promise<ClaimResult>;
+    /**
+     * 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).
+     *
+     * @param walletAddress - Optional wallet (defaults to activeAddress)
+     * @returns Array of positions with market app IDs and token balances
+     */
+    getPositions(walletAddress?: string): Promise<WalletPosition[]>;
+    /**
+     * 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.
+     *
+     * @param marketAppId - The market app ID
+     * @returns Orderbook with yes and no sides, each having bids and asks
+     */
+    getOrderbook(marketAppId: number): Promise<Orderbook>;
+    /**
+     * Gets open orders for a specific wallet on a market.
+     *
+     * @param marketAppId - The market app ID
+     * @param walletAddress - Optional wallet (defaults to activeAddress)
+     * @returns Array of open orders
+     */
+    getOpenOrders(marketAppId: number, walletAddress?: string): Promise<OpenOrder[]>;
+    /**
+     * Fetches all live, tradeable markets from the Alpha API.
+     *
+     * Automatically paginates to retrieve all markets.
+     *
+     * @returns Array of live markets
+     */
+    getMarkets(): Promise<Market[]>;
+    /**
+     * Fetches a single market by its ID.
+     *
+     * @param marketId - The market ID
+     * @returns The market data, or null if not found
+     */
+    getMarket(marketId: string): Promise<Market | null>;
+}
+
+/**
+ * Calculates the required fee amount in microunits.
+ *
+ * Formula: `fee = feeBase * quantity * price * (1 - price)`
+ *
+ * All values are in microunits where 1,000,000 = $1.00.
+ *
+ * @param quantity - Order quantity in microunits (e.g. 1_000_000 for 1 share)
+ * @param price - Order price in microunits (e.g. 500_000 for $0.50)
+ * @param feeBase - Fee base in microunits (e.g. 70_000 for 7%)
+ * @returns Fee amount in microunits (ceiling)
+ *
+ * @example
+ * ```typescript
+ * // 1 share at $0.50 with 7% fee base
+ * calculateFee(1_000_000, 500_000, 70_000); // => 17500
+ * ```
+ */
+declare const calculateFee: (quantity: number | bigint, price: number | bigint, feeBase: number | bigint) => number;
+/**
+ * Calculates the fee when given a total amount that includes the fee.
+ *
+ * @param totalAmount - Total amount in microunits including fee
+ * @param price - Price in microunits
+ * @param feeBase - Fee base in microunits
+ * @returns Fee amount in microunits (ceiling)
+ */
+declare const calculateFeeFromTotal: (totalAmount: number | bigint, price: number | bigint, feeBase: number | bigint) => number;
+
+/**
+ * Computes matching counterparty orders from an orderbook for a given order.
+ *
+ * Supports both direct matching (Buy YES vs Sell YES) and complementary matching
+ * (Buy YES at 60c vs Buy NO at 40c — prices sum to $1.00).
+ *
+ * @param orderbook - The full orderbook for the market
+ * @param isBuying - Whether the taker is buying
+ * @param isYes - Whether the taker's position is Yes (true) or No (false)
+ * @param quantity - Desired quantity in microunits
+ * @param price - Desired price in microunits
+ * @param slippageTolerance - Maximum acceptable slippage in microunits
+ * @returns Array of counterparty matches, sorted by best price, up to the requested quantity
+ */
+declare const calculateMatchingOrders: (orderbook: Orderbook, isBuying: boolean, isYes: boolean, quantity: number, price: number, slippageTolerance: number) => CounterpartyMatch[];
+
+/**
+ * Decodes raw Algorand global state array into a key-value object.
+ *
+ * @param rawState - The raw global-state array from algod/indexer
+ * @returns Decoded key-value object
+ */
+declare const decodeGlobalState: (rawState: any[]) => Record<string, any>;
+/**
+ * Reads the global state of a market app from the chain.
+ *
+ * @param algodClient - Algod client
+ * @param marketAppId - The market app ID
+ * @returns Decoded market global state
+ */
+declare const getMarketGlobalState: (algodClient: algosdk.Algodv2, marketAppId: number) => Promise<MarketGlobalState>;
+/**
+ * Reads the global state of an escrow app via the indexer.
+ *
+ * @param indexerClient - Indexer client
+ * @param escrowAppId - The escrow app ID
+ * @returns Decoded escrow global state
+ */
+declare const getEscrowGlobalState: (indexerClient: algosdk.Indexer, escrowAppId: number) => Promise<EscrowGlobalState>;
+/**
+ * Checks if an address has opted into an ASA.
+ *
+ * @param algodClient - Algod client
+ * @param address - The Algorand address to check
+ * @param assetId - The ASA ID to check
+ * @returns True if opted in
+ */
+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 };