| name | alpha-arcade-interaction |
| description | Trade on Alpha Arcade prediction markets on Algorand via Algorand MCP tools — browse markets, read orderbooks, place limit/market orders, manage positions, cancel/amend orders, split/merge shares, and claim winnings. Use when user asks about prediction markets, event betting, YES/NO shares, orderbooks, or Alpha Arcade. |
Alpha Arcade — Prediction Markets on Algorand
Interact with Alpha Arcade prediction markets via the Algorand MCP server (15 tools across read-only and trading categories). All operations use the Algorand MCP wallet for signing; no separate mnemonic needed.
Key Characteristics
- On-chain prediction markets — all orders and settlements happen on Algorand
- Binary and multi-choice markets — bet on YES/NO outcomes or choose from multiple options
- USDC-denominated — all collateral and payouts in USDC (ASA 31566704)
- Microunit inputs — all prices and quantities in tool inputs use microunits (1,000,000 = $1.00 or 1 share)
- Formatted outputs — read tools return human-readable strings like "$0.50" and "2.50 shares"
Setup
Alpha Arcade tools are built into the Algorand MCP server. Load them via ToolSearch before use:
ToolSearch("+alpha") # Load all Alpha Arcade tools
ToolSearch("select:mcp__algorand-mcp__alpha_get_live_markets") # Load a specific tool
Trading uses the local agent wallet (SQLite-backed at ~/.algorand-mcp/wallet.db) — no separate mnemonic needed.
Read-only tools work without a wallet. Trading tools require an active wallet account (see wallet_get_info and wallet_add_account).
Units & Price Format
All prices and quantities in tool inputs use microunits: 1,000,000 = $1.00 or 1 share.
| Human value | Microunit value |
|---|
| $0.50 | 500,000 |
| $0.05 slippage | 50,000 |
| 1 share | 1,000,000 |
| 30 shares | 30,000,000 |
Tool outputs from read tools (get_orderbook, get_open_orders, get_positions) return pre-formatted strings. Write tools accept raw microunit integers.
API probability fields are microunits, NOT percentages
Critical: The yesProb and noProb fields returned by market data (e.g., get_market, get_live_markets) are in microunits (0–1,000,000), NOT percentages (0–100).
yesProb value | Meaning | Display price |
|---|
| 862,500 | 86.25% chance | $0.86 |
| 500,000 | 50% chance | $0.50 |
| 50,000 | 5% chance | $0.05 |
To convert for display: price = yesProb / 1,000,000 → e.g., 862500 / 1000000 = $0.86
Do NOT divide by 100 or treat as a percentage — this produces values like 8,625,000,000 which overflow uint64 and cause transaction failures.
Market Data Model
Binary markets
A standard yes/no market has a single marketAppId, yesAssetId, and noAssetId. Use marketAppId for all trading calls.
Multi-choice markets
Multi-choice markets (e.g., "Who wins the election?") have an options[] array. Each option is its own binary market with its own marketAppId:
{
"title": "Presidential Election Winner 2028",
"options": [
{ "title": "Candidate A", "marketAppId": 100001, "yesAssetId": 111, "noAssetId": 112 },
{ "title": "Candidate B", "marketAppId": 100002, "yesAssetId": 113, "noAssetId": 114 }
]
}
Always trade using the option's marketAppId, not the parent.
Orderbook Mechanics
Four-sided book
The orderbook has four sides: YES bids, YES asks, NO bids, NO asks.
Cross-side equivalence
Because YES + NO always = $1.00:
- A YES bid at $0.30 is equivalent to a NO ask at $0.70
- A NO bid at $0.71 is equivalent to a YES ask at $0.29
The get_orderbook tool returns a unified YES-perspective view that merges all 4 sides automatically.
Limit vs market orders
- Limit order (
alpha_create_limit_order): Sits on the orderbook at your exact price. No matching happens. Appears in get_open_orders as an unfilled order until matched or cancelled.
- Market order (
alpha_create_market_order): Auto-matches against existing orders within your slippage tolerance. Returns the actual fill price. Filled immediately — does NOT appear in open orders.
Positions vs open orders
- Positions (
alpha_get_positions): YES/NO token balances the wallet holds. These come from filled market orders, split shares, or received transfers. Positions represent ownership of outcome tokens.
- Open orders (
alpha_get_open_orders): Unfilled limit orders sitting on the orderbook. Each has an escrowAppId that can be used to cancel or amend.
A common mistake is checking only open orders after a market order — market orders fill immediately and become positions, not open orders. Always check both.
Collateral
Every order requires both ALGO and USDC/tokens:
- ALGO: ~0.957 ALGO locked per order as minimum balance requirement (MBR) for the on-chain escrow. Refunded on cancel or fill.
- Buy orders: Lock USDC as trade collateral (proportional to quantity × price).
- Sell orders: Lock outcome tokens (YES or NO) as collateral.
If a trade fails with an "overspend" error, the wallet lacks sufficient ALGO or USDC. Check both balances before retrying.
Algorand MCP Alpha Arcade Tools
Read-only tools (no wallet required)
| Tool | Purpose |
|---|
alpha_get_live_markets | Fetch all live markets with prices, volume, categories |
alpha_get_reward_markets | Fetch markets with liquidity rewards (requires ALPHA_API_KEY) |
alpha_get_market | Fetch full details for a single market by ID |
alpha_get_orderbook | Fetch unified YES-perspective orderbook for a market |
alpha_get_open_orders | Fetch all open orders for a wallet on a specific market |
alpha_get_positions | Fetch all YES/NO token positions for a wallet across all markets |
Trading tools (require active wallet account)
| Tool | Purpose |
|---|
alpha_create_limit_order | Place a limit order at a specific price |
alpha_create_market_order | Place a market order with auto-matching and slippage |
alpha_cancel_order | Cancel an open order (refunds collateral) |
alpha_amend_order | Edit an existing unfilled order in-place |
alpha_propose_match | Propose a match between a maker order and your wallet |
alpha_split_shares | Split USDC into equal YES + NO tokens |
alpha_merge_shares | Merge equal YES + NO tokens back into USDC |
alpha_claim | Claim USDC from a resolved market |
Key Workflows
Buying shares
Step 1: Check wallet
→ wallet_get_info { network }
Step 2: Browse markets
→ alpha_get_live_markets { network }
(or alpha_get_reward_markets for markets with liquidity rewards)
Step 3: Check liquidity
→ alpha_get_orderbook { marketAppId, network }
Step 4: Place order
→ alpha_create_market_order { marketAppId, side, quantity, maxPrice, network }
(auto-matches) or
→ alpha_create_limit_order { marketAppId, side, quantity, price, network }
(rests on book)
Step 5: Save the returned escrowAppId — needed to cancel or amend
Step 6: Present transaction link
→ Show any returned txIds as clickable explorer links:
Mainnet: https://allo.info/tx/{txId}
Testnet: https://lora.algokit.io/testnet/transaction/{txId}
Checking your portfolio
Step 1: Check positions (filled orders / token balances)
→ alpha_get_positions { network }
Step 2: Check open orders on a specific market
→ alpha_get_open_orders { marketAppId, network }
Editing an order (amend)
Step 1: Find the escrowAppId
→ alpha_get_open_orders { marketAppId, network }
Step 2: Amend the order
→ alpha_amend_order { marketAppId, escrowAppId, price, quantity, network }
(faster and cheaper than cancel + recreate — only works on unfilled orders)
Cancelling an order
Step 1: Find the escrowAppId and owner
→ alpha_get_open_orders { marketAppId, network }
Step 2: Cancel
→ alpha_cancel_order { marketAppId, escrowAppId, orderOwner, network }
Claiming from a resolved market
Step 1: Find markets with token balances
→ alpha_get_positions { network }
(note the yesAssetId or noAssetId)
Step 2: Claim
→ alpha_claim { marketAppId, assetId, network }
Providing liquidity (split/merge)
Step 1: Split USDC into YES + NO tokens
→ alpha_split_shares { marketAppId, quantity, network }
Step 2: Place limit orders on both sides for market making
Step 3: Merge matched tokens back to USDC
→ alpha_merge_shares { marketAppId, quantity, network }
Post-transaction display: After any Alpha Arcade trading operation that returns transaction IDs (alpha_create_market_order, alpha_create_limit_order, alpha_cancel_order, alpha_split_shares, alpha_merge_shares, alpha_claim), always present the txIds as clickable explorer links. Mainnet: https://allo.info/tx/{txId}. Testnet: https://lora.algokit.io/testnet/transaction/{txId}.
Common Pitfalls
- Probabilities are microunits, NOT percentages:
yesProb / noProb range from 0–1,000,000 (not 0–100). Treating them as percentages causes uint64 overflow and transaction failures. To display: divide by 1,000,000. To pass as price: use as-is.
- Market orders become positions, not open orders: After a market order fills, check
alpha_get_positions for token balances — not alpha_get_open_orders. Open orders only shows unfilled limit orders.
- Multi-choice markets: The parent has no
marketAppId for trading. Use options[].marketAppId.
- Prices are microunits in inputs: $0.50 = 500,000, not 0.5 or 50.
- Both ALGO and USDC needed: Orders require ALGO for MBR (~0.957 per order) AND USDC for buy collateral. An "overspend" error means one of these is insufficient.
- Orderbook cross-side: If you only check YES asks, you miss cheaper liquidity from NO bids. The
alpha_get_orderbook tool handles this automatically.
- Save escrowAppId: It's the only way to cancel or amend your order later.
- USDC opt-in: The wallet must be opted into USDC (ASA 31566704) before trading.
- Wallet required for trading: Read-only tools work without a wallet, but trading tools require an active wallet account. Check via
wallet_get_info and if no wallet exists, add one using wallet_add_account.
- Testnet by default — confirm before mainnet: The MCP server now defaults to
testnet. Always pass network: "mainnet" explicitly when the user wants to trade with real funds, and confirm with them first — real money is at stake on mainnet.
Links
