@goplausible/openclaw-algorand-plugin 1.3.0 → 1.4.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.3.0",
+  "version": "1.4.0",
   "skills": [
     "skills/algorand-development",
     "skills/algorand-typescript",

package/package.json

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

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

@@ -710,6 +710,7 @@ DEX-aggregated swaps across Tinyman V2, Pact, and Folks with smart order routing
   "network": "mainnet"
 }
 ```
+- **`type`**: `"fixed-input"` = `amount` is the input (spend exactly this much); `"fixed-output"` = `amount` is the output (receive exactly this much). See **Swap Type Rules** below.
 - **Returns**: `expectedOutput`, `inputAmount`, `usdIn`, `usdOut`, `userPriceImpact`, `route`, `flattenedRoute`, `requiredAppOptIns`, `protocolFees`
 
 ### api_haystack_execute_swap
@@ -728,8 +729,23 @@ DEX-aggregated swaps across Tinyman V2, Pact, and Folks with smart order routing
   "network": "mainnet"
 }
 ```
+- **`type`**: `"fixed-input"` = `amount` is the input (spend exactly this much); `"fixed-output"` = `amount` is the output (receive exactly this much). See **Swap Type Rules** below.
 - **Returns**: `status`, `confirmedRound`, `txIds`, `signer`, `nickname`, quote details, `summary` (inputAmount, outputAmount, totalFees, transactionCount)
 
+### Swap Type Rules
+
+> **CRITICAL**: The `type` parameter determines which side of the swap is exact. Getting this wrong means the user spends more or receives less than intended.
+
+| User intent | type | amount is | fromASAID | toASAID |
+|-------------|------|-----------|-----------|---------|
+| "Buy 10 ALGO with USDC" | `fixed-output` | 10000000 (output) | USDC | ALGO |
+| "Buy USDC for 10 ALGO" | `fixed-input` | 10000000 (input) | ALGO | USDC |
+| "Swap 5 USDC to ALGO" | `fixed-input` | 5000000 (input) | USDC | ALGO |
+| "I want exactly 100 USDC" | `fixed-output` | 100000000 (output) | ALGO | USDC |
+
+- **"Buy X of Y"** → `fixed-output`, amount = X in base units of Y, toASAID = Y
+- **"Swap/sell/use X of Y"** → `fixed-input`, amount = X in base units of Y, fromASAID = Y
+
 ### api_haystack_needs_optin
 - **Purpose**: Check if an address needs to opt into an asset before swapping
 - **Parameters**: `{ "address": "ALGO_ADDRESS", "assetId": 31566704, "network": "mainnet" }`

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

@@ -402,6 +402,16 @@ api_tinyman_get_pool {
 
 Best-price swap across multiple DEXes (Tinyman V2, Pact, Folks). For detailed reference, see the **haystack-router-interaction** skill.
 
+### CRITICAL: fixed-input vs fixed-output
+
+| User says | type | amount is | fromASAID | toASAID |
+|-----------|------|-----------|-----------|---------|
+| "Swap 10 ALGO for USDC" | `fixed-input` | 10000000 (input — spend exactly 10 ALGO) | 0 (ALGO) | 31566704 (USDC) |
+| "Buy 10 ALGO with USDC" | `fixed-output` | 10000000 (output — receive exactly 10 ALGO) | 31566704 (USDC) | 0 (ALGO) |
+
+- **"Buy X of Y"** → `fixed-output`, amount = X in base units of Y, toASAID = Y
+- **"Swap/sell/use X of Y"** → `fixed-input`, amount = X in base units of Y, fromASAID = Y
+
 ### Step 1: Check wallet
 ```
 wallet_get_info { "network": "mainnet" }
@@ -421,24 +431,41 @@ wallet_optin_asset { "assetId": 31566704, "network": "mainnet" }
 ```
 
 ### Step 3: Get a quote (show user before executing)
+
+**Example A — "Swap 10 ALGO for USDC" (fixed-input):**
 ```
 api_haystack_get_swap_quote {
   "fromASAID": 0,
   "toASAID": 31566704,
-  "amount": 1000000,
+  "amount": 10000000,
   "type": "fixed-input",
   "address": "[wallet_address]",
   "network": "mainnet"
 }
 ```
-> Present to user: expected output, USD values, route, price impact.
+
+**Example B — "Buy 10 ALGO with USDC" (fixed-output):**
+```
+api_haystack_get_swap_quote {
+  "fromASAID": 31566704,
+  "toASAID": 0,
+  "amount": 10000000,
+  "type": "fixed-output",
+  "address": "[wallet_address]",
+  "network": "mainnet"
+}
+```
+> Present to user: expected output (or estimated input), USD values, route, price impact.
 
 ### Step 4: Execute swap (after user confirms)
+
+Use the **same `type`, `fromASAID`, `toASAID`, and `amount`** as the quote:
 ```
 api_haystack_execute_swap {
   "fromASAID": 0,
   "toASAID": 31566704,
-  "amount": 1000000,
+  "amount": 10000000,
+  "type": "fixed-input",
   "slippage": 1,
   "network": "mainnet"
 }

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

@@ -56,11 +56,23 @@ The SDK is the **only** supported integration path. Do not call the API directly
 
 - **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
+- **Slippage**: Percentage tolerance on output (e.g., 1 = 1%). Applied to the final output, not individual hops.
+- **Quote types**: `fixed-input` (default) — specify input amount; `fixed-output` — specify desired output.
 - **Routing**: Supports multi-hop and parallel (combo) swaps for optimal pricing
 - **Middleware**: Plugin system for custom pre/post-swap transactions (e.g., auto opt-out)
 
+### fixed-input vs fixed-output
+
+| Type | `amount` specifies | Other side | Example |
+|------|-------------------|------------|---------|
+| `fixed-input` (default) | Input (what you send) | Estimated output | "Swap 10 ALGO for USDC" — spend exactly 10 ALGO |
+| `fixed-output` | Output (what you get) | Estimated input | "Buy 10 ALGO with USDC" — receive exactly 10 ALGO |
+
+- **"Buy X of Y"** → `fixed-output`, amount = X in base units of Y, toASAID = Y
+- **"Swap/sell/use X of Y"** → `fixed-input`, amount = X in base units of Y, fromASAID = Y
+- **"I want exactly X of Y"** → `fixed-output`, amount = X in base units of Y, toASAID = Y
+- The `amount` field always refers to the **fixed side** — never the estimated side
+
 ## Reference Files
 
 Read the appropriate file based on the task:

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

@@ -122,10 +122,39 @@ Step 4: User confirms → Execute
 
 - **Amounts** are always in base units (microAlgos for ALGO, smallest unit for ASAs)
 - **ASA IDs**: 0 = ALGO, 31566704 = USDC, etc.
+- **Slippage**: Percentage tolerance on output (e.g., 1 = 1%). Applied to the final output, not individual hops.
 - **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
 
+## CRITICAL: fixed-input vs fixed-output — Choosing the Correct Swap Type
+
+The `type` parameter determines which side of the swap is exact. Getting this wrong means the user spends more or receives less than intended. **Parse the user's intent carefully.**
+
+| Type | Meaning | `amount` specifies | The other side is | Use when |
+|------|---------|-------------------|-------------------|----------|
+| `fixed-input` | Spend exactly this much | **Input** amount (what you send) | Estimated (output varies) | "Swap 10 ALGO for USDC", "Sell 10 ALGO", "Use 10 ALGO to buy USDC" |
+| `fixed-output` | Receive exactly this much | **Output** amount (what you get) | Estimated (input varies) | "Buy 10 ALGO with USDC", "I want exactly 5 USDC", "Get me 10 ALGO" |
+
+### Mapping User Intent — Examples
+
+| User says | Type | fromASAID | toASAID | amount | Why |
+|-----------|------|-----------|---------|--------|-----|
+| "Buy 10 ALGO with USDC" | `fixed-output` | 31566704 (USDC) | 0 (ALGO) | 10000000 | User wants **exactly 10 ALGO** out |
+| "Buy USDC for 10 ALGO" | `fixed-input` | 0 (ALGO) | 31566704 (USDC) | 10000000 | User wants to **spend exactly 10 ALGO** |
+| "Swap 5 USDC to ALGO" | `fixed-input` | 31566704 (USDC) | 0 (ALGO) | 5000000 | User wants to **spend exactly 5 USDC** |
+| "I want exactly 100 USDC" | `fixed-output` | 0 (ALGO) | 31566704 (USDC) | 100000000 | User wants **exactly 100 USDC** out |
+| "Sell 10 ALGO" | `fixed-input` | 0 (ALGO) | 31566704 (USDC) | 10000000 | User wants to **spend exactly 10 ALGO** |
+| "Get me 10 ALGO" | `fixed-output` | 31566704 (USDC) | 0 (ALGO) | 10000000 | User wants **exactly 10 ALGO** out |
+
+### Rules
+
+1. **"Buy X of Y"** → `fixed-output`, amount = X (in base units of Y), toASAID = Y
+2. **"Swap/sell/use X of Y for Z"** → `fixed-input`, amount = X (in base units of Y), fromASAID = Y
+3. **"I want exactly X of Y"** → `fixed-output`, amount = X (in base units of Y), toASAID = Y
+4. **When ambiguous, ask the user**: "Do you want to spend exactly X or receive exactly X?"
+5. **The `amount` field always refers to the fixed side** — input amount for `fixed-input`, output amount for `fixed-output`
+6. **Always show the quote** before executing so the user can verify the estimated other side
+
 ## Reference Files
 
 Read the appropriate file based on the task: