@goplausible/openclaw-algorand-plugin 1.4.0 → 1.6.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-algorand-plugin",
   "name": "Algorand Integration",
   "description": "Algorand blockchain integration with MCP and skills — by GoPlausible",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "skills": [
     "skills/algorand-development",
     "skills/algorand-typescript",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplausible/openclaw-algorand-plugin",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "publishConfig": {
     "access": "public"
   },

package/skills/algorand-interaction/SKILL.md

@@ -193,6 +193,22 @@ Map CAIP-2 network identifiers from `accepts[].network` to `testnet` or `mainnet
 
 See [references/examples-algorand-mcp.md](references/examples-algorand-mcp.md) for the full step-by-step workflow.
 
+## Alpha Arcade Prediction Markets
+
+Trade on-chain prediction markets (YES/NO outcomes) denominated in USDC via the Alpha Arcade integration (14 tools).
+
+| Step | Tool | Purpose |
+|------|------|---------|
+| 1 | `wallet_get_info` | Verify active account, check ALGO + USDC balance |
+| 2 | `alpha_get_live_markets` | Browse available markets |
+| 3 | `alpha_get_orderbook` | Check liquidity and prices for a market |
+| 4 | `alpha_create_market_order` or `alpha_create_limit_order` | Place an order |
+| 5 | `alpha_get_positions` / `alpha_get_open_orders` | Check portfolio |
+
+All prices and quantities use **microunits** (1,000,000 = $1.00 or 1 share). Orders require both ALGO (~0.957 per escrow) and USDC collateral.
+
+> For detailed Alpha Arcade workflows (orderbook mechanics, multi-choice markets, split/merge shares, claiming, collateral model), load the `alpha-arcade-interaction` skill.
+
 ## References
 
 For detailed tool documentation:

package/skills/algorand-interaction/references/algorand-mcp.md

@@ -26,12 +26,11 @@
 Secure wallet management. Private keys are never available to you — use these tools to sign.
 
 ### wallet_add_account
-- **Purpose**: Create a new Algorand account (or import from mnemonic) with nickname and spending limits
+- **Purpose**: Create a new Algorand account with nickname and spending limits
 - **Parameters**:
 ```json
 {
   "nickname": "my-account",
-  "mnemonic": "optional 25-word mnemonic to import",
   "allowance": 5000000,
   "dailyAllowance": 10000000
 }

package/skills/alpha-arcade-interaction/SKILL.md

@@ -0,0 +1,180 @@
+---
+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 local wallet (OS keychain) — no separate mnemonic needed.
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `ALPHA_API_KEY` | For reward markets | Alpha Arcade API key |
+| `ALPHA_API_BASE_URL` | No | API base URL (default: https://platform.alphaarcade.com/api) |
+
+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`:
+
+```json
+{
+  "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
+1. `get_live_markets` — find a market (or `get_reward_markets` for markets with liquidity rewards)
+2. `get_orderbook` — check available liquidity
+3. `create_market_order` (auto-matches) or `create_limit_order` (rests on book)
+4. Save the returned `escrowAppId` — you need it to cancel
+
+### Checking your portfolio
+1. `get_positions` — see all YES/NO token balances with market titles and asset IDs
+2. For open orders on a specific market: `get_open_orders` with the `marketAppId`
+
+### Editing an order (amend)
+1. `get_open_orders` — find the `escrowAppId`
+2. `amend_order` with `marketAppId`, `escrowAppId`, new `price`, and new `quantity`
+3. Faster and cheaper than cancel + recreate. Only works on unfilled orders.
+
+### Cancelling an order
+1. `get_open_orders` — find the `escrowAppId` and `owner` address
+2. `cancel_order` with `marketAppId`, `escrowAppId`, and `orderOwner`
+
+### Claiming from a resolved market
+1. `get_positions` — find markets with token balances; note the `yesAssetId` or `noAssetId`
+2. `claim` with `marketAppId` and the winning token's `assetId`
+
+### Providing liquidity (split/merge)
+1. `split_shares` — convert USDC into equal YES + NO tokens
+2. Place limit orders on both sides of the book for market making
+3. `merge_shares` — convert matched YES + NO tokens back to USDC
+
+## 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`.
+- **Mainnet by default**: The server defaults to mainnet. Real money is at stake. Pass `network: "testnet"` for testing.
+
+## Links
+
+- Alpha Arcade: https://alphaarcade.com
+- Alpha Arcade API: https://platform.alphaarcade.com