| name | alpha-arcade-interaction |
| description | Trade on Alpha Arcade prediction markets on Algorand — 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 Alpha Arcade MCP server (15 tools across read-only and trading categories).
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. Trading uses the MCP-managed local wallet — 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 (
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 (
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 (
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 (
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.
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
get_live_markets — find a market (or get_reward_markets for markets with liquidity rewards)get_orderbook — check available liquiditycreate_market_order (auto-matches) or create_limit_order (rests on book)- Save the returned
escrowAppId — you need it to cancel
- Present txID — show transaction ID with explorer link (see Post-Transaction below)
Checking your portfolio
get_positions — see all YES/NO token balances with market titles and asset IDs- For open orders on a specific market:
get_open_orders with the marketAppId
Editing an order (amend)
get_open_orders — find the escrowAppIdamend_order with marketAppId, escrowAppId, new price, and new quantity- Faster and cheaper than cancel + recreate. Only works on unfilled orders.
Cancelling an order
get_open_orders — find the escrowAppId and owner addresscancel_order with marketAppId, escrowAppId, and orderOwner- Present txID — show transaction ID with explorer link
Claiming from a resolved market
get_positions — find markets with token balances; note the yesAssetId or noAssetIdclaim with marketAppId and the winning token's assetId- Present txID — show transaction ID with explorer link
Providing liquidity (split/merge)
split_shares — convert USDC into equal YES + NO tokens- Place limit orders on both sides of the book for market making
merge_shares — convert matched YES + NO tokens back to USDC- Present txIDs — show transaction IDs with explorer links for each operation
Post-Transaction: Deliver Transaction ID
ALWAYS present the transaction ID to the user after any successful trading operation (orders, cancellations, amendments, claims, splits, merges). Use the correct explorer link based on the network:
| Network | Explorer Link Template |
|---|
mainnet | https://allo.info/tx/{txId} |
testnet | https://lora.algokit.io/testnet/transaction/{txId} |
This applies to all Alpha Arcade trading tools: create_market_order, create_limit_order, cancel_order, amend_order, propose_match, split_shares, merge_shares, and claim.
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
get_positions for token balances — not 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
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 existed, add one using wallet_add_account.
- Testnet by default (algorand-mcp 4.2.5+): the server defaults to testnet. Mainnet trading involves real money — pass
network: "mainnet" only when the user has explicitly asked to trade on mainnet, and confirm the full order (market, side, price, size, USDC collateral) before submission.
Links
