@goplausible/openclaw-algorand-plugin 1.1.0 → 1.3.0

package/lib/x402-fetch.ts

@@ -36,17 +36,10 @@ const PAYMENT_INSTRUCTIONS = `To pay for this resource, follow these steps using
      "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=" → "mainnet"
 
 2. Build fee payer transaction (facilitator sponsors fees for the group):
-   make_payment_txn {
-     from: "<feePayer from accepts[].extra.feePayer>",
-     to: "<feePayer>",
-     amount: 0,
-     fee: 2000,
-     flatFee: true,
-     network: "<network>"
-   }
-   — fee: 2000 covers both transactions in the group (1000 each). flatFee: true prevents SDK override.
+   make_payment_txn { from: "<feePayer from accepts[].extra.feePayer>", to: "<feePayer>", amount: 0, fee: N×1000 (N=group size, e.g. 2000 for 2 txns), flatFee: true, network: "<network>" }
+   — NEVER set fee=0 on the fee payer — this causes "txgroup had 0 in fees" errors.
 
-3. Build payment transaction (fee = 0 since facilitator covers it):
+3. Build payment transaction:
    — For native ALGO (asset "0"):
      make_payment_txn { from: "<your_address>", to: "<payTo>", amount: <maxAmountRequired>, fee: 0, flatFee: true, network: "<network>" }
    — For ASA (asset is ASA ID):

package/openclaw.plugin.json

@@ -2,14 +2,16 @@
   "id": "openclaw-algorand-plugin",
   "name": "Algorand Integration",
   "description": "Algorand blockchain integration with MCP and skills — by GoPlausible",
-  "version": "1.0.1",
+  "version": "1.3.0",
   "skills": [
     "skills/algorand-development",
     "skills/algorand-typescript",
     "skills/algorand-python",
     "skills/algorand-interaction",
     "skills/algorand-x402-typescript",
-    "skills/algorand-x402-python"
+    "skills/algorand-x402-python",
+    "skills/haystack-router-development",
+    "skills/haystack-router-interaction"
   ],
   "configSchema": {
     "type": "object",

package/package.json

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

package/skills/algorand-interaction/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: algorand-interaction
-description: Interact with Algorand blockchain via the Algorand MCP server — wallet operations, ALGO/ASA transactions, smart contracts, account info, NFD lookups, atomic groups, Tinyman swaps, TEAL compilation, knowledge base. Use when user asks about Algorand wallet, balances, sending ALGO or tokens, asset opt-in, transactions, NFD names, DEX swaps, smart contracts, or account details.
+description: Interact with Algorand blockchain via the Algorand MCP server — wallet operations, ALGO/ASA transactions, smart contracts, account info, NFD lookups, atomic groups, Tinyman swaps, Haystack Router DEX-aggregated swaps, TEAL compilation, knowledge base. Use when user asks about Algorand wallet, balances, sending ALGO or tokens, asset opt-in, transactions, NFD names, DEX swaps, smart contracts, or account details.
 ---
 
 # Algorand MCP Interaction
 
-Interact with Algorand blockchain through the Algorand MCP server (99 tools across 11 categories).
+Interact with Algorand blockchain through the Algorand MCP server (104+ tools across 13 categories).
 
 ## Key Characteristics
 
@@ -160,6 +160,10 @@ For atomic (all-or-nothing) multi-transaction groups:
 
 **Tinyman DEX** (9): `api_tinyman_get_pool`, `api_tinyman_get_pool_analytics`, `api_tinyman_get_pool_creation_quote`, `api_tinyman_get_liquidity_quote`, `api_tinyman_get_remove_liquidity_quote`, `api_tinyman_get_swap_quote`, `api_tinyman_get_asset_optin_quote`, `api_tinyman_get_validator_optin_quote`, `api_tinyman_get_validator_optout_quote`
 
+**Haystack Router** (3): `api_haystack_get_swap_quote`, `api_haystack_execute_swap`, `api_haystack_needs_optin` — DEX-aggregated swaps across Tinyman V2, Pact, Folks with optimal routing. See the **haystack-router-interaction** skill for detailed workflows and reference docs.
+
+**Pera Asset Verification** (3): `api_pera_asset_verification_status`, `api_pera_verified_asset_details`, `api_pera_verified_asset_search` — mainnet asset verification (verified/trusted/suspicious/unverified), detailed asset info with USD value, and search by name/keyword
+
 **ARC-26 URI** (1): `generate_algorand_uri`
 
 **Knowledge Base** (1): `get_knowledge_doc`
@@ -172,13 +176,15 @@ API responses are paginated. All API tools accept optional `itemsPerPage` (defau
 
 When `x402_fetch` returns HTTP 402 with `PaymentRequirements`, use the atomic group transaction pattern to build the payment:
 
-1. Build fee payer transaction (0-amount from facilitator's `feePayer` address, `fee: 2000`, `flatFee: true` — covers fees for both txns)
-2. Build payment transaction (ALGO or ASA transfer to `payTo`, `fee: 0`, `flatFee: true` — facilitator covers fee)
+1. Build fee payer transaction: `make_payment_txn` with from=feePayer, to=feePayer, amount=0, **fee=N×1000** (N=group size, e.g. 2000 for 2 txns), **flatFee=true**
+2. Build payment transaction: `make_payment_txn` or `make_asset_transfer_txn` to `payTo`, **fee=0**, **flatFee=true**
 3. Group both transactions with `assign_group_id`
-4. Sign only the payment transaction (index 1) with wallet and tool wallet_sign_transaction — leave fee payer unsigned
+4. Sign only the payment transaction (index 1) with `wallet_sign_transaction` — leave fee payer unsigned
 5. Encode the unsigned fee payer transaction (index 0) with `encode_unsigned_transaction`
 6. Construct PAYMENT-SIGNATURE JSON payload — **must include `accepted` field** (the exact `accepts[]` entry chosen) — and retry with `x402_fetch`
 
+> **IMPORTANT: Fee Abstraction** — Pass `fee` and `flatFee` directly as input parameters to `make_*_txn` tools. Fee payer: `fee=N×1000`, `flatFee=true`. Payment: `fee=0`, `flatFee=true`. NEVER set fee=0 on the fee payer — this causes "txgroup had 0 in fees" errors.
+
 **Critical**: The `accepted` field is REQUIRED. It must be an exact copy of the `accepts[]` entry you chose to pay with (including all fields: scheme, network, price, payTo, asset, maxAmountRequired, extra, etc.). Without it, the server cannot match your payment and will reject with 402.
 
 **Critical — Base64 blob handling**: When constructing the `paymentHeader` JSON string for `x402_fetch`, NEVER manually re-type or partially copy base64 blob strings. Use the EXACT `bytes` value from `encode_unsigned_transaction` and the EXACT `blob` value from `wallet_sign_transaction` — copy each complete value verbatim into the `paymentGroup` array. Even a single character corruption (e.g., `5` → `4`) causes "signature does not match sender" errors and the payment will be rejected.
@@ -204,7 +210,7 @@ When using NFD (`.algo` names), always use the `depositAccount` field from the N
 - **Mainnet = real value** — always confirm with user before mainnet transactions
 - Never log, display, or store mnemonics or secret keys — use `wallet_*` tools for signing
 - Verify recipient addresses with `validate_address` — transactions are irreversible
-- Verify asset IDs on-chain — scam tokens use similar names
+- Verify asset IDs on-chain and check verification tier with `api_pera_asset_verification_status` — scam tokens use similar names
 - Respect wallet spending limits — if rejected, inform user rather than bypassing
 
 ## Links

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

@@ -14,8 +14,10 @@
 7. [Indexer API Tools](#indexer-api-tools)
 8. [NFDomains API Tools](#nfdomains-api-tools)
 9. [Tinyman DEX API Tools](#tinyman-dex-api-tools)
-10. [ARC-26 URI Tools](#arc-26-uri-tools)
-11. [Knowledge Base Tools](#knowledge-base-tools)
+10. [Haystack Router Tools](#haystack-router-tools)
+11. [Pera Asset Verification Tools](#pera-asset-verification-tools)
+12. [ARC-26 URI Tools](#arc-26-uri-tools)
+13. [Knowledge Base Tools](#knowledge-base-tools)
 
 ---
 
@@ -198,17 +200,16 @@ Build unsigned transaction objects. Must be signed before submission.
   "from": "sender_address",
   "to": "receiver_address",
   "amount": 1000000,
-  "note": "optional note",
   "fee": 1000,
   "flatFee": false,
+  "note": "optional note",
   "closeRemainderTo": "optional",
   "rekeyTo": "optional",
   "network": "testnet"
 }
 ```
 > Amount in microAlgos: 1 ALGO = 1,000,000
-> `fee` (optional): transaction fee in microAlgos. Default: 1000 (minimum fee).
-> `flatFee` (optional): if `true`, use `fee` exactly as specified; if `false` (default), SDK may adjust fee based on transaction size.
+> `fee` (optional): transaction fee in microAlgos (default: suggested fee). `flatFee` (optional): if true, use exact fee value instead of suggested fee.
 
 ### make_keyreg_txn
 - **Purpose**: Create a key registration transaction for consensus participation
@@ -294,8 +295,7 @@ Build unsigned transaction objects. Must be signed before submission.
   "network": "testnet"
 }
 ```
-> `fee` (optional): transaction fee in microAlgos. Default: 1000 (minimum fee).
-> `flatFee` (optional): if `true`, use `fee` exactly as specified; if `false` (default), SDK may adjust fee based on transaction size.
+> `fee` (optional): transaction fee in microAlgos (default: suggested fee). `flatFee` (optional): if true, use exact fee value instead of suggested fee.
 
 ### make_app_create_txn
 - **Purpose**: Deploy a smart contract
@@ -691,6 +691,80 @@ Decentralized exchange operations on Tinyman AMM.
 
 ---
 
+## Haystack Router Tools
+
+DEX-aggregated swaps across Tinyman V2, Pact, and Folks with smart order routing. For detailed workflows and the full SDK guide, see the **haystack-router-interaction** and **haystack-router-development** skills.
+
+### api_haystack_get_swap_quote
+- **Purpose**: Get an optimized swap quote across multiple DEXes without executing
+- **Parameters**:
+```json
+{
+  "fromASAID": 0,
+  "toASAID": 31566704,
+  "amount": 1000000,
+  "type": "fixed-input",
+  "address": "optional — enables opt-in detection",
+  "maxGroupSize": 16,
+  "maxDepth": 4,
+  "network": "mainnet"
+}
+```
+- **Returns**: `expectedOutput`, `inputAmount`, `usdIn`, `usdOut`, `userPriceImpact`, `route`, `flattenedRoute`, `requiredAppOptIns`, `protocolFees`
+
+### api_haystack_execute_swap
+- **Purpose**: All-in-one swap: quote → sign (via wallet) → submit → confirm. Enforces wallet spending limits.
+- **Parameters**:
+```json
+{
+  "fromASAID": 0,
+  "toASAID": 31566704,
+  "amount": 1000000,
+  "slippage": 1,
+  "type": "fixed-input",
+  "note": "optional text note",
+  "maxGroupSize": 16,
+  "maxDepth": 4,
+  "network": "mainnet"
+}
+```
+- **Returns**: `status`, `confirmedRound`, `txIds`, `signer`, `nickname`, quote details, `summary` (inputAmount, outputAmount, totalFees, transactionCount)
+
+### 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" }`
+- **Returns**: `{ address, assetId, needsOptIn: true/false, network }`
+
+---
+
+## Pera Asset Verification Tools
+
+Mainnet asset verification via Pera Wallet API. Use to check if assets are legitimate before transacting.
+
+### api_pera_asset_verification_status
+- **Purpose**: Get the verification tier of a mainnet asset (verified, trusted, suspicious, unverified)
+- **Parameters**: `{ "assetId": 31566704 }`
+- **Returns**: `{ asset_id, verification_tier, explorer_url }`
+- **Note**: Mainnet only. Returns `"unverified"` for unknown assets.
+
+### api_pera_verified_asset_details
+- **Purpose**: Get detailed asset info including name, unit name, decimals, total supply, USD value, logo, verification tier, and collectible status
+- **Parameters**: `{ "assetId": 31566704 }`
+- **Returns**: Full asset object with `name`, `unit_name`, `fraction_decimals`, `total`, `usd_value`, `logo`, `verification_tier`, `is_collectible`, `creator_address`, etc.
+
+### api_pera_verified_asset_search
+- **Purpose**: Search mainnet assets by name, unit name, or keyword with optional verification filter
+- **Parameters**:
+```json
+{
+  "query": "USDC",
+  "verifiedOnly": true
+}
+```
+- **Returns**: Array of `{ asset_id, name, unit_name, decimals, verification_tier, usd_value, logo, creator_address, is_deleted }`
+
+---
+
 ## ARC-26 URI Tools
 
 ### generate_algorand_uri

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

@@ -398,6 +398,80 @@ api_tinyman_get_pool {
 
 ---
 
+## Haystack Router Swap (DEX-Aggregated)
+
+Best-price swap across multiple DEXes (Tinyman V2, Pact, Folks). For detailed reference, see the **haystack-router-interaction** skill.
+
+### Step 1: Check wallet
+```
+wallet_get_info { "network": "mainnet" }
+```
+
+### Step 2: Check opt-in (if swapping to an ASA)
+```
+api_haystack_needs_optin {
+  "address": "[wallet_address]",
+  "assetId": 31566704,
+  "network": "mainnet"
+}
+```
+If `needsOptIn: true`:
+```
+wallet_optin_asset { "assetId": 31566704, "network": "mainnet" }
+```
+
+### Step 3: Get a quote (show user before executing)
+```
+api_haystack_get_swap_quote {
+  "fromASAID": 0,
+  "toASAID": 31566704,
+  "amount": 1000000,
+  "type": "fixed-input",
+  "address": "[wallet_address]",
+  "network": "mainnet"
+}
+```
+> Present to user: expected output, USD values, route, price impact.
+
+### Step 4: Execute swap (after user confirms)
+```
+api_haystack_execute_swap {
+  "fromASAID": 0,
+  "toASAID": 31566704,
+  "amount": 1000000,
+  "slippage": 1,
+  "network": "mainnet"
+}
+```
+> Signs via wallet, submits, and confirms atomically. Returns confirmed round and tx IDs.
+
+---
+
+## Verify an Asset (Pera)
+
+Check if an asset is legitimate before transacting — mainnet only.
+
+### Check verification status
+```
+api_pera_asset_verification_status { "assetId": 31566704 }
+```
+> Returns: `{ asset_id: 31566704, verification_tier: "verified", explorer_url: "..." }`
+> Tiers: `verified` (highest), `trusted`, `suspicious`, `unverified`
+
+### Get detailed asset info with USD value
+```
+api_pera_verified_asset_details { "assetId": 31566704 }
+```
+> Returns: name, unit name, decimals, total supply, USD value, logo, verification tier
+
+### Search for verified assets
+```
+api_pera_verified_asset_search { "query": "USDC", "verifiedOnly": true }
+```
+> Returns array of matching assets filtered to verified/trusted only
+
+---
+
 ## Using the Knowledge Base
 
 ### Get a specific document
@@ -553,7 +627,8 @@ wallet_get_info { "network": "<network>" }
 
 ### Step 2: Build fee payer transaction
 
-The facilitator sponsors fees for the entire group. Set `fee: 2000` (covers both transactions at 1000 each) and `flatFee: true` to prevent the SDK from overriding:
+The facilitator sponsors fees for the entire group. The fee payer's `fee` must equal **N × 1000 µAlgo** (N = total transactions in group). For a 2-txn group: fee = 2 × 1000 = **2000**. NEVER set fee=0 on the fee payer.
+
 ```
 make_payment_txn {
   "from": "<feePayer>",
@@ -567,7 +642,7 @@ make_payment_txn {
 
 ### Step 3: Build payment transaction
 
-The payment transaction fee is 0 since the facilitator covers it. Set `flatFee: true` to prevent the SDK from adding a fee:
+The payment transaction fee is 0 since the facilitator covers it.
 
 **For native ALGO (asset = "0"):**
 ```

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

@@ -0,0 +1,85 @@
+---
+name: haystack-router-development
+description: Comprehensive guide for building applications with Haystack Router SDK (@txnlab/haystack-router) — a DEX aggregator and smart order routing protocol on Algorand. Use when developing swap UIs with React and use-wallet, writing Node.js automation scripts, integrating RouterClient for quotes and swaps, or working with the SDK API surface, middleware, fees, and referral program. Strong triggers include haystack router, @txnlab/haystack-router, RouterClient, DEX aggregator, swap UI, swap React, newQuote, newSwap, deflex migration, haystack SDK, swap routing, best price swap.
+---
+
+# Haystack Router (Development)
+
+This is the parent skill for building applications that integrate the `@txnlab/haystack-router` SDK — React swap UIs, Node.js automation scripts, custom signing flows, middleware, and direct RouterClient usage. No Algorand MCP tools are involved.
+
+> **Want to execute swaps** through the Algorand MCP server instead of building an app? Use the **haystack-router-interaction** skill — it provides Algorand MCP tools for quoting, swapping, and opt-in checking with wallet-based signing.
+> **Need Algorand blockchain interaction guidance?** See the **algorand-interaction** skill for wallet setup, transaction workflows, and MCP tool reference.
+
+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.
+
+## Package
+
+`@txnlab/haystack-router` — TypeScript SDK for DEX-aggregated swaps. Requires `algosdk` (v3+) as a peer dependency.
+
+```bash
+npm install @txnlab/haystack-router algosdk
+```
+
+**API key required.** A free tier key is available for immediate use — see [configuration.md](references/configuration.md) for details.
+
+## SDK Core Flow
+
+```typescript
+import { RouterClient } from '@txnlab/haystack-router'
+
+// 1. Initialize
+const router = new RouterClient({
+  apiKey: '1b72df7e-1131-4449-8ce1-29b79dd3f51e', // Free tier (60 requests/min)
+})
+
+// 2. Get a quote
+const quote = await router.newQuote({
+  fromASAID: 0, // ALGO
+  toASAID: 31566704, // USDC
+  amount: 1_000_000, // 1 ALGO (base units)
+  address: activeAddress,
+})
+
+// 3. Execute the swap (use-wallet signer for browser, custom signer for Node.js)
+const swap = await router.newSwap({
+  quote,
+  address: activeAddress,
+  signer: transactionSigner,
+  slippage: 1, // 1%
+})
+const result = await swap.execute()
+```
+
+The SDK is the **only** supported integration path. Do not call the API directly.
+
+## 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
+- **Middleware**: Plugin system for custom pre/post-swap transactions (e.g., auto opt-out)
+
+## Reference Files
+
+Read the appropriate file based on the task:
+
+| Task                                    | Reference                                               |
+| --------------------------------------- | ------------------------------------------------------- |
+| Install SDK, initialize RouterClient    | [getting-started.md](references/getting-started.md)     |
+| Get swap quotes, display pricing        | [quotes.md](references/quotes.md)                       |
+| Execute swaps with SDK signing          | [swaps.md](references/swaps.md)                         |
+| Build React swap UI with use-wallet     | [react-integration.md](references/react-integration.md) |
+| Automate swaps via Node.js scripts      | [node-automation.md](references/node-automation.md)     |
+| RouterClient config, middleware, debug  | [configuration.md](references/configuration.md)         |
+| Fee structure, referral program         | [fees-and-referrals.md](references/fees-and-referrals.md) |
+| Full API surface and types              | [api-reference.md](references/api-reference.md)         |
+| Migrate from @txnlab/deflex             | [migration.md](references/migration.md)                 |
+
+## How to Use This Skill
+
+1. **Start here** to understand which reference you need
+2. **Read the topic `.md`** file for step-by-step guidance
+3. **For MCP-based swaps** (no SDK), see the `haystack-router-interaction` skill
+4. **For general Algorand development**, see `algorand-development`, `algorand-typescript`, or `algorand-python` skills