@goplausible/openclaw-algorand-plugin 1.1.0 → 1.2.0

package/skills/haystack-router-development/references/react-integration.md

@@ -0,0 +1,260 @@
+# React Integration
+
+## Setup
+
+Install dependencies:
+
+```bash
+npm install @txnlab/haystack-router @txnlab/use-wallet-react algosdk
+```
+
+Wrap your app with `WalletProvider`:
+
+```tsx
+import { WalletProvider, WalletId } from '@txnlab/use-wallet-react'
+
+const walletProviders = [
+  { id: WalletId.PERA },
+  { id: WalletId.DEFLY },
+  { id: WalletId.LUTE },
+]
+
+function App() {
+  return (
+    <WalletProvider wallets={walletProviders}>
+      <SwapInterface />
+    </WalletProvider>
+  )
+}
+```
+
+## Basic Swap Component
+
+```tsx
+import { useState } from 'react'
+import { useWallet } from '@txnlab/use-wallet-react'
+import { RouterClient, type SwapQuote } from '@txnlab/haystack-router'
+
+function SwapInterface() {
+  const { activeAddress, transactionSigner } = useWallet()
+  const [amount, setAmount] = useState('')
+  const [fromAsset, setFromAsset] = useState(0) // ALGO
+  const [toAsset, setToAsset] = useState(31566704) // USDC
+  const [slippage, setSlippage] = useState('1')
+  const [quote, setQuote] = useState<SwapQuote | null>(null)
+
+  const getQuote = async () => {
+    const router = new RouterClient({
+      apiKey: import.meta.env.VITE_HAYSTACK_API_KEY,
+      autoOptIn: true,
+    })
+
+    const amountInBaseUnits = BigInt(Math.floor(parseFloat(amount) * 1_000_000))
+
+    const result = await router.newQuote({
+      fromASAID: fromAsset,
+      toASAID: toAsset,
+      amount: amountInBaseUnits,
+      address: activeAddress!,
+    })
+
+    setQuote(result)
+  }
+
+  const executeSwap = async () => {
+    if (!quote || !activeAddress) return
+
+    const router = new RouterClient({
+      apiKey: import.meta.env.VITE_HAYSTACK_API_KEY,
+      autoOptIn: true,
+    })
+
+    const swap = await router.newSwap({
+      quote,
+      address: activeAddress,
+      signer: transactionSigner,
+      slippage: parseFloat(slippage),
+    })
+
+    const result = await swap.execute()
+    console.log(`Confirmed in round ${result.confirmedRound}`)
+
+    setQuote(null) // Clear stale quote
+  }
+
+  return (
+    <div>
+      <input
+        type="number"
+        value={amount}
+        onChange={(e) => setAmount(e.target.value)}
+        placeholder="Amount"
+      />
+      <button onClick={getQuote} disabled={!activeAddress || !amount}>
+        Get Quote
+      </button>
+
+      {quote && (
+        <div>
+          <p>Output: {(Number(quote.quote) / 1e6).toFixed(4)} USDC</p>
+          <p>USD value: ${quote.usdOut.toFixed(2)}</p>
+          <p>
+            Route:{' '}
+            {Object.entries(quote.flattenedRoute)
+              .map(([protocol, pct]) => `${protocol}: ${pct}%`)
+              .join(', ')}
+          </p>
+          <button onClick={executeSwap}>Execute Swap</button>
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+## TanStack Query Integration
+
+For production UIs, use TanStack Query for auto-refreshing quotes and better state management.
+
+```bash
+npm install @tanstack/react-query
+```
+
+```tsx
+import { useState, useEffect, useMemo } from 'react'
+import {
+  useQuery,
+  useMutation,
+  QueryClient,
+  QueryClientProvider,
+} from '@tanstack/react-query'
+import { useWallet } from '@txnlab/use-wallet-react'
+import { RouterClient, type SwapQuote } from '@txnlab/haystack-router'
+
+const queryClient = new QueryClient()
+
+function SwapWithAutoRefresh() {
+  const { activeAddress, transactionSigner } = useWallet()
+  const [amount, setAmount] = useState('')
+  const [debouncedAmount, setDebouncedAmount] = useState('')
+  const [fromAsset] = useState(0)
+  const [toAsset] = useState(31566704)
+  const [slippage] = useState(1)
+
+  // Debounce amount input (500ms)
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedAmount(amount), 500)
+    return () => clearTimeout(timer)
+  }, [amount])
+
+  const router = useMemo(
+    () =>
+      new RouterClient({
+        apiKey: import.meta.env.VITE_HAYSTACK_API_KEY,
+        autoOptIn: true,
+      }),
+    [],
+  )
+
+  const isValidRequest =
+    activeAddress && debouncedAmount && parseFloat(debouncedAmount) > 0
+
+  // Auto-fetch and refresh quotes
+  const {
+    data: quote,
+    error,
+    isLoading,
+  } = useQuery({
+    queryKey: ['quote', fromAsset, toAsset, debouncedAmount, activeAddress],
+    queryFn: () =>
+      router.newQuote({
+        fromASAID: fromAsset,
+        toASAID: toAsset,
+        amount: BigInt(Math.floor(parseFloat(debouncedAmount) * 1_000_000)),
+        address: activeAddress!,
+      }),
+    enabled: !!isValidRequest,
+    refetchInterval: 15_000, // Refresh every 15 seconds
+    retry: 1,
+  })
+
+  // Swap mutation
+  const swapMutation = useMutation({
+    mutationFn: async () => {
+      if (!quote || !activeAddress) throw new Error('Missing quote or address')
+
+      const swap = await router.newSwap({
+        quote,
+        address: activeAddress,
+        signer: transactionSigner,
+        slippage,
+      })
+      return swap.execute()
+    },
+    onSuccess: (result) => {
+      console.log(`Confirmed in round ${result.confirmedRound}`)
+      queryClient.invalidateQueries({ queryKey: ['quote'] })
+    },
+  })
+
+  return (
+    <div>
+      <input
+        type="number"
+        value={amount}
+        onChange={(e) => setAmount(e.target.value)}
+        placeholder="Amount"
+      />
+
+      {isLoading && <p>Fetching quote...</p>}
+      {error && <p>Error: {(error as Error).message}</p>}
+
+      {quote && (
+        <div>
+          <p>Output: {(Number(quote.quote) / 1e6).toFixed(4)} USDC</p>
+          <p>USD: ${quote.usdOut.toFixed(2)}</p>
+          <button
+            onClick={() => swapMutation.mutate()}
+            disabled={swapMutation.isPending}
+          >
+            {swapMutation.isPending ? 'Swapping...' : 'Swap'}
+          </button>
+        </div>
+      )}
+    </div>
+  )
+}
+```
+
+Key patterns:
+
+- **Debounced input**: Prevent quote requests on every keystroke
+- **Auto-refresh**: `refetchInterval: 15_000` keeps quotes current
+- **Invalidation**: Clear stale quotes after a successful swap
+- **Loading/error states**: TanStack Query manages all async state
+
+## Displaying Route Details
+
+```tsx
+function RouteDisplay({ quote }: { quote: SwapQuote }) {
+  return (
+    <div>
+      <h4>Route</h4>
+      {quote.route.map((route, i) => (
+        <div key={i}>
+          <strong>{route.percentage}%</strong>
+          {route.path.map((hop, j) => (
+            <span key={j}>
+              {j > 0 && ' → '}
+              {hop.in.unit_name} → {hop.out.unit_name} ({hop.name})
+            </span>
+          ))}
+        </div>
+      ))}
+      {quote.userPriceImpact !== undefined && (
+        <p>Price impact: {quote.userPriceImpact.toFixed(2)}%</p>
+      )}
+    </div>
+  )
+}
+```

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 |