@goplausible/openclaw-algorand-plugin 1.0.2 → 1.2.0

package/skills/haystack-router-interaction/references/node-automation.md

@@ -0,0 +1,51 @@
+# Node.js Automation (Algorand MCP)
+
+Automate swaps using Algorand MCP tools. The `api_haystack_execute_swap` tool handles quoting, signing, and submission in one call.
+
+## Single Swap
+
+```
+1. wallet_get_info { network: "testnet" }
+   → Get address and confirm ALGO balance is sufficient
+
+2. api_haystack_needs_optin { address, assetId: 31566704, network: "testnet" }
+   → Check if output asset needs opt-in
+
+3. (If needsOptIn) wallet_optin_asset { assetId: 31566704, network: "testnet" }
+   → Opt into output asset
+
+4. api_haystack_get_swap_quote {
+     fromASAID: 0, toASAID: 31566704, amount: 1000000,
+     address: "<wallet_address>", network: "testnet"
+   }
+   → Preview quote → confirm with user
+
+5. api_haystack_execute_swap {
+     fromASAID: 0, toASAID: 31566704, amount: 1000000,
+     slippage: 1, note: "order-123", network: "testnet"
+   }
+   → Signs via wallet, submits, waits for confirmation
+   → Returns: confirmedRound, txIds, summary with exact amounts
+```
+
+## Batch Swaps
+
+For multiple sequential swaps, repeat steps 4–5 for each pair:
+
+```
+Swap pairs example:
+  - 0 → 31566704, amount: 1000000   (1 ALGO → USDC)
+  - 0 → 312769,   amount: 2000000   (2 ALGO → USDt)
+
+For each pair:
+  → api_haystack_get_swap_quote { ... }  → show user
+  → api_haystack_execute_swap { ... }    → execute after confirmation
+```
+
+## Key Rules
+
+- **Use `api_haystack_execute_swap`** — it handles signing via the active wallet
+- **Always confirm each swap with the user** before executing
+- **Each execute call gets a fresh quote** — no stale quote issues
+- **Check opt-in** before first swap to a new ASA using `api_haystack_needs_optin`
+- **Default to testnet** unless user explicitly requests mainnet

package/skills/haystack-router-interaction/references/quotes.md

@@ -0,0 +1,80 @@
+# Quotes
+
+## Getting a Quote
+
+```
+→ api_haystack_get_swap_quote {
+    fromASAID: 0,           // ALGO
+    toASAID: 31566704,      // USDC
+    amount: 1000000,        // 1 ALGO in base units
+    type: "fixed-input",    // or "fixed-output"
+    address: "<wallet_address>",  // optional, for opt-in detection
+    network: "mainnet"
+  }
+
+Response includes:
+  - expectedOutput: output amount in base units
+  - inputAmount: original input amount
+  - usdIn / usdOut: USD values
+  - userPriceImpact: price impact percentage
+  - route: detailed routing path
+  - flattenedRoute: protocol split percentages (e.g., "TinymanV2: 60%", "Pact: 40%")
+  - requiredAppOptIns: app IDs needing opt-in
+  - protocolFees: fee breakdown
+```
+
+## Parameters
+
+| Parameter      | Type     | Required | Description                                     |
+| -------------- | -------- | -------- | ----------------------------------------------- |
+| `fromASAID`    | `number` | Yes      | Input asset ID (0 = ALGO)                       |
+| `toASAID`      | `number` | Yes      | Output asset ID                                 |
+| `amount`       | `number` | Yes      | Amount in base units                            |
+| `type`         | `string` | No       | `"fixed-input"` (default) or `"fixed-output"`   |
+| `address`      | `string` | No       | User address (for opt-in detection)             |
+| `maxGroupSize` | `number` | No       | Max transactions in group (default: 16)         |
+| `maxDepth`     | `number` | No       | Max routing hops (default: 4)                   |
+| `network`      | `string` | No       | `"mainnet"` (default) or `"testnet"`            |
+
+## Quote Types
+
+**Fixed-input** (default): Specify exact input amount, receive variable output.
+
+```
+→ api_haystack_get_swap_quote {
+    fromASAID: 0, toASAID: 31566704,
+    amount: 1000000,        // Exact: send 1 ALGO
+    type: "fixed-input", network: "mainnet"
+  }
+// expectedOutput = USDC to receive
+```
+
+**Fixed-output**: Specify desired output, send variable input.
+
+```
+→ api_haystack_get_swap_quote {
+    fromASAID: 0, toASAID: 31566704,
+    amount: 1000000,        // Exact: receive 1 USDC
+    type: "fixed-output", network: "mainnet"
+  }
+// inputAmount = ALGO required to send
+```
+
+## Asset Opt-In Detection
+
+Use the dedicated `api_haystack_needs_optin` tool to check:
+
+```
+1. api_haystack_needs_optin { address: "<address>", assetId: <toASAID>, network }
+   → Returns { needsOptIn: true/false }
+
+2. If needsOptIn is true:
+   → wallet_optin_asset { assetId: <toASAID>, network }
+   → This handles build, sign, and submit in one step
+
+3. Then proceed with quote or execute:
+   → api_haystack_get_swap_quote { fromASAID, toASAID, amount, address, network }
+   → api_haystack_execute_swap { fromASAID, toASAID, amount, slippage, network }
+```
+
+Note: `api_haystack_execute_swap` automatically handles opt-in detection when the RouterClient is configured with `autoOptIn: true` (default for Algorand MCP tools).

package/skills/haystack-router-interaction/references/swaps.md

@@ -0,0 +1,84 @@
+# Swaps
+
+The `api_haystack_execute_swap` tool handles the entire swap lifecycle: quoting, signing (via active wallet), submission, and confirmation — all in one call. **No manual signing or transaction assembly needed.**
+
+## Quick Swap (Single Tool)
+
+```
+→ api_haystack_execute_swap {
+    fromASAID: 0,             // ALGO
+    toASAID: 31566704,        // USDC
+    amount: 1000000,          // 1 ALGO in base units
+    slippage: 1,              // 1% tolerance
+    network: "mainnet"
+  }
+
+Returns:
+  status: "confirmed"
+  confirmedRound: "12345678"
+  txIds: ["TXID1...", "TXID2...", ...]
+  signer: "<wallet_address>"
+  nickname: "<account_nickname>"
+  quote: { expectedOutput, usdIn, usdOut, userPriceImpact, route }
+  summary: { inputAmount, outputAmount, totalFees, transactionCount }
+```
+
+## Complete Workflow (with preview)
+
+For best UX, preview the quote before executing:
+
+```
+1. Check wallet state
+   → wallet_get_info { network: "mainnet" }
+   → Note the address and ALGO balance
+
+2. Check output asset opt-in (skip for ALGO)
+   → api_haystack_needs_optin { address, assetId: 31566704, network: "mainnet" }
+   → If needsOptIn is true:
+     → wallet_optin_asset { assetId: 31566704, network: "mainnet" }
+
+3. Preview quote (show user before executing)
+   → api_haystack_get_swap_quote {
+       fromASAID: 0, toASAID: 31566704, amount: 1000000,
+       address: "<wallet_address>", network: "mainnet"
+     }
+   → Present to user: expected output, USD values, route, price impact
+
+4. User confirms → Execute (all-in-one)
+   → api_haystack_execute_swap {
+       fromASAID: 0, toASAID: 31566704, amount: 1000000,
+       slippage: 1, network: "mainnet"
+     }
+   → Returns confirmed result with exact summary
+```
+
+## Important Rules
+
+- **Always check wallet first** — Use `wallet_get_info` to confirm address, balance, and network
+- **Always confirm with user** — Show quote details and ask for confirmation before executing
+- **Use `api_haystack_execute_swap`** — It handles signing via the active wallet account
+- **Check opt-in for ASAs** — Use `api_haystack_needs_optin` + `wallet_optin_asset` if needed
+- **Default to testnet** — Unless user explicitly requests mainnet
+- **Handle quote staleness** — Quotes are time-sensitive; execute promptly after user confirms
+
+## Slippage Guidance
+
+| Pair Type         | Recommended Slippage |
+| ----------------- | -------------------- |
+| Stable pairs      | 0.5–1%               |
+| Volatile pairs    | 1–3%                 |
+| Low liquidity     | 3–5%                 |
+
+Slippage is verified on the **final output** of the swap, not individual hops.
+
+## Error Handling
+
+Common errors:
+
+- **Slippage exceeded** — price moved beyond tolerance, refetch quote
+- **Insufficient balance** — check with `wallet_get_info`
+- **Asset not opted in** — use `wallet_optin_asset`
+- **Transaction rejected** — user declined or signing failed
+- **Network timeout** — retry after brief delay
+
+Quotes are time-sensitive. If a quote is stale (prices moved significantly), refetch before executing.