@goplausible/openclaw-algorand-plugin 1.1.0 → 1.3.0

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

@@ -0,0 +1,161 @@
+# Swaps
+
+## Executing a Swap
+
+```typescript
+import { RouterClient } from '@txnlab/haystack-router'
+
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+})
+
+// 1. Get a quote
+const quote = await router.newQuote({
+  fromASAID: 0,
+  toASAID: 31566704,
+  amount: 1_000_000,
+  address: activeAddress,
+})
+
+// 2. Create and execute swap
+const swap = await router.newSwap({
+  quote,
+  address: activeAddress,
+  signer: transactionSigner,
+  slippage: 1, // 1%
+})
+
+const result = await swap.execute()
+console.log(`Confirmed in round ${result.confirmedRound}`)
+```
+
+## newSwap() Parameters
+
+| Parameter  | Type                                  | Required | Description                               |
+| ---------- | ------------------------------------- | -------- | ----------------------------------------- |
+| `quote`    | `SwapQuote \| FetchQuoteResponse`     | Yes      | Quote from `newQuote()` or `fetchQuote()` |
+| `address`  | `string`                              | Yes      | Signer's Algorand address                 |
+| `signer`   | `TransactionSigner \| SignerFunction` | Yes      | Transaction signing function              |
+| `slippage` | `number`                              | Yes      | Slippage tolerance (e.g., `1` = 1%)       |
+| `note`     | `Uint8Array`                          | No       | Note attached to input transaction        |
+
+## Signer Patterns
+
+### Browser: use-wallet
+
+```typescript
+import { useWallet } from '@txnlab/use-wallet-react'
+
+const { activeAddress, transactionSigner } = useWallet()
+
+const swap = await router.newSwap({
+  quote,
+  address: activeAddress,
+  signer: transactionSigner,
+  slippage: 1,
+})
+```
+
+The SDK supports two signer return patterns:
+
+- **Pera/Defly style**: Returns `Uint8Array[]` matching `indexesToSign` length
+- **Lute/ARC-1 style**: Returns `(Uint8Array | null)[]` matching full group length, `null` for unsigned
+
+Both are detected and handled automatically.
+
+## 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. This means intermediate steps can have higher variance as long as the final result is within tolerance.
+
+## Execution Result
+
+```typescript
+const result = await swap.execute()
+
+result.confirmedRound // bigint — block where swap confirmed
+result.txIds // string[] — all transaction IDs
+result.methodResults // ABIResult[] — ABI method call results
+```
+
+## Swap Summary
+
+After execution, get exact amounts (may differ from quote due to slippage):
+
+```typescript
+const result = await swap.execute()
+const summary = swap.getSummary()
+
+if (summary) {
+  summary.inputAssetId // bigint
+  summary.outputAssetId // bigint
+  summary.inputAmount // bigint — exact input sent
+  summary.outputAmount // bigint — exact output received
+  summary.totalFees // bigint — total ALGO fees (microAlgos)
+  summary.transactionCount // number
+  summary.inputTxnId // string — user-signed input txn ID
+  summary.outputTxnId // string — app call containing output
+}
+```
+
+## Advanced: Custom Transaction Composition
+
+Add custom transactions before/after the swap in the same atomic group:
+
+```typescript
+const swap = await router.newSwap({
+  quote,
+  address: activeAddress,
+  signer: transactionSigner,
+  slippage: 1,
+})
+
+const result = await swap
+  .addTransaction(customTxn) // Add before swap
+  .addSwapTransactions() // Add swap txns + middleware
+  .addMethodCall(abiCall) // Add ABI call after swap
+  .execute()
+```
+
+Constraints:
+
+- Max 16 transactions per group
+- Non-composable swaps (Tinyman v1) cannot add custom transactions
+- Call `addSwapTransactions()` to manually control ordering
+
+## Advanced: Step-by-Step Execution
+
+For more control over the signing and submission flow:
+
+```typescript
+const swap = await router.newSwap({ quote, address, signer, slippage: 1 })
+
+// Build (assigns group IDs)
+const txnsWithSigners = swap.buildGroup()
+
+// Sign
+const signedTxns = await swap.sign()
+
+// Submit (doesn't wait)
+const txIds = await swap.submit()
+
+// Check status
+swap.getStatus() // BUILDING → BUILT → SIGNED → SUBMITTED → COMMITTED
+```
+
+## Error Handling
+
+Common errors:
+
+- **Slippage exceeded** — price moved beyond tolerance, refetch quote
+- **Insufficient balance** — check account balance
+- **Asset not opted in** — include opt-in in quote or opt in manually
+- **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.

package/skills/haystack-router-interaction/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: haystack-router-interaction
+description: Route and execute optimal token swaps on Algorand using Haystack Router via Algorand MCP tools. Use when getting best-price quotes across multiple Algorand DEXes and LST protocols, executing atomic swaps, and checking asset opt-in — all through the Algorand MCP server. Strong triggers include haystack swap, best price swap, DEX aggregator swap, swap ALGO to USDC, api_haystack, haystack quote, execute swap, swap routing, optimal swap, multi-DEX swap.
+---
+
+# Haystack Router (Interaction)
+
+This is the parent skill for interacting with Haystack Router through Algorand MCP tools — getting quotes, executing swaps, and checking opt-in status. All operations use the Algorand MCP wallet for signing; no SDK installation or API keys needed.
+
+> **Building an application** that integrates Haystack Router directly? Use the **haystack-router-development** skill instead — it covers the `@txnlab/haystack-router` SDK, React integration, Node.js automation, middleware, and the full API surface.
+> **Need general wallet/transaction guidance?** See the **algorand-interaction** skill for wallet setup, session start checklist, network selection, and pre-transaction validation.
+
+Haystack Router is a DEX aggregator and smart order routing protocol on Algorand. It finds optimal swap routes across multiple DEXes (Tinyman V2, Pact, Folks) and LST protocols (tALGO, xALGO), then executes them atomically through on-chain smart contracts.
+
+## mcporter Syntax (OpenClaw CLI)
+
+When calling Haystack Router MCP tools via mcporter in OpenClaw CLI:
+
+```bash
+mcporter call algorand-mcp.api_haystack_get_swap_quote --args '{"fromASAID": 0, "toASAID": 31566704, "amount": 1000000, "network": "mainnet"}'
+```
+
+Key: use `server.tool` (dot notation) with `--args '{"json"}'`. See `algorand-interaction` skill for full mcporter reference.
+
+## Network Selection
+
+Every Haystack Router tool accepts a `network` parameter:
+
+| Value | Description |
+|-------|-------------|
+| `mainnet` | Algorand mainnet (default) — **real value, exercise caution** |
+| `testnet` | Algorand testnet — safe for development |
+
+Default to `testnet` during development. Always confirm with the user before mainnet swaps.
+
+## Algorand MCP Haystack Router Tools
+
+Three dedicated Algorand MCP tools provide full Haystack Router functionality. These handle quoting, execution (with wallet signing), and opt-in checking — no raw mnemonics or secret keys needed.
+
+### `api_haystack_get_swap_quote`
+
+Get an optimized swap quote without executing. Use to preview pricing, route, and price impact before confirming with user.
+
+```
+→ api_haystack_get_swap_quote {
+    fromASAID: 0,             // Input asset (0 = ALGO)
+    toASAID: 31566704,        // Output asset (USDC)
+    amount: 1000000,          // 1 ALGO in base units
+    type: "fixed-input",      // or "fixed-output"
+    address: "<address>",     // optional, for opt-in detection
+    maxGroupSize: 16,         // optional
+    maxDepth: 4,              // optional
+    network: "mainnet"
+  }
+
+Returns: expectedOutput, inputAmount, usdIn, usdOut, userPriceImpact,
+         route, flattenedRoute, requiredAppOptIns, protocolFees
+```
+
+### `api_haystack_execute_swap`
+
+All-in-one swap: quote → sign (via wallet) → submit → confirm. Uses the active wallet account for signing. Enforces wallet spending limits.
+
+```
+→ api_haystack_execute_swap {
+    fromASAID: 0,             // Input asset
+    toASAID: 31566704,        // Output asset
+    amount: 1000000,          // Amount in base units
+    slippage: 1,              // 1% slippage tolerance
+    type: "fixed-input",      // optional
+    note: "my swap",          // optional text note
+    maxGroupSize: 16,         // optional
+    maxDepth: 4,              // optional
+    network: "mainnet"
+  }
+
+Returns: status, confirmedRound, txIds, signer, nickname, quote details,
+         summary (inputAmount, outputAmount, totalFees, transactionCount)
+```
+
+### `api_haystack_needs_optin`
+
+Check if an address needs to opt into an asset before swapping.
+
+```
+→ api_haystack_needs_optin {
+    address: "<address>",
+    assetId: 31566704,
+    network: "mainnet"
+  }
+
+Returns: { address, assetId, needsOptIn: true/false, network }
+```
+
+## Algorand MCP Agent Swap Workflow
+
+```
+Step 1: Check wallet
+  → wallet_get_info { network }
+
+Step 2: Check opt-in (if swapping to an ASA)
+  → api_haystack_needs_optin { address, assetId, network }
+  → If needed: wallet_optin_asset { assetId, network }
+
+Step 3: Preview quote (recommended — show user before executing)
+  → api_haystack_get_swap_quote { fromASAID, toASAID, amount, address, network }
+  → Present to user: expected output, USD values, route, price impact
+
+Step 4: User confirms → Execute
+  → api_haystack_execute_swap { fromASAID, toASAID, amount, slippage, network }
+  → Returns confirmed result with summary
+```
+
+**Key rules:**
+- Always check wallet with `wallet_get_info` before any swap
+- Always confirm with the user before executing (show quote details)
+- The execute tool handles signing via the active wallet — no manual signing needed
+- Default to testnet during development; confirm before mainnet
+- Quotes are time-sensitive — execute promptly after user confirms
+
+## Key Concepts
+
+- **Amounts** are always in base units (microAlgos for ALGO, smallest unit for ASAs)
+- **ASA IDs**: 0 = ALGO, 31566704 = USDC, etc.
+- **Quote types**: `fixed-input` (default) — specify input amount; `fixed-output` — specify desired output
+- **Slippage**: Percentage tolerance on output (e.g., 1 = 1%). Applied to the final output, not individual hops
+- **Routing**: Supports multi-hop and parallel (combo) swaps for optimal pricing
+
+## Reference Files
+
+Read the appropriate file based on the task:
+
+| Task                                        | Reference                                             |
+| ------------------------------------------- | ----------------------------------------------------- |
+| Quick start and Algorand MCP tool reference | [getting-started.md](references/getting-started.md)   |
+| Get swap quotes, display pricing            | [quotes.md](references/quotes.md)                     |
+| Execute swaps via Algorand MCP tools        | [swaps.md](references/swaps.md)                       |
+| Automate swaps via Algorand MCP tools       | [node-automation.md](references/node-automation.md)   |
+| Network, slippage, rate limits, ASA IDs     | [configuration.md](references/configuration.md)       |
+
+## How to Use This Skill
+
+1. **Start here** to understand the three Haystack Router MCP tools and the swap workflow
+2. **Read the topic `.md`** file for detailed guidance on quotes, swaps, or automation
+3. **For SDK-based development** (React UIs, Node.js apps), see the `haystack-router-development` skill
+4. **For wallet setup and general blockchain interaction**, see the `algorand-interaction` skill

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

@@ -0,0 +1,53 @@
+# Configuration (Algorand MCP)
+
+## Network
+
+All Algorand MCP Haystack Router tools accept a `network` parameter:
+
+- `"mainnet"` — MainNet (default)
+- `"testnet"` — TestNet
+
+```
+→ api_haystack_get_swap_quote {
+    fromASAID: 0, toASAID: 31566704, amount: 1000000,
+    network: "testnet"
+  }
+```
+
+Default to **testnet** during development; confirm with user before using mainnet.
+
+## Slippage
+
+Set slippage (percentage tolerance on output) when executing swaps:
+
+```
+→ api_haystack_execute_swap {
+    fromASAID: 0, toASAID: 31566704, amount: 1000000,
+    slippage: 1,        // 1% — receive at least 99% of quoted output
+    network: "testnet"
+  }
+```
+
+**Recommendations:**
+
+- **Stable pairs** (ALGO/USDC): 0.5–1%
+- **Volatile pairs**: 1–3%
+- **Low liquidity**: 3–5%
+
+Slippage is verified on the **final output** of the swap, not on individual hops.
+
+## Rate Limits
+
+The Algorand MCP server uses a free tier API key (60 requests/min). This applies to all Haystack Router tool calls. Override via `HAYSTACK_API_KEY` environment variable.
+
+## Common ASA IDs
+
+| Asset | ASA ID    |
+| ----- | --------- |
+| ALGO  | 0         |
+| USDC  | 31566704  |
+| USDt  | 312769    |
+| goBTC | 386192725 |
+| goETH | 386195940 |
+
+Look up ASA IDs on [Allo.info](https://allo.info) or [Pera Explorer](https://explorer.perawallet.app/).

package/skills/haystack-router-interaction/references/getting-started.md

@@ -0,0 +1,48 @@
+# Getting Started
+
+When operating as an Algorand MCP agent, use Algorand MCP tools directly. No SDK installation or API key management needed — the Algorand MCP server handles this internally.
+
+## Quick Swap (2 steps)
+
+```
+1. wallet_get_info { network: "testnet" }
+   → Get wallet address and balance
+
+2. api_haystack_execute_swap {
+     fromASAID: 0, toASAID: 31566704, amount: 1000000,
+     slippage: 1, network: "testnet"
+   }
+   → Quotes, signs via wallet, submits, confirms — all in one call
+```
+
+## With Preview (recommended for user-facing swaps)
+
+```
+1. wallet_get_info { network: "testnet" }
+2. api_haystack_needs_optin { address, assetId: 31566704, network: "testnet" }
+   → If needed: wallet_optin_asset { assetId: 31566704, network: "testnet" }
+3. api_haystack_get_swap_quote { fromASAID: 0, toASAID: 31566704, amount: 1000000, network: "testnet" }
+   → Show user the quote → get confirmation
+4. api_haystack_execute_swap { fromASAID: 0, toASAID: 31566704, amount: 1000000, slippage: 1, network: "testnet" }
+```
+
+## Algorand MCP Tool Reference
+
+| Tool                            | Purpose                                          |
+| ------------------------------- | ------------------------------------------------ |
+| `api_haystack_get_swap_quote`   | Preview swap quote with routing and pricing       |
+| `api_haystack_execute_swap`     | Execute swap: quote + sign + submit + confirm     |
+| `api_haystack_needs_optin`      | Check if address needs asset opt-in               |
+| `wallet_get_info`               | Get wallet address and ALGO balance               |
+| `wallet_optin_asset`            | Opt into an ASA (one-step build+sign+submit)      |
+
+See [swaps.md](swaps.md) for detailed workflow and [quotes.md](quotes.md) for quote parameters.
+
+## Amounts and Units
+
+All amounts are in **base units** (smallest denomination):
+
+| Asset               | Decimals | 1 unit in base | Example              |
+| ------------------- | -------- | -------------- | -------------------- |
+| ALGO (ASA 0)        | 6        | 1,000,000      | `1_000_000` = 1 ALGO |
+| USDC (ASA 31566704) | 6        | 1,000,000      | `5_000_000` = 5 USDC |

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.