@goplausible/openclaw-algorand-plugin 1.2.0 → 1.4.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,7 +2,7 @@
   "id": "openclaw-algorand-plugin",
   "name": "Algorand Integration",
   "description": "Algorand blockchain integration with MCP and skills — by GoPlausible",
-  "version": "1.2.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.2.0",
+  "version": "1.4.0",
   "publishConfig": {
     "access": "public"
   },

package/skills/algorand-interaction/SKILL.md

@@ -5,7 +5,7 @@ description: Interact with Algorand blockchain via the Algorand MCP server — w
 
 # Algorand MCP Interaction
 
-Interact with Algorand blockchain through the Algorand MCP server (101+ tools across 12 categories).
+Interact with Algorand blockchain through the Algorand MCP server (104+ tools across 13 categories).
 
 ## Key Characteristics
 
@@ -162,6 +162,8 @@ For atomic (all-or-nothing) multi-transaction groups:
 
 **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`
@@ -174,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.
@@ -206,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

@@ -15,8 +15,9 @@
 8. [NFDomains API Tools](#nfdomains-api-tools)
 9. [Tinyman DEX API Tools](#tinyman-dex-api-tools)
 10. [Haystack Router Tools](#haystack-router-tools)
-11. [ARC-26 URI Tools](#arc-26-uri-tools)
-12. [Knowledge Base Tools](#knowledge-base-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)
 
 ---
 
@@ -199,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
@@ -295,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
@@ -711,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
@@ -729,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" }`
@@ -738,6 +753,34 @@ DEX-aggregated swaps across Tinyman V2, Pact, and Folks with smart order routing
 
 ---
 
+## 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

@@ -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"
 }
@@ -447,6 +474,31 @@ api_haystack_execute_swap {
 
 ---
 
+## 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
@@ -602,7 +654,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>",
@@ -616,7 +669,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

@@ -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: