@goplausible/algorand-mcp 3.7.0 → 3.9.0

package/dist/index.js

@@ -137,6 +137,10 @@ class AlgorandMcpServer {
             if (name.startsWith('api_')) {
                 return handleApiManager(name, args);
             }
+            // Handle Alpha Arcade tools
+            if (name.startsWith('alpha_')) {
+                return handleApiManager(name, args);
+            }
             // Handle ARC-26 tools
             if (name === 'generate_algorand_uri') {
                 return arc26Manager.handleTool(name, args);

package/dist/tools/apiManager/alpha/alphaClient.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Alpha Arcade client factory for the local MCP wallet system.
+ * Creates AlphaClient instances backed by the WalletManager keychain signer.
+ */
+import { AlphaClient } from '@alpha-arcade/sdk';
+import { type NetworkId } from '../../../algorand-client.js';
+export declare const MATCHER_APP_ID = 3078581851;
+export declare const USDC_ASSET_ID = 31566704;
+export declare const API_BASE_URL = "https://platform.alphaarcade.com/api";
+declare const ALPHA_API_KEY: string;
+export declare const formatPrice: (microunits: number) => string;
+export declare const formatQty: (microunits: number) => string;
+export declare const formatPriceFromProb: (microunits: number) => string;
+export declare function friendlyTradeError(msg: string): string;
+/**
+ * Create a read-only AlphaClient (no signing capability).
+ * Used for market queries, orderbook, positions lookups.
+ */
+export declare function createReadOnlyClient(network: NetworkId): AlphaClient;
+/**
+ * Create a trading AlphaClient backed by the local wallet keychain.
+ * Uses the active wallet account's secret key for signing.
+ */
+export declare function createTradingClient(network: NetworkId): Promise<AlphaClient>;
+/**
+ * Resolve wallet address — uses provided address or falls back to active wallet.
+ */
+export declare function resolveWalletAddress(walletAddress?: string): Promise<string>;
+export { ALPHA_API_KEY };

package/dist/tools/apiManager/alpha/alphaClient.js

@@ -0,0 +1,121 @@
+/**
+ * Alpha Arcade client factory for the local MCP wallet system.
+ * Creates AlphaClient instances backed by the WalletManager keychain signer.
+ */
+import { AlphaClient } from '@alpha-arcade/sdk';
+import algosdk from 'algosdk';
+import { getAlgodClient, getIndexerClient } from '../../../algorand-client.js';
+import { WalletManager } from '../../walletManager.js';
+// ── Constants ──────────────────────────────────────────────────────────────
+export const MATCHER_APP_ID = 3078581851;
+export const USDC_ASSET_ID = 31566704;
+export const API_BASE_URL = 'https://platform.alphaarcade.com/api';
+// Read optional env vars once
+const ALPHA_API_KEY = process.env.ALPHA_API_KEY || '';
+const ALPHA_API_BASE_URL = process.env.ALPHA_API_BASE_URL || API_BASE_URL;
+// ── Formatting helpers ─────────────────────────────────────────────────────
+export const formatPrice = (microunits) => `$${(microunits / 1e6).toFixed(2)}`;
+export const formatQty = (microunits) => `${(microunits / 1e6).toFixed(2)} shares`;
+export const formatPriceFromProb = (microunits) => `$${(microunits / 1e6).toFixed(2)}`;
+// ── Friendly error messages ────────────────────────────────────────────────
+export function friendlyTradeError(msg) {
+    const m = msg || 'Unknown error';
+    const isUsdcError = m.includes(String(USDC_ASSET_ID)) || /usdc/i.test(m);
+    const overspendAlgo = m.match(/overspend.*?MicroAlgos:\{Raw:(\d+)\}.*?tried to spend \{(\d+)\}/i);
+    if (overspendAlgo) {
+        const have = (Number.parseInt(overspendAlgo[1], 10) / 1e6).toFixed(2);
+        const need = (Number.parseInt(overspendAlgo[2], 10) / 1e6).toFixed(2);
+        return `Insufficient ALGO balance. You have ~${have} ALGO but need ~${need} ALGO (escrow collateral + fees). Please fund your wallet with more ALGO.`;
+    }
+    const overspendAsset = m.match(/overspend.*?asset.*?(\d+).*?holding:\{Amount:(\d+)\}.*?tried to spend \{(\d+)\}/i);
+    if (overspendAsset) {
+        const assetId = overspendAsset[1];
+        const have = (Number.parseInt(overspendAsset[2], 10) / 1e6).toFixed(2);
+        const need = (Number.parseInt(overspendAsset[3], 10) / 1e6).toFixed(2);
+        const label = assetId === String(USDC_ASSET_ID) ? 'USDC' : `asset ${assetId}`;
+        return `Insufficient ${label} balance. You have ~$${have} but need ~$${need}. Please add more ${label} to your wallet.`;
+    }
+    if (/overspend/i.test(m)) {
+        const label = isUsdcError ? 'USDC' : 'ALGO';
+        return `Insufficient ${label} balance to cover this transaction. Please add more ${label} to your wallet.`;
+    }
+    if (/underflow/i.test(m)) {
+        const label = isUsdcError ? 'USDC' : 'token';
+        return `Insufficient ${label} balance for this operation. Make sure you hold enough ${label} before trading.`;
+    }
+    if (/asset \d+ missing/i.test(m) || /not opted in/i.test(m)) {
+        if (isUsdcError)
+            return "Your account hasn't opted in to USDC. Please opt in to USDC (asset 31566704) first.";
+        return "Your account hasn't opted in to a required asset. Please opt in first.";
+    }
+    if (/below min/i.test(m) || /min balance/i.test(m)) {
+        return 'This transaction would drop your account below the minimum ALGO balance. Please add more ALGO.';
+    }
+    if (/account.*has been closed/i.test(m) || /dead account/i.test(m)) {
+        return 'The target account has been closed and cannot receive transactions.';
+    }
+    if (/group size/i.test(m)) {
+        return 'Transaction group error. Please try again.';
+    }
+    if (/logic eval error/i.test(m) || /rejected by logic/i.test(m)) {
+        return 'The smart contract rejected this transaction. The order parameters may be invalid or the market conditions have changed. Please try again.';
+    }
+    if (/timeout/i.test(m) || /network/i.test(m) || /ECONNREFUSED/i.test(m)) {
+        return 'Network error reaching the Algorand node. Please try again in a moment.';
+    }
+    return m;
+}
+// ── Client factories ───────────────────────────────────────────────────────
+/**
+ * Create a read-only AlphaClient (no signing capability).
+ * Used for market queries, orderbook, positions lookups.
+ */
+export function createReadOnlyClient(network) {
+    const algodClient = getAlgodClient(network);
+    const indexerClient = getIndexerClient(network);
+    const dummySigner = async () => [];
+    return new AlphaClient({
+        algodClient,
+        indexerClient,
+        signer: dummySigner,
+        activeAddress: 'AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ',
+        matcherAppId: MATCHER_APP_ID,
+        usdcAssetId: USDC_ASSET_ID,
+        apiBaseUrl: ALPHA_API_BASE_URL,
+        apiKey: ALPHA_API_KEY || undefined,
+    });
+}
+/**
+ * Create a trading AlphaClient backed by the local wallet keychain.
+ * Uses the active wallet account's secret key for signing.
+ */
+export async function createTradingClient(network) {
+    const account = await WalletManager.getActiveWalletAccount();
+    const sk = await WalletManager.getActiveWalletSecretKey();
+    const address = account.address;
+    const algodClient = getAlgodClient(network);
+    const indexerClient = getIndexerClient(network);
+    const signer = async (txnGroup, indexesToSign) => {
+        return indexesToSign.map((idx) => algosdk.signTransaction(txnGroup[idx], sk).blob);
+    };
+    return new AlphaClient({
+        algodClient,
+        indexerClient,
+        signer,
+        activeAddress: address,
+        matcherAppId: MATCHER_APP_ID,
+        usdcAssetId: USDC_ASSET_ID,
+        apiBaseUrl: ALPHA_API_BASE_URL,
+        apiKey: ALPHA_API_KEY || undefined,
+    });
+}
+/**
+ * Resolve wallet address — uses provided address or falls back to active wallet.
+ */
+export async function resolveWalletAddress(walletAddress) {
+    if (walletAddress)
+        return walletAddress;
+    const account = await WalletManager.getActiveWalletAccount();
+    return account.address;
+}
+export { ALPHA_API_KEY };

package/dist/tools/apiManager/alpha/index.d.ts

@@ -0,0 +1,3 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const alphaTools: Tool[];
+export declare function handleAlphaTools(name: string, args: any): Promise<any>;

package/dist/tools/apiManager/alpha/index.js

@@ -0,0 +1,50 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { marketTools, handleMarketTools } from './markets.js';
+import { positionTools, handlePositionTools } from './positions.js';
+import { tradingTools, handleTradingTools } from './trading.js';
+import { shareTools, handleShareTools } from './shares.js';
+// Combine all Alpha Arcade tools
+export const alphaTools = [
+    ...marketTools,
+    ...positionTools,
+    ...tradingTools,
+    ...shareTools,
+];
+// Handle all Alpha Arcade tools
+export async function handleAlphaTools(name, args) {
+    try {
+        const combinedArgs = { name, ...args };
+        // Market query tools
+        if (name === 'alpha_get_live_markets' ||
+            name === 'alpha_get_reward_markets' ||
+            name === 'alpha_get_market' ||
+            name === 'alpha_get_orderbook') {
+            return handleMarketTools(combinedArgs);
+        }
+        // Position/order query tools
+        if (name === 'alpha_get_open_orders' || name === 'alpha_get_positions') {
+            return handlePositionTools(combinedArgs);
+        }
+        // Trading tools
+        if (name === 'alpha_create_limit_order' ||
+            name === 'alpha_create_market_order' ||
+            name === 'alpha_cancel_order' ||
+            name === 'alpha_amend_order' ||
+            name === 'alpha_propose_match') {
+            return handleTradingTools(combinedArgs);
+        }
+        // Share management tools
+        if (name === 'alpha_split_shares' ||
+            name === 'alpha_merge_shares' ||
+            name === 'alpha_claim') {
+            return handleShareTools(combinedArgs);
+        }
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown Alpha Arcade tool: ${name}`);
+    }
+    catch (error) {
+        if (error instanceof McpError) {
+            throw error;
+        }
+        throw new McpError(ErrorCode.InternalError, `Failed to handle Alpha Arcade tool: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/tools/apiManager/alpha/markets.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Alpha Arcade read-only market tools: get_live_markets, get_reward_markets, get_market, get_orderbook
+ */
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const marketTools: Tool[];
+export declare function handleMarketTools(args: any): Promise<any>;

package/dist/tools/apiManager/alpha/markets.js

@@ -0,0 +1,193 @@
+/**
+ * Alpha Arcade read-only market tools: get_live_markets, get_reward_markets, get_market, get_orderbook
+ */
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { extractNetwork } from '../../../algorand-client.js';
+import { withCommonParams } from '../../commonParams.js';
+import { createReadOnlyClient, formatPriceFromProb, ALPHA_API_KEY, } from './alphaClient.js';
+export const marketTools = [
+    {
+        name: 'alpha_get_live_markets',
+        description: 'Fetch all live Alpha Arcade prediction markets. Returns summary: id, title, marketAppId, prices, volume. Multi-choice markets have an options[] array — use options[].marketAppId for trading.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {},
+            required: [],
+        }),
+    },
+    {
+        name: 'alpha_get_reward_markets',
+        description: 'Fetch Alpha Arcade markets with liquidity rewards (totalRewards, rewardsPaidOut, etc.). Same shape as alpha_get_live_markets but includes reward info. Requires ALPHA_API_KEY.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {},
+            required: [],
+        }),
+    },
+    {
+        name: 'alpha_get_market',
+        description: 'Fetch full details for a single Alpha Arcade prediction market. Pass marketAppId (numeric, always required) and optionally marketId (UUID) for richer API data.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: {
+                    type: 'number',
+                    description: 'The market application ID (numeric, always required)',
+                },
+                marketId: {
+                    type: 'string',
+                    description: 'The market UUID (optional, used for API mode when ALPHA_API_KEY is set)',
+                },
+            },
+            required: ['marketAppId'],
+        }),
+    },
+    {
+        name: 'alpha_get_orderbook',
+        description: 'Fetch the on-chain orderbook as a unified YES-perspective view. Merges all 4 sides (YES bids/asks + NO bids/asks). Includes spread calculation.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: {
+                    type: 'number',
+                    description: 'The market app ID',
+                },
+            },
+            required: ['marketAppId'],
+        }),
+    },
+];
+function formatMarketSummary(m) {
+    const vol = typeof m.volume === 'number' ? m.volume : Number.parseFloat(String(m.volume ?? ''));
+    const entry = {
+        id: m.id,
+        title: m.title || `Market ${m.marketAppId}`,
+        marketAppId: m.marketAppId,
+        image: m.image,
+        yesAssetId: m.yesAssetId || undefined,
+        noAssetId: m.noAssetId || undefined,
+        yesPrice: m.yesProb != null ? formatPriceFromProb(m.yesProb) : undefined,
+        noPrice: m.noProb != null ? formatPriceFromProb(m.noProb) : undefined,
+        volume: !Number.isNaN(vol) ? `$${vol.toFixed(2)}` : undefined,
+        endsAt: m.endTs ? new Date(m.endTs * 1000).toISOString() : undefined,
+        isResolved: m.isResolved ?? false,
+        source: m.source ?? 'unknown',
+    };
+    if (m.categories?.length)
+        entry.categories = m.categories;
+    if (m.feeBase != null)
+        entry.feeBase = m.feeBase;
+    if (m.options?.length) {
+        entry.options = m.options.map((o) => ({
+            title: o.title || `Option ${o.marketAppId}`,
+            marketAppId: o.marketAppId,
+            yesAssetId: o.yesAssetId,
+            noAssetId: o.noAssetId,
+        }));
+    }
+    return entry;
+}
+export async function handleMarketTools(args) {
+    const { name, marketAppId, marketId } = args;
+    const network = extractNetwork(args);
+    const client = createReadOnlyClient(network);
+    switch (name) {
+        case 'alpha_get_live_markets': {
+            let markets;
+            try {
+                markets = await client.getLiveMarkets();
+            }
+            catch (apiErr) {
+                if (ALPHA_API_KEY) {
+                    markets = await client.getMarketsOnChain();
+                }
+                else {
+                    throw apiErr;
+                }
+            }
+            const summary = markets.map(formatMarketSummary);
+            return { markets: summary, type: 'live' };
+        }
+        case 'alpha_get_reward_markets': {
+            if (!ALPHA_API_KEY) {
+                return { error: 'Reward markets require an ALPHA_API_KEY. Set it in your environment to access reward market data.' };
+            }
+            const markets = await client.getRewardMarkets();
+            const summary = markets.map((m) => {
+                const entry = formatMarketSummary(m);
+                if (m.totalRewards != null)
+                    entry.totalRewards = m.totalRewards;
+                if (m.rewardsPaidOut != null)
+                    entry.rewardsPaidOut = m.rewardsPaidOut;
+                if (m.rewardsSpreadDistance != null)
+                    entry.rewardsSpreadDistance = m.rewardsSpreadDistance;
+                if (m.rewardsMinContracts != null)
+                    entry.rewardsMinContracts = m.rewardsMinContracts;
+                if (m.lastRewardAmount != null)
+                    entry.lastRewardAmount = m.lastRewardAmount;
+                if (m.lastRewardTs != null)
+                    entry.lastRewardTs = new Date(m.lastRewardTs).toISOString();
+                return entry;
+            });
+            return { markets: summary, type: 'reward' };
+        }
+        case 'alpha_get_market': {
+            if (!marketAppId) {
+                throw new McpError(ErrorCode.InvalidParams, 'marketAppId is required');
+            }
+            let market = null;
+            if (ALPHA_API_KEY && marketId) {
+                try {
+                    market = await client.getMarketFromApi(marketId);
+                }
+                catch {
+                    // fall through to on-chain
+                }
+            }
+            if (!market) {
+                market = await client.getMarketOnChain(marketAppId).catch(() => null);
+            }
+            if (!market) {
+                return { error: `Market ${marketAppId} not found.` };
+            }
+            return market;
+        }
+        case 'alpha_get_orderbook': {
+            if (!marketAppId) {
+                throw new McpError(ErrorCode.InvalidParams, 'marketAppId is required');
+            }
+            const book = await client.getOrderbook(marketAppId);
+            const toUnified = (e, source, priceOverride) => {
+                const p = priceOverride ?? e.price;
+                const priceCents = p / 1000000;
+                const shares = e.quantity / 1000000;
+                return {
+                    price: `${(priceCents * 100).toFixed(2)}¢`,
+                    priceRaw: p,
+                    shares: `${shares.toFixed(2)}`,
+                    total: `$${(priceCents * shares).toFixed(2)}`,
+                    escrowAppId: e.escrowAppId,
+                    owner: e.owner,
+                    source,
+                };
+            };
+            const asks = [
+                ...book.yes.asks.map((e) => toUnified(e, 'YES ask')),
+                ...book.no.bids.map((e) => toUnified(e, 'NO bid (= YES ask)', 1000000 - e.price)),
+            ].sort((a, b) => a.priceRaw - b.priceRaw);
+            const bids = [
+                ...book.yes.bids.map((e) => toUnified(e, 'YES bid')),
+                ...book.no.asks.map((e) => toUnified(e, 'NO ask (= YES bid)', 1000000 - e.price)),
+            ].sort((a, b) => b.priceRaw - a.priceRaw);
+            const bestAsk = asks.length > 0 ? asks[0].priceRaw : null;
+            const bestBid = bids.length > 0 ? bids[0].priceRaw : null;
+            const spread = bestAsk != null && bestBid != null
+                ? `${((bestAsk - bestBid) / 10000).toFixed(2)}¢`
+                : 'N/A';
+            const totalOrders = book.yes.bids.length + book.yes.asks.length + book.no.bids.length + book.no.asks.length;
+            return { unified: { asks, bids, spread }, totalOrders, marketAppId };
+        }
+        default:
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown Alpha market tool: ${name}`);
+    }
+}

package/dist/tools/apiManager/alpha/positions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Alpha Arcade position and order query tools: get_open_orders, get_positions
+ */
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const positionTools: Tool[];
+export declare function handlePositionTools(args: any): Promise<any>;

package/dist/tools/apiManager/alpha/positions.js

@@ -0,0 +1,80 @@
+/**
+ * Alpha Arcade position and order query tools: get_open_orders, get_positions
+ */
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { extractNetwork } from '../../../algorand-client.js';
+import { withCommonParams } from '../../commonParams.js';
+import { createReadOnlyClient, resolveWalletAddress, formatPrice, formatQty, } from './alphaClient.js';
+export const positionTools = [
+    {
+        name: 'alpha_get_open_orders',
+        description: 'Fetch all open orders for a wallet on a specific Alpha Arcade market. Uses your active MCP wallet if walletAddress is not provided.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: {
+                    type: 'number',
+                    description: 'The market app ID',
+                },
+                walletAddress: {
+                    type: 'string',
+                    description: 'Algorand wallet address (uses active MCP wallet if omitted)',
+                },
+            },
+            required: ['marketAppId'],
+        }),
+    },
+    {
+        name: 'alpha_get_positions',
+        description: 'Fetch all YES/NO token positions for a wallet across all Alpha Arcade markets. Uses your active MCP wallet if walletAddress is not provided.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                walletAddress: {
+                    type: 'string',
+                    description: 'Algorand wallet address (uses active MCP wallet if omitted)',
+                },
+            },
+            required: [],
+        }),
+    },
+];
+export async function handlePositionTools(args) {
+    const { name, marketAppId, walletAddress } = args;
+    const network = extractNetwork(args);
+    const client = createReadOnlyClient(network);
+    switch (name) {
+        case 'alpha_get_open_orders': {
+            if (!marketAppId) {
+                throw new McpError(ErrorCode.InvalidParams, 'marketAppId is required');
+            }
+            const address = await resolveWalletAddress(walletAddress);
+            const orders = await client.getOpenOrders(marketAppId, address);
+            const formatted = orders.map((o) => ({
+                escrowAppId: o.escrowAppId,
+                position: o.position === 1 ? 'YES' : 'NO',
+                side: o.side === 1 ? 'BUY' : 'SELL',
+                price: formatPrice(o.price),
+                quantity: formatQty(o.quantity),
+                filled: formatQty(o.quantityFilled),
+                remaining: formatQty(o.quantity - o.quantityFilled),
+            }));
+            return { orders: formatted, marketAppId, walletAddress: address };
+        }
+        case 'alpha_get_positions': {
+            const address = await resolveWalletAddress(walletAddress);
+            const positions = await client.getPositions(address);
+            const formatted = positions.map((p) => ({
+                marketAppId: p.marketAppId,
+                title: p.title || `Market ${p.marketAppId}`,
+                yesBalance: formatQty(p.yesBalance),
+                noBalance: formatQty(p.noBalance),
+                yesAssetId: p.yesAssetId,
+                noAssetId: p.noAssetId,
+            }));
+            return { positions: formatted, walletAddress: address };
+        }
+        default:
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown Alpha position tool: ${name}`);
+    }
+}

package/dist/tools/apiManager/alpha/shares.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Alpha Arcade share management tools: split_shares, merge_shares, claim
+ */
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const shareTools: Tool[];
+export declare function handleShareTools(args: any): Promise<any>;

package/dist/tools/apiManager/alpha/shares.js

@@ -0,0 +1,109 @@
+/**
+ * Alpha Arcade share management tools: split_shares, merge_shares, claim
+ */
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { extractNetwork } from '../../../algorand-client.js';
+import { withCommonParams } from '../../commonParams.js';
+import { createTradingClient, friendlyTradeError, formatPrice, formatQty, } from './alphaClient.js';
+export const shareTools = [
+    {
+        name: 'alpha_split_shares',
+        description: 'Split USDC into equal YES and NO outcome tokens on Alpha Arcade. 1 USDC (1000000 microunits) = 1 YES + 1 NO.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: { type: 'number', description: 'The market app ID' },
+                amount: { type: 'number', description: 'Amount to split in microunits (e.g. 1000000 = $1.00 USDC)' },
+            },
+            required: ['marketAppId', 'amount'],
+        }),
+    },
+    {
+        name: 'alpha_merge_shares',
+        description: 'Merge equal YES and NO outcome tokens back into USDC on Alpha Arcade. 1 YES + 1 NO = 1 USDC.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: { type: 'number', description: 'The market app ID' },
+                amount: { type: 'number', description: 'Amount to merge in microunits' },
+            },
+            required: ['marketAppId', 'amount'],
+        }),
+    },
+    {
+        name: 'alpha_claim',
+        description: 'Claim USDC from a resolved Alpha Arcade market by redeeming outcome tokens. Winning = 1:1 USDC.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: { type: 'number', description: 'The market app ID' },
+                assetId: { type: 'number', description: 'The outcome token ASA ID to redeem' },
+                amount: { type: 'number', description: 'Amount to claim in microunits (omit to claim entire balance)' },
+            },
+            required: ['marketAppId', 'assetId'],
+        }),
+    },
+];
+export async function handleShareTools(args) {
+    const { name } = args;
+    const network = extractNetwork(args);
+    switch (name) {
+        case 'alpha_split_shares': {
+            const { marketAppId, amount } = args;
+            try {
+                const client = await createTradingClient(network);
+                const result = await client.splitShares({ marketAppId, amount });
+                return {
+                    type: 'split',
+                    marketAppId,
+                    amount: formatQty(amount),
+                    amountUSDC: formatPrice(amount),
+                    txIds: result.txIds,
+                    confirmedRound: result.confirmedRound,
+                };
+            }
+            catch (error) {
+                return { error: `Error splitting shares: ${friendlyTradeError(error.message)}` };
+            }
+        }
+        case 'alpha_merge_shares': {
+            const { marketAppId, amount } = args;
+            try {
+                const client = await createTradingClient(network);
+                const result = await client.mergeShares({ marketAppId, amount });
+                return {
+                    type: 'merge',
+                    marketAppId,
+                    amount: formatQty(amount),
+                    amountUSDC: formatPrice(amount),
+                    txIds: result.txIds,
+                    confirmedRound: result.confirmedRound,
+                };
+            }
+            catch (error) {
+                return { error: `Error merging shares: ${friendlyTradeError(error.message)}` };
+            }
+        }
+        case 'alpha_claim': {
+            const { marketAppId, assetId, amount } = args;
+            try {
+                const client = await createTradingClient(network);
+                const result = await client.claim({ marketAppId, assetId, amount });
+                return {
+                    type: 'claim',
+                    marketAppId,
+                    assetId,
+                    amountRequested: amount != null ? formatQty(amount) : 'Full balance',
+                    amountClaimed: formatQty(result.amountClaimed),
+                    txIds: result.txIds,
+                    confirmedRound: result.confirmedRound,
+                };
+            }
+            catch (error) {
+                return { error: `Error claiming: ${friendlyTradeError(error.message)}` };
+            }
+        }
+        default:
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown Alpha share tool: ${name}`);
+    }
+}

package/dist/tools/apiManager/alpha/trading.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Alpha Arcade trading tools: create_limit_order, create_market_order, cancel_order, amend_order, propose_match
+ */
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const tradingTools: Tool[];
+export declare function handleTradingTools(args: any): Promise<any>;

package/dist/tools/apiManager/alpha/trading.js

@@ -0,0 +1,245 @@
+/**
+ * Alpha Arcade trading tools: create_limit_order, create_market_order, cancel_order, amend_order, propose_match
+ */
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { extractNetwork } from '../../../algorand-client.js';
+import { withCommonParams } from '../../commonParams.js';
+import { createTradingClient, friendlyTradeError, formatPrice, formatQty, } from './alphaClient.js';
+export const tradingTools = [
+    {
+        name: 'alpha_create_limit_order',
+        description: 'Place a limit order on an Alpha Arcade prediction market. Price and quantity in microunits (500000 = $0.50, 1000000 = 1 share). Locks ~0.957 ALGO collateral. Returns escrowAppId — save it for cancel_order.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: { type: 'number', description: 'The market app ID' },
+                position: { type: 'number', enum: [0, 1], description: '1 = Yes, 0 = No' },
+                price: { type: 'number', description: 'Price in microunits (e.g. 500000 = $0.50)' },
+                quantity: { type: 'number', description: 'Quantity in microunits (e.g. 1000000 = 1 share)' },
+                isBuying: { type: 'boolean', description: 'true = buy order, false = sell order' },
+            },
+            required: ['marketAppId', 'position', 'price', 'quantity', 'isBuying'],
+        }),
+    },
+    {
+        name: 'alpha_create_market_order',
+        description: 'Place a market order with auto-matching on Alpha Arcade. Price, quantity, and slippage in microunits. Returns escrowAppId, matched quantity, and actual fill price.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: { type: 'number', description: 'The market app ID' },
+                position: { type: 'number', enum: [0, 1], description: '1 = Yes, 0 = No' },
+                price: { type: 'number', description: 'Price in microunits (e.g. 500000 = $0.50)' },
+                quantity: { type: 'number', description: 'Quantity in microunits (e.g. 1000000 = 1 share)' },
+                isBuying: { type: 'boolean', description: 'true = buy order, false = sell order' },
+                slippage: { type: 'number', description: 'Slippage tolerance in microunits (e.g. 50000 = $0.05)' },
+            },
+            required: ['marketAppId', 'position', 'price', 'quantity', 'isBuying', 'slippage'],
+        }),
+    },
+    {
+        name: 'alpha_cancel_order',
+        description: 'Cancel an open Alpha Arcade order. Requires escrowAppId and orderOwner. Refunds USDC/tokens and ~0.957 ALGO collateral.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: { type: 'number', description: 'The market app ID' },
+                escrowAppId: { type: 'number', description: 'The escrow app ID of the order to cancel' },
+                orderOwner: { type: 'string', description: 'The Algorand address that owns the order' },
+            },
+            required: ['marketAppId', 'escrowAppId', 'orderOwner'],
+        }),
+    },
+    {
+        name: 'alpha_amend_order',
+        description: 'Edit an existing unfilled Alpha Arcade order in-place (change price, quantity, or slippage). Faster than cancel + recreate.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: { type: 'number', description: 'The market app ID' },
+                escrowAppId: { type: 'number', description: 'The escrow app ID of the order to amend' },
+                price: { type: 'number', description: 'New price in microunits' },
+                quantity: { type: 'number', description: 'New quantity in microunits' },
+                slippage: { type: 'number', description: 'New slippage in microunits (default 0)' },
+            },
+            required: ['marketAppId', 'escrowAppId', 'price', 'quantity'],
+        }),
+    },
+    {
+        name: 'alpha_propose_match',
+        description: 'Propose a match between an existing maker order and your wallet as taker on Alpha Arcade.',
+        inputSchema: withCommonParams({
+            type: 'object',
+            properties: {
+                marketAppId: { type: 'number', description: 'The market app ID' },
+                makerEscrowAppId: { type: 'number', description: 'The escrow app ID of the maker order' },
+                makerAddress: { type: 'string', description: 'The Algorand address of the maker' },
+                quantityMatched: { type: 'number', description: 'Quantity to match in microunits' },
+            },
+            required: ['marketAppId', 'makerEscrowAppId', 'makerAddress', 'quantityMatched'],
+        }),
+    },
+];
+export async function handleTradingTools(args) {
+    const { name } = args;
+    const network = extractNetwork(args);
+    switch (name) {
+        case 'alpha_create_limit_order': {
+            const { marketAppId, position, price, quantity, isBuying } = args;
+            const safePrice = Math.max(0, Math.round(price));
+            const safeQty = Math.max(0, Math.round(quantity));
+            if (safePrice <= 0 || safePrice > 1000000) {
+                return { error: `Invalid price: ${price}. Price must be between 1 and 1000000 microunits ($0.000001–$1.00).` };
+            }
+            if (safeQty <= 0 || safeQty > 1000000000000) {
+                return { error: `Invalid quantity: ${quantity}. Quantity must be positive and reasonable.` };
+            }
+            try {
+                const client = await createTradingClient(network);
+                const result = await client.createLimitOrder({
+                    marketAppId,
+                    position: position,
+                    price: safePrice,
+                    quantity: safeQty,
+                    isBuying,
+                });
+                const posLabel = position === 1 ? 'YES' : 'NO';
+                const sideLabel = isBuying ? 'BUY' : 'SELL';
+                return {
+                    type: 'limit',
+                    marketAppId,
+                    escrowAppId: result.escrowAppId,
+                    position: posLabel,
+                    side: sideLabel,
+                    price: formatPrice(price),
+                    quantity: formatQty(quantity),
+                    txIds: result.txIds,
+                    confirmedRound: result.confirmedRound,
+                };
+            }
+            catch (error) {
+                return { error: `Error creating limit order: ${friendlyTradeError(error.message)}` };
+            }
+        }
+        case 'alpha_create_market_order': {
+            const { marketAppId, position, price, quantity, isBuying, slippage } = args;
+            const safePrice = Math.max(0, Math.round(price));
+            const safeQty = Math.max(0, Math.round(quantity));
+            const safeSlip = Math.max(0, Math.round(slippage));
+            if (safePrice <= 0 || safePrice > 1000000) {
+                return { error: `Invalid price: ${price}. Price must be between 1 and 1000000 microunits ($0.000001–$1.00).` };
+            }
+            if (safeQty <= 0 || safeQty > 1000000000000) {
+                return { error: `Invalid quantity: ${quantity}. Quantity must be positive and reasonable.` };
+            }
+            const estFund = Math.floor((safeQty * (safePrice + safeSlip)) / 1000000);
+            if (estFund < 0 || estFund > Number.MAX_SAFE_INTEGER) {
+                return { error: `Computed fund amount (${estFund}) would overflow. Reduce your trade amount.` };
+            }
+            try {
+                const client = await createTradingClient(network);
+                const result = await client.createMarketOrder({
+                    marketAppId,
+                    position: position,
+                    price: safePrice,
+                    quantity: safeQty,
+                    isBuying,
+                    slippage: safeSlip,
+                });
+                const posLabel = position === 1 ? 'YES' : 'NO';
+                const sideLabel = isBuying ? 'BUY' : 'SELL';
+                return {
+                    type: 'market',
+                    marketAppId,
+                    escrowAppId: result.escrowAppId,
+                    position: posLabel,
+                    side: sideLabel,
+                    price: formatPrice(price),
+                    quantity: formatQty(quantity),
+                    fillPrice: formatPrice(result.matchedPrice ?? 0),
+                    matchedQuantity: formatQty(result.matchedQuantity ?? 0),
+                    txIds: result.txIds,
+                    confirmedRound: result.confirmedRound,
+                };
+            }
+            catch (error) {
+                return { error: `Error creating market order: ${friendlyTradeError(error.message)}` };
+            }
+        }
+        case 'alpha_cancel_order': {
+            const { marketAppId, escrowAppId, orderOwner } = args;
+            try {
+                const client = await createTradingClient(network);
+                const result = await client.cancelOrder({ marketAppId, escrowAppId, orderOwner });
+                const success = result.success !== false;
+                return {
+                    type: 'cancel',
+                    success,
+                    marketAppId,
+                    escrowAppId,
+                    orderOwner,
+                    txIds: result.txIds ?? [],
+                    confirmedRound: result.confirmedRound ?? 0,
+                };
+            }
+            catch (error) {
+                return { error: `Error cancelling order: ${friendlyTradeError(error.message)}` };
+            }
+        }
+        case 'alpha_amend_order': {
+            const { marketAppId, escrowAppId, price, quantity, slippage } = args;
+            try {
+                const client = await createTradingClient(network);
+                const result = await client.amendOrder({
+                    marketAppId,
+                    escrowAppId,
+                    price,
+                    quantity,
+                    slippage,
+                });
+                const success = result.success !== false;
+                return {
+                    type: 'amend',
+                    success,
+                    marketAppId,
+                    escrowAppId,
+                    newPrice: formatPrice(price),
+                    newQuantity: formatQty(quantity),
+                    txIds: result.txIds ?? [],
+                    confirmedRound: result.confirmedRound ?? 0,
+                };
+            }
+            catch (error) {
+                return { error: `Error amending order: ${friendlyTradeError(error.message)}` };
+            }
+        }
+        case 'alpha_propose_match': {
+            const { marketAppId, makerEscrowAppId, makerAddress, quantityMatched } = args;
+            try {
+                const client = await createTradingClient(network);
+                const result = await client.proposeMatch({
+                    marketAppId,
+                    makerEscrowAppId,
+                    makerAddress,
+                    quantityMatched,
+                });
+                const success = result.success !== false;
+                return {
+                    type: 'match',
+                    success,
+                    marketAppId,
+                    makerEscrowAppId,
+                    makerAddress,
+                    quantityMatched: formatQty(quantityMatched),
+                    txIds: result.txIds ?? [],
+                    confirmedRound: result.confirmedRound ?? 0,
+                };
+            }
+            catch (error) {
+                return { error: `Error proposing match: ${error.message || 'Unknown error'}` };
+            }
+        }
+        default:
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown Alpha trading tool: ${name}`);
+    }
+}

package/dist/tools/apiManager/index.js

@@ -6,6 +6,7 @@ import { tinymanTools, handleTinymanTools } from './tinyman/index.js';
 // import { ultradeTools, handleUltradeTools } from './ultrade/index.js';
 import { haystackTools, handleHaystackTools } from './hayrouter/index.js';
 import { peraTools, handlePeraTools } from './pera/index.js';
+import { alphaTools, handleAlphaTools } from './alpha/index.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import { ResponseProcessor } from '../../utils/responseProcessor.js';
 // Combine all API tools
@@ -15,7 +16,8 @@ export const apiManager = [
     ...nfdTools,
     ...tinymanTools,
     ...haystackTools,
-    ...peraTools
+    ...peraTools,
+    ...alphaTools
 ];
 // Handle all API tools
 export async function handleApiManager(name, args) {
@@ -45,6 +47,10 @@ export async function handleApiManager(name, args) {
         else if (name.startsWith('api_pera_')) {
             response = await handlePeraTools(name, args);
         }
+        // Alpha Arcade tools
+        else if (name.startsWith('alpha_')) {
+            response = await handleAlphaTools(name, args);
+        }
         else {
             throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
         }

package/dist/tools/utilityManager.js

@@ -86,7 +86,7 @@ export class UtilityManager {
                                 type: 'text',
                                 text: JSON.stringify({
                                     name: 'Algorand MCP Server',
-                                    version: '3.7.0',
+                                    version: '3.9.0',
                                     builder: 'GoPlausible',
                                     description: 'A Model Context Protocol (MCP) server providing comprehensive access to the Algorand blockchain. Supports account management, transaction building and signing, smart contract interaction, asset operations, ARC-26 URI generation, and deep integration with Algorand ecosystem services including NFDomains, Tinyman, Vestige, and Ultrade.',
                                     blockchain: 'Algorand — a carbon-negative, pure proof-of-stake Layer 1 blockchain delivering instant finality, low fees, and advanced smart contract capabilities via AVM (Algorand Virtual Machine).',
@@ -102,6 +102,7 @@ export class UtilityManager {
                                         'Tinyman DEX integration',
                                         'Vestige analytics integration',
                                         'Ultrade orderbook DEX integration',
+                                        'Alpha Arcade prediction market integration',
                                     ],
                                     links: {
                                         repository: 'https://github.com/GoPlausible/algorand-mcp',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplausible/algorand-mcp",
-  "version": "3.7.0",
+  "version": "3.9.0",
   "publishConfig": {
     "access": "public"
   },
@@ -42,13 +42,14 @@
     "typescript": "^5.0.0"
   },
   "dependencies": {
+    "@alpha-arcade/sdk": "latest",
     "@cf-wasm/photon": "^0.1.31",
     "@juit/qrcode": "^1.0.59",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@napi-rs/keyring": "^1.2.0",
     "@noble/curves": "^2.0.1",
     "@tinymanorg/tinyman-js-sdk": "^5.1.2",
-    "@txnlab/haystack-router":"^2.0.5",
+    "@txnlab/haystack-router": "^2.0.5",
     "algo-msgpack-with-bigint": "^2.1.1",
     "algosdk": "^3.5.2",
     "hi-base32": "^0.5.1",
@@ -57,4 +58,4 @@
     "sql.js": "^1.14.0",
     "zod": "^3.25.61"
   }
-}
+}