@goplausible/openclaw-algorand-plugin 1.2.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,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.3.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.3.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
@@ -738,6 +737,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

@@ -447,6 +447,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 +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>",
@@ -616,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"):**
 ```