@goplausible/openclaw-algorand-plugin 1.7.2 → 1.8.1

package/README.md

@@ -4,16 +4,21 @@
 
 ## Features
 
-- **Local MCP Server**: Bundled `algorand-mcp` (99 tools) — wallet, transactions, smart contracts, TEAL, indexer, DEX, NFD, knowledge base
+- **Local MCP Server**: Bundled `algorand-mcp` (107 tools) — wallet, transactions, smart contracts, TEAL, indexer, DEX, NFD, Haystack Router, Alpha Arcade, knowledge base
 - **x402 Payment Protocol**: Built-in `x402_fetch` tool for HTTP-native payments on Algorand
+- **Headless Linux Keyring Persistence**: Automatic setup for wallet key persistence on cloud VMs and Docker (survives reboots)
 - **Interactive Setup**: Guided wizard for configuration
-- **Skills Included** (6 skills):
+- **Skills Included** (9 skills):
   - `algorand-development` — AlgoKit CLI, project creation, general workflows
   - `algorand-typescript` — TypeScript smart contracts (PuyaTs)
   - `algorand-python` — Python smart contracts (PuyaPy)
   - `algorand-interaction` — Blockchain interaction via MCP (wallet, transactions, swaps, NFD)
   - `algorand-x402-typescript` — x402 payments in TypeScript
   - `algorand-x402-python` — x402 payments in Python
+  - `algorand-x402-payment` — Runtime x402 payment (agent as client)
+  - `haystack-router-development` — DEX aggregator SDK integration
+  - `haystack-router-interaction` — Best-price swaps via MCP tools
+  - `alpha-arcade-interaction` — Prediction markets interaction
 
 ## Installation
 
@@ -35,7 +40,7 @@ After installing, run these commands:
 # 1. Initialize plugin (write memory file + configure mcporter)
 openclaw algorand-plugin init
 
-# 2. Run interactive setup (configure x402 toggle)
+# 2. Run interactive setup (keyring persistence + x402 toggle)
 openclaw algorand-plugin setup
 
 # 3. Restart the gateway
@@ -55,7 +60,7 @@ openclaw algorand-plugin mcp-config  # Show MCP config snippet for external codi
 
 The plugin bundles [`@goplausible/algorand-mcp`](https://www.npmjs.com/package/@goplausible/algorand-mcp) as an npm dependency. It runs locally via stdio through [mcporter](https://www.npmjs.com/package/mcporter).
 
-- **99 tools** across 11 categories (wallet, transactions, algod, indexer, NFD, Tinyman, TEAL, knowledge base, and more)
+- **107 tools** across 13 categories (wallet, transactions, algod, indexer, NFD, Tinyman, Haystack Router, Pera verification, Alpha Arcade, TEAL, knowledge base, and more)
 - **Multi-network**: `mainnet`, `testnet`, `localnet`
 - **Secure wallet**: Per-transaction and daily spending limits, private keys never exposed to agents
 
@@ -67,6 +72,17 @@ When `enableX402` is enabled (default), the plugin registers the `x402_fetch` to
 - Agent builds payment using algorand-mcp wallet tools (atomic group with facilitator-sponsored fees)
 - Agent retries with signed `PAYMENT-SIGNATURE` header to complete the payment and access the resource
 
+## Headless Linux (Cloud VMs, Docker)
+
+On headless Linux, the OS keyring defaults to in-memory storage — wallet keys created by `algorand-mcp` are **lost on reboot**. The setup wizard (`openclaw algorand-plugin setup`) automatically detects this and:
+
+1. Installs `gnome-keyring`, `libsecret-tools`, `dbus-user-session`
+2. Enables `loginctl linger` for D-Bus session persistence
+3. Creates a persistent login keyring (auto-unlocked, no password)
+4. Backs up and restores existing wallet mnemonics if upgrading
+
+After setup, wallet keys persist across reboots with no user interaction needed. Agent wallets are hot wallets — keep funds minimal and use QR code top-ups.
+
 ## Configuration
 
 Config is stored in `~/.openclaw/openclaw.json` under `plugins.entries.openclaw-algorand-plugin.config`:

package/index.ts

@@ -301,6 +301,29 @@ export default function register(api: PluginApi) {
           console.log("  Config:");
           console.log(`    x402:      ${pluginConfig.enableX402 !== false ? "Enabled" : "Disabled"}`);
           console.log("");
+
+          // Keyring status
+          try {
+            const scriptPath = join(__dirname, "scripts", "setup-keyring.sh");
+            const keyringOutput = execSync(`bash "${scriptPath}" --detect`, { encoding: "utf-8", timeout: 5000 });
+            const vars = Object.fromEntries(
+              keyringOutput.trim().split("\n").map((line: string) => line.split("=", 2))
+            );
+            console.log("  Keyring:");
+            if (vars.PERSISTENT === "true") {
+              console.log(`    Storage:   ✅ ${vars.BACKEND}`);
+              console.log(`    Wallets:   ${vars.WALLET_DB_COUNT} account(s) in wallet.db`);
+            } else {
+              console.log(`    Storage:   ⚠️  ${vars.BACKEND} — run \`openclaw algorand-plugin setup\``);
+              if (parseInt(vars.WALLET_DB_COUNT) > 0) {
+                console.log(`    Wallets:   ⚠️  ${vars.WALLET_DB_COUNT} account(s) with mnemonics in volatile storage!`);
+              }
+            }
+          } catch {
+            console.log("  Keyring:");
+            console.log("    Storage:   ❓ Could not detect");
+          }
+          console.log("");
           console.log("  Links:");
           console.log(`    GoPlausible: ${GOPLAUSIBLE_SERVICES.website}`);
           console.log(`    Algorand x402: ${GOPLAUSIBLE_SERVICES.x402}`);
@@ -346,6 +369,16 @@ export default function register(api: PluginApi) {
       console.log("   This plugin provides:");
       console.log("   • 9 Algorand skills (Algorand development in TS and Python, x402, MCP interaction, alpha arcade interaction, haystack router development and interaction)");
       console.log("   • algorand-mcp server (~100 blockchain tools via mcporter)\n");
+      // Keyring persistence warning for headless Linux
+      try {
+        const scriptPath = join(__dirname, "scripts", "setup-keyring.sh");
+        const keyringOutput = execSync(`bash "${scriptPath}" --detect`, { encoding: "utf-8", timeout: 5000 });
+        if (keyringOutput.includes("PERSISTENT=false")) {
+          console.log("   ⚠️  Headless Linux detected — wallet keys use in-memory storage.");
+          console.log("   Run `openclaw algorand-plugin setup` for persistent storage.\n");
+        }
+      } catch { /* ignore on install */ }
+
       console.log("   Next steps:");
       console.log("   1. Run `openclaw algorand-plugin init` — configure mcporter + add plugin memory");
       console.log("   2. Run `openclaw algorand-plugin setup` — configure options & add to allow list");

package/lib/mcp-servers.ts

@@ -1,7 +1,7 @@
 export const ALGORAND_MCP = {
   id: "algorand-mcp",
   name: "Algorand MCP",
-  description: "Local Algorand MCP server — 99 tools for blockchain interaction",
+  description: "Local Algorand MCP server — 107 tools for blockchain interaction",
   type: "stdio" as const,
   command: "algorand-mcp",
 } as const;

package/memory/algorand-plugin.md

@@ -1,10 +1,12 @@
 # Algorand Plugin Guide
 
-This plugin enables three core capabilities:
+This plugin enables four core capabilities:
 
 1. **Algorand Development** — Smart contracts, typed clients, React frontends via AlgoKit CLI and skills
-2. **Blockchain Interaction** — Algorand MCP server (99 tools) via mcporter
+2. **Blockchain Interaction** — Algorand MCP server (107 tools) via mcporter (includes Pera asset verification)
 3. **x402 Payment Protocol** — HTTP-native payments with Algorand as first-class chain
+4. **Haystack Router** — DEX aggregator/smart order routing on Algorand (Tinyman V2, Pact, Folks)
+5. **Alpha Arcade** — On-chain prediction markets on Algorand (USDC-denominated, binary/multi-choice)
 
 ## Skill Routing
 
@@ -16,6 +18,10 @@ This plugin enables three core capabilities:
 | Interaction | Blockchain interaction via MCP | `algorand-interaction` |
 | x402 | TypeScript x402 development | `algorand-x402-typescript` |
 | x402 | Python x402 development | `algorand-x402-python` |
+| x402 | Runtime x402 payment (Claude as client) | `algorand-x402-payment` |
+| Haystack | Build swap apps with SDK | `haystack-router-development` |
+| Haystack | Execute swaps via MCP tools | `haystack-router-interaction` |
+| Alpha Arcade | Prediction markets via MCP tools | `alpha-arcade-interaction` |
 
 ## Using Algorand MCP Tools
 
@@ -31,7 +37,7 @@ mcporter call algorand-mcp.get_account_info address=XXXXX network=testnet
 mcporter call algorand-mcp.search_assets name=USDC network=mainnet
 ```
 
-## MCP Tool Categories (101 tools)
+## MCP Tool Categories (107 tools)
 
 - **Wallet** (10) — `wallet_add_account`, `wallet_remove_account`, `wallet_list_accounts`, `wallet_switch_account`, `wallet_get_info`, `wallet_get_assets`, `wallet_sign_transaction`, `wallet_sign_transaction_group`, `wallet_sign_data`, `wallet_optin_asset`
 - **Account Management** (8) — `create_account`, `rekey_account`, `mnemonic_to_mdk`, `mdk_to_mnemonic`, `secret_key_to_mnemonic`, `mnemonic_to_secret_key`, `seed_from_mnemonic`, `mnemonic_from_seed`
@@ -42,9 +48,37 @@ mcporter call algorand-mcp.search_assets name=USDC network=mainnet
 - **Indexer API** (17) — `api_indexer_lookup_account_by_id`, `api_indexer_lookup_account_assets`, `api_indexer_lookup_account_app_local_states`, `api_indexer_lookup_account_created_applications`, `api_indexer_search_for_accounts`, `api_indexer_lookup_applications`, `api_indexer_lookup_application_logs`, `api_indexer_search_for_applications`, `api_indexer_lookup_application_box`, `api_indexer_lookup_application_boxes`, `api_indexer_lookup_asset_by_id`, `api_indexer_lookup_asset_balances`, `api_indexer_lookup_asset_transactions`, `api_indexer_search_for_assets`, `api_indexer_lookup_transaction_by_id`, `api_indexer_lookup_account_transactions`, `api_indexer_search_for_transactions`
 - **NFDomains** (6) — `api_nfd_get_nfd`, `api_nfd_get_nfds_for_addresses`, `api_nfd_get_nfd_activity`, `api_nfd_get_nfd_analytics`, `api_nfd_browse_nfds`, `api_nfd_search_nfds`
 - **Tinyman AMM** (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`
-- **ARC-26 URI** (1) — `generate_algorand_uri`
+- **Haystack Router** (3) — `api_haystack_get_swap_quote`, `api_haystack_execute_swap`, `api_haystack_needs_optin`
+- **Pera Asset Verification** (3) — `api_pera_asset_verification_status`, `api_pera_verified_asset_details`, `api_pera_verified_asset_search`
+- **Alpha Arcade** (15) — Read: `alpha_get_live_markets`, `alpha_get_reward_markets`, `alpha_get_market`, `alpha_get_orderbook`, `alpha_get_open_orders`, `alpha_get_positions`. Trade: `alpha_create_limit_order`, `alpha_create_market_order`, `alpha_cancel_order`, `alpha_amend_order`, `alpha_propose_match`, `alpha_split_shares`, `alpha_merge_shares`, `alpha_claim`
+- **ARC-26 URI** (1) — `generate_algorand_qrcode`
 - **Knowledge** (1) — `get_knowledge_doc` (categories: `arcs`, `sdks`, `algokit`, `algokit-utils`, `tealscript`, `puya`, `liquid-auth`, `python`, `developers`, `clis`, `nodes`, `details`)
 
+## QR Code Display (ARC-26 URI)
+
+When generating QR codes with `generate_algorand_qrcode`, the tool returns:
+- UTF-8 text QR code (terminal-friendly)
+- PNG image as base64 (web-friendly)
+- URI string
+
+**Important:** MCP tool output may not render properly through mcporter → exec pipeline.
+After calling the tool, **extract and paste the QR code directly in your response**:
+
+1. Call the tool and capture output
+2. Extract the UTF-8 QR block (Unicode block characters)
+3. Extract the base64 PNG data
+4. Include both in your reply:
+
+```
+[paste UTF-8 QR here]
+```
+
+![QR Code](data:image/png;base64,[paste base64 here])
+
+URI: `algorand://ADDRESS?amount=X&asset=Y`
+
+This ensures the QR renders correctly in both terminal and web interfaces.
+
 ## Key things to remember
 
 - Always check wallet with `wallet_get_info` before blockchain operations
@@ -70,6 +104,7 @@ mcporter call algorand-mcp.search_assets name=USDC network=mainnet
 - **NEVER use PyTEAL or Beaker** — these are legacy. Use Algorand TypeScript or Algorand Python.
 - **NEVER use AlgoExplorer** — obsolete. Use Allo.info for block/account/transaction data.
 - **NFD (.algo names)**: Always use `depositAccount` field for transactions.
+- **Alpha Arcade prices are microunits**: `yesProb`/`noProb` range 0–1,000,000 (NOT percentages). $0.50 = 500,000. Orders require both ALGO (MBR) and USDC (collateral).
 
 ## External resources
 
@@ -81,9 +116,12 @@ mcporter call algorand-mcp.search_assets name=USDC network=mainnet
 - Testnet Faucet: https://lora.algokit.io/testnet/fund
 - Testnet USDC Faucet: https://faucet.circle.com/
 - Algorand Developer Docs: https://dev.algorand.co/
-- Algorand Developer Docs Github : https://github.com/algorandfoundation/devportal
-- Algorand Developer Examples Github : https://github.com/algorandfoundation/devportal-code-examples
-- GoPlausible x402-avm Documentation and Example code : https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/README.md
-- GoPlausible x402-avm Examples template Projects : https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/
-- CAIP-2 Specification : https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md
-- Coinbase x402 Protocol : https://github.com/coinbase/x402
+- Algorand Developer Docs Github: https://github.com/algorandfoundation/devportal
+- Algorand Developer Examples Github: https://github.com/algorandfoundation/devportal-code-examples
+- GoPlausible x402-avm Documentation and Example code: https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/README.md
+- GoPlausible x402-avm Examples template Projects: https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/
+- CAIP-2 Specification: https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md
+- Coinbase x402 Protocol: https://github.com/coinbase/x402
+- Haystack Router: https://github.com/TxnLab/haystack-router
+- Alpha Arcade: https://alphaarcade.com
+- Alpha Arcade API: https://platform.alphaarcade.com

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.7.2",
+  "version": "1.8.1",
   "skills": [
     "skills/algorand-development",
     "skills/algorand-typescript",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplausible/openclaw-algorand-plugin",
-  "version": "1.7.2",
+  "version": "1.8.1",
   "publishConfig": {
     "access": "public"
   },
@@ -27,6 +27,7 @@
     "index.ts",
     "setup.ts",
     "lib/",
+    "scripts/",
     "skills/",
     "memory/",
     "openclaw.plugin.json"

package/scripts/backup-keyring.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Usage:
+//   node backup-keyring.js backup <output-file>    — dump address\tmnemonic pairs
+//   node backup-keyring.js restore <input-file>     — restore mnemonics from backup
+//   node backup-keyring.js count                    — print number of accounts in wallet.db
+//   node backup-keyring.js verify                   — check which accounts have mnemonics in keyring
+
+const { Entry } = require('@napi-rs/keyring');
+const initSqlJs = require('sql.js');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const KEYCHAIN_SERVICE = 'algorand-mcp';
+const WALLET_DB = path.join(os.homedir(), '.algorand-mcp', 'wallet.db');
+
+async function getAccounts() {
+  if (!fs.existsSync(WALLET_DB)) return [];
+  const SQL = await initSqlJs();
+  const buf = fs.readFileSync(WALLET_DB);
+  const db = new SQL.Database(buf);
+  const rows = db.exec('SELECT address FROM accounts');
+  db.close();
+  if (!rows.length || !rows[0].values.length) return [];
+  return rows[0].values.map(r => r[0]);
+}
+
+function getMnemonic(address) {
+  try {
+    const entry = new Entry(KEYCHAIN_SERVICE, address);
+    const pw = entry.getPassword();
+    return pw || null;
+  } catch {
+    return null;
+  }
+}
+
+function setMnemonic(address, mnemonic) {
+  const entry = new Entry(KEYCHAIN_SERVICE, address);
+  entry.setPassword(mnemonic);
+}
+
+async function main() {
+  const mode = process.argv[2];
+  const file = process.argv[3];
+
+  if (mode === 'count') {
+    const accounts = await getAccounts();
+    console.log(accounts.length);
+    return;
+  }
+
+  if (mode === 'verify') {
+    const accounts = await getAccounts();
+    let ok = 0, missing = 0;
+    for (const addr of accounts) {
+      if (getMnemonic(addr)) {
+        console.log('OK ' + addr);
+        ok++;
+      } else {
+        console.log('MISSING ' + addr);
+        missing++;
+      }
+    }
+    console.log(`TOTAL=${accounts.length} OK=${ok} MISSING=${missing}`);
+    return;
+  }
+
+  if (mode === 'backup') {
+    if (!file) { console.error('Usage: backup-keyring.js backup <output-file>'); process.exit(1); }
+    const accounts = await getAccounts();
+    if (accounts.length === 0) {
+      console.log('NO_ACCOUNTS');
+      return;
+    }
+    let backed = 0, failed = 0;
+    const lines = [];
+    for (const addr of accounts) {
+      const mnemonic = getMnemonic(addr);
+      if (mnemonic) {
+        lines.push(addr + '\t' + mnemonic);
+        backed++;
+      } else {
+        console.error('MISSING ' + addr);
+        failed++;
+      }
+    }
+    if (lines.length > 0) {
+      fs.writeFileSync(file, lines.join('\n') + '\n', { mode: 0o600 });
+    }
+    console.log(`BACKED_UP=${backed} FAILED=${failed}`);
+    return;
+  }
+
+  if (mode === 'restore') {
+    if (!file) { console.error('Usage: backup-keyring.js restore <input-file>'); process.exit(1); }
+    if (!fs.existsSync(file)) { console.error('File not found: ' + file); process.exit(1); }
+    const content = fs.readFileSync(file, 'utf-8').trim();
+    if (!content) { console.log('RESTORED=0'); return; }
+    let restored = 0;
+    for (const line of content.split('\n')) {
+      const [addr, ...rest] = line.split('\t');
+      const mnemonic = rest.join('\t');
+      if (addr && mnemonic) {
+        setMnemonic(addr, mnemonic);
+        restored++;
+      }
+    }
+    console.log(`RESTORED=${restored}`);
+    return;
+  }
+
+  console.error('Usage: backup-keyring.js <backup|restore|count|verify> [file]');
+  process.exit(1);
+}
+
+main().catch(err => { console.error(err.message); process.exit(1); });

package/scripts/setup-keyring.sh

@@ -0,0 +1,428 @@
+#!/usr/bin/env bash
+set -e
+
+MODE="${1:---detect}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PLUGIN_DIR="$(dirname "$SCRIPT_DIR")"
+NODE_MODULES="$PLUGIN_DIR/node_modules"
+BACKUP_SCRIPT="$SCRIPT_DIR/backup-keyring.js"
+WALLET_DB="$HOME/.algorand-mcp/wallet.db"
+
+# ═══════════════════════════════════════════════════════════
+# 1. OS Detection
+# ═══════════════════════════════════════════════════════════
+if [[ "$(uname -s)" != "Linux" ]]; then
+  case "$(uname -s)" in
+    Darwin)  BACKEND="macOS Keychain" ;;
+    *)       BACKEND="OS Keychain" ;;
+  esac
+  if [ "$MODE" = "--detect" ]; then
+    echo "PLATFORM=$(uname -s | tr '[:upper:]' '[:lower:]')"
+    echo "BACKEND=$BACKEND"
+    echo "PERSISTENT=true"
+    echo "HEADLESS=false"
+  else
+    echo ""
+    echo "  ✅ $BACKEND — persistent by default. No setup needed."
+    echo ""
+  fi
+  exit 0
+fi
+
+# ═══════════════════════════════════════════════════════════
+# 2. Linux Environment Detection
+# ═══════════════════════════════════════════════════════════
+
+PLATFORM="linux"
+KEYRING_DIR="$HOME/.local/share/keyrings"
+
+# Display (headless?)
+HAS_DISPLAY=false
+[[ -n "${DISPLAY:-}" || -n "${WAYLAND_DISPLAY:-}" ]] && HAS_DISPLAY=true
+
+# D-Bus session
+HAS_DBUS=false
+[[ -n "${DBUS_SESSION_BUS_ADDRESS:-}" ]] && HAS_DBUS=true
+
+# GNOME Keyring daemon running
+KEYRING_RUNNING=false
+pgrep -u "$USER" gnome-keyring-daemon >/dev/null 2>&1 && KEYRING_RUNNING=true
+
+# Keyring files on disk
+KEYRING_FILES=false
+[[ -d "$KEYRING_DIR" && "$(ls -A "$KEYRING_DIR" 2>/dev/null)" ]] && KEYRING_FILES=true
+
+# Wallet DB exists and account count (via Node.js)
+WALLET_DB_EXISTS=false
+WALLET_DB_COUNT=0
+[[ -f "$WALLET_DB" ]] && WALLET_DB_EXISTS=true
+if [[ "$WALLET_DB_EXISTS" == "true" && -f "$BACKUP_SCRIPT" ]]; then
+  WALLET_DB_COUNT=$(NODE_PATH="$NODE_MODULES" node "$BACKUP_SCRIPT" count 2>/dev/null || echo "0")
+fi
+
+# Package manager
+PKG=""
+if command -v apt >/dev/null 2>&1; then
+  PKG="apt"
+elif command -v dnf >/dev/null 2>&1; then
+  PKG="dnf"
+elif command -v yum >/dev/null 2>&1; then
+  PKG="yum"
+elif command -v pacman >/dev/null 2>&1; then
+  PKG="pacman"
+elif command -v apk >/dev/null 2>&1; then
+  PKG="apk"
+fi
+
+# Container detection
+IN_CONTAINER=false
+[[ -f /.dockerenv ]] && IN_CONTAINER=true
+grep -q 'docker\|lxc\|containerd' /proc/1/cgroup 2>/dev/null && IN_CONTAINER=true
+
+# Persistence verdict
+HEADLESS=false
+if [[ "$HAS_DBUS" == "true" && "$KEYRING_RUNNING" == "true" && "$KEYRING_FILES" == "true" ]]; then
+  PERSISTENT="true"
+  BACKEND="GNOME Keyring (persistent)"
+elif [[ "$HAS_DISPLAY" == "true" ]]; then
+  PERSISTENT="true"
+  BACKEND="Desktop Keyring (persistent)"
+else
+  PERSISTENT="false"
+  BACKEND="In-memory (volatile)"
+  HEADLESS=true
+fi
+
+# ═══════════════════════════════════════════════════════════
+# 3. Detect-only mode
+# ═══════════════════════════════════════════════════════════
+if [ "$MODE" = "--detect" ]; then
+  echo "PLATFORM=$PLATFORM"
+  echo "BACKEND=$BACKEND"
+  echo "PERSISTENT=$PERSISTENT"
+  echo "HEADLESS=$HEADLESS"
+  echo "HAS_DISPLAY=$HAS_DISPLAY"
+  echo "HAS_DBUS=$HAS_DBUS"
+  echo "KEYRING_RUNNING=$KEYRING_RUNNING"
+  echo "KEYRING_FILES=$KEYRING_FILES"
+  echo "WALLET_DB_EXISTS=$WALLET_DB_EXISTS"
+  echo "WALLET_DB_COUNT=$WALLET_DB_COUNT"
+  echo "PKG_MANAGER=$PKG"
+  echo "IN_CONTAINER=$IN_CONTAINER"
+  exit 0
+fi
+
+# ═══════════════════════════════════════════════════════════
+# 4. Setup mode
+# ═══════════════════════════════════════════════════════════
+
+echo ""
+echo "  ── Algorand MCP Keyring Persistence Setup ──"
+echo ""
+
+# ─── 4a. Status display ───
+echo "  Platform:        Linux"
+echo "  Display:         $( [[ "$HAS_DISPLAY" == "true" ]] && echo "✅ Yes" || echo "❌ No (headless)" )"
+echo "  D-Bus session:   $( [[ "$HAS_DBUS" == "true" ]] && echo "✅ Active" || echo "❌ Not found" )"
+echo "  Keyring daemon:  $( [[ "$KEYRING_RUNNING" == "true" ]] && echo "✅ Running" || echo "❌ Not running" )"
+echo "  Keyring files:   $( [[ "$KEYRING_FILES" == "true" ]] && echo "✅ Found in $KEYRING_DIR" || echo "❌ None (in-memory only)" )"
+echo "  Wallet DB:       $( [[ "$WALLET_DB_EXISTS" == "true" ]] && echo "✅ $WALLET_DB ($WALLET_DB_COUNT account(s))" || echo "— Not found (fresh install)" )"
+echo "  Package manager: ${PKG:-unknown}"
+echo "  Container:       $( [[ "$IN_CONTAINER" == "true" ]] && echo "Yes" || echo "No" )"
+echo ""
+
+# Already persistent with keyring files on disk?
+if [[ "$PERSISTENT" == "true" && "$KEYRING_FILES" == "true" ]]; then
+  echo "  ✅ Keyring is persistent and will survive reboots."
+  echo ""
+  exit 0
+fi
+
+# ─── 4b. Backup existing wallet mnemonics (UPDATE scenario only) ───
+BACKUP_FILE=""
+if [[ "$WALLET_DB_COUNT" -gt 0 && "$KEYRING_RUNNING" == "true" && -f "$BACKUP_SCRIPT" ]]; then
+  echo "  ── Step 1: Backup wallet mnemonics from current keyring ──"
+  echo ""
+  echo "  Found $WALLET_DB_COUNT account(s) in wallet.db."
+  echo "  Reading mnemonics from current keyring before setup..."
+  echo ""
+
+  BACKUP_FILE=$(mktemp /tmp/algorand-mcp-keyring-backup.XXXXXX)
+  chmod 600 "$BACKUP_FILE"
+
+  BACKUP_RESULT=$(NODE_PATH="$NODE_MODULES" node "$BACKUP_SCRIPT" backup "$BACKUP_FILE" 2>&1)
+  echo "  $BACKUP_RESULT"
+
+  # Check if backup actually has content
+  if [[ ! -s "$BACKUP_FILE" ]]; then
+    rm -f "$BACKUP_FILE"
+    BACKUP_FILE=""
+    echo "  ℹ️  No mnemonics to backup (keyring may be empty after a reboot)."
+  fi
+  echo ""
+elif [[ "$WALLET_DB_COUNT" -gt 0 && "$KEYRING_RUNNING" != "true" ]]; then
+  echo "  ── Step 1: Backup ──"
+  echo ""
+  echo "  ⚠️  Keyring daemon not running — cannot backup existing mnemonics."
+  echo "  If the system was rebooted, in-memory mnemonics are already lost."
+  echo ""
+fi
+
+# ─── 4c. Install keyring packages ───
+echo "  ── Step 2: Install keyring packages ──"
+echo ""
+
+if [[ -z "$PKG" ]]; then
+  echo "  Could not detect package manager. Install manually:"
+  echo "    gnome-keyring, libsecret-tools, dbus-user-session (or equivalent)"
+  echo ""
+else
+  case "$PKG" in
+    apt)
+      INSTALL_CMD="sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt update && sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_MODE=a apt install -y gnome-keyring libsecret-tools dbus-user-session"
+      ;;
+    dnf)
+      INSTALL_CMD="sudo dnf install -y gnome-keyring libsecret libsecret-tools"
+      ;;
+    yum)
+      INSTALL_CMD="sudo yum install -y gnome-keyring libsecret libsecret-tools"
+      ;;
+    pacman)
+      INSTALL_CMD="sudo pacman -Sy --noconfirm gnome-keyring libsecret"
+      ;;
+    apk)
+      INSTALL_CMD="sudo apk add gnome-keyring libsecret dbus secret-tool"
+      ;;
+  esac
+
+  echo "  Run:"
+  echo "    $INSTALL_CMD"
+  echo ""
+  read -r -p "  Install now? [y/N] " REPLY
+  if [[ "$REPLY" =~ ^[Yy]$ ]]; then
+    echo ""
+    eval "$INSTALL_CMD"
+    echo ""
+    echo "  ✅ Packages installed."
+  else
+    echo "  Skipped. Install later with the command above."
+  fi
+  echo ""
+fi
+
+# ─── 4d. Enable lingering user session ───
+echo "  ── Step 3: Enable user session lingering ──"
+echo ""
+echo "  This keeps D-Bus and keyring daemon alive after SSH logout."
+echo ""
+
+if loginctl show-user "$USER" 2>/dev/null | grep -q "Linger=yes"; then
+  echo "  ✅ Lingering already enabled for $USER"
+else
+  read -r -p "  Enable lingering for $USER? [y/N] " REPLY
+  if [[ "$REPLY" =~ ^[Yy]$ ]]; then
+    loginctl enable-linger "$USER"
+    echo "  ✅ Lingering enabled."
+  else
+    echo "  Skipped."
+  fi
+fi
+echo ""
+
+# ─── 4e. Start D-Bus and keyring daemon ───
+echo "  ── Step 4: Start D-Bus session and keyring daemon ──"
+echo ""
+
+# Ensure D-Bus is available
+if [[ -z "${DBUS_SESSION_BUS_ADDRESS:-}" ]]; then
+  echo "  Starting D-Bus session..."
+  eval $(dbus-launch --sh-syntax)
+  echo "  ✅ D-Bus session started."
+else
+  echo "  ✅ D-Bus session already active."
+fi
+
+# Kill stale keyring daemons (leftover --unlock processes, etc.)
+STALE_COUNT=$(pgrep -u "$USER" gnome-keyring-daemon 2>/dev/null | wc -l)
+if [[ "$STALE_COUNT" -gt 1 ]]; then
+  echo "  Cleaning up $STALE_COUNT stale keyring daemon processes..."
+  pkill -9 -u "$USER" gnome-keyring-daemon 2>/dev/null || true
+  sleep 2
+fi
+
+# Start the daemon via --start (D-Bus activated, stays resident)
+# Note: on headless, the daemon may be D-Bus activated on demand rather than
+# staying resident. This is normal — secret-tool and @napi-rs/keyring will
+# trigger D-Bus activation automatically when they query the Secret Service.
+echo "  Starting gnome-keyring-daemon..."
+eval $(gnome-keyring-daemon --start --components=secrets 2>&1 | grep -v '^\*\*') || true
+sleep 1
+
+if pgrep -u "$USER" gnome-keyring-daemon >/dev/null 2>&1; then
+  echo "  ✅ Keyring daemon running."
+else
+  # On D-Bus activated systems, the daemon starts on demand — verify by querying
+  if command -v secret-tool >/dev/null 2>&1; then
+    secret-tool search --all service algorand-mcp 2>/dev/null && echo "  ✅ Keyring daemon available (D-Bus activated)." || true
+  fi
+  echo "  ℹ️  Daemon is D-Bus activated (starts on demand when queried)."
+fi
+echo ""
+
+# ─── 4f. Create persistent login keyring collection ───
+KEYRING_FILE="$KEYRING_DIR/login.keyring"
+mkdir -p "$KEYRING_DIR"
+
+echo "  ── Step 5: Create persistent keyring ──"
+echo ""
+
+if [[ -f "$KEYRING_FILE" ]]; then
+  echo "  ✅ Keyring already exists at $KEYRING_FILE"
+else
+  # On headless Linux, gnome-keyring-daemon refuses to create a collection
+  # via normal prompts (no GUI). We use the D-Bus internal interface
+  # CreateWithMasterPassword to create the "login" collection with an
+  # empty master password — making it auto-unlocked and persistent on disk.
+  echo "  Creating login keyring collection via D-Bus..."
+
+  python3 << 'PYEOF'
+import sys
+try:
+    from jeepney import new_method_call, DBusAddress
+    from jeepney.io.blocking import open_dbus_connection
+
+    conn = open_dbus_connection(bus='SESSION')
+
+    # Open a plain-text session with the Secret Service
+    msg = new_method_call(
+        DBusAddress('/org/freedesktop/secrets',
+                    bus_name='org.freedesktop.secrets',
+                    interface='org.freedesktop.Secret.Service'),
+        'OpenSession',
+        'sv',
+        ('plain', ('s', ''))
+    )
+    reply = conn.send_and_get_reply(msg)
+    session_path = reply.body[1]
+
+    # Create the "login" collection with empty master password
+    # Uses the internal gnome-keyring interface (bypasses GUI prompt)
+    props = {
+        'org.freedesktop.Secret.Collection.Label': ('s', 'login')
+    }
+    master_password = (session_path, b'', b'', 'text/plain')
+
+    msg = new_method_call(
+        DBusAddress('/org/freedesktop/secrets',
+                    bus_name='org.gnome.keyring',
+                    interface='org.gnome.keyring.InternalUnsupportedGuiltRiddenInterface'),
+        'CreateWithMasterPassword',
+        'a{sv}(oayays)',
+        (props, master_password)
+    )
+    reply = conn.send_and_get_reply(msg)
+    print(f"  Collection created: {reply.body[0]}")
+    conn.close()
+except Exception as e:
+    print(f"  Error: {e}", file=sys.stderr)
+    sys.exit(1)
+PYEOF
+
+  if [[ $? -eq 0 && -f "$KEYRING_FILE" ]]; then
+    echo "  ✅ Persistent keyring created at $KEYRING_FILE"
+  else
+    FOUND_FILE=$(ls "$KEYRING_DIR"/*.keyring 2>/dev/null | head -1 || true)
+    if [[ -n "$FOUND_FILE" ]]; then
+      echo "  ✅ Persistent keyring created at $FOUND_FILE"
+    else
+      echo "  ⚠️  Keyring file not created. Ensure python3 and jeepney are installed."
+      echo "     Install with: pip3 install jeepney"
+    fi
+  fi
+fi
+echo ""
+
+# ─── 4g. Restore backed-up wallet mnemonics (UPDATE scenario only) ───
+if [[ -n "$BACKUP_FILE" && -f "$BACKUP_FILE" && -s "$BACKUP_FILE" ]]; then
+  echo "  ── Step 6: Restore wallet mnemonics ──"
+  echo ""
+
+  RESTORE_RESULT=$(NODE_PATH="$NODE_MODULES" node "$BACKUP_SCRIPT" restore "$BACKUP_FILE" 2>&1)
+  echo "  $RESTORE_RESULT"
+
+  # Securely delete backup
+  shred -u "$BACKUP_FILE" 2>/dev/null || rm -f "$BACKUP_FILE"
+  echo "  ✅ Temporary backup securely deleted."
+  echo ""
+fi
+
+# ─── 4h. Docker-specific guidance ───
+if [[ "$IN_CONTAINER" == "true" ]]; then
+  echo "  ── Docker / Container Notes ──"
+  echo ""
+  echo "  Add to your Dockerfile:"
+  echo "    RUN apt-get update && apt-get install -y \\"
+  echo "        gnome-keyring libsecret-tools dbus-user-session \\"
+  echo "        && rm -rf /var/lib/apt/lists/*"
+  echo ""
+  echo "  Entrypoint wrapper (entrypoint.sh):"
+  echo '    #!/bin/bash'
+  echo '    export $(dbus-launch)'
+  echo '    eval $(gnome-keyring-daemon --start --components=secrets)'
+  echo '    # Create login collection if not exists (headless — no GUI prompt)'
+  echo '    if [ ! -f ~/.local/share/keyrings/login.keyring ]; then'
+  echo '      python3 -c "'
+  echo '        from jeepney import new_method_call, DBusAddress'
+  echo '        from jeepney.io.blocking import open_dbus_connection'
+  echo '        conn = open_dbus_connection(bus=\"SESSION\")'
+  echo '        r = conn.send_and_get_reply(new_method_call(DBusAddress(\"/org/freedesktop/secrets\",bus_name=\"org.freedesktop.secrets\",interface=\"org.freedesktop.Secret.Service\"),\"OpenSession\",\"sv\",(\"plain\",(\"s\",\"\"))))'
+  echo '        s = r.body[1]'
+  echo '        conn.send_and_get_reply(new_method_call(DBusAddress(\"/org/freedesktop/secrets\",bus_name=\"org.gnome.keyring\",interface=\"org.gnome.keyring.InternalUnsupportedGuiltRiddenInterface\"),\"CreateWithMasterPassword\",\"a{sv}(oayays)\",({\"org.freedesktop.Secret.Collection.Label\":(\"s\",\"login\")},(s,b\"\",b\"\",\"text/plain\"))))'
+  echo '        conn.close()'
+  echo '      "'
+  echo '    fi'
+  echo '    exec "$@"'
+  echo ""
+  echo "  Persist keyring + wallet data (docker-compose.yml):"
+  echo "    volumes:"
+  echo "      - keyring-data:/home/user/.local/share/keyrings"
+  echo "      - wallet-data:/home/user/.algorand-mcp"
+  echo ""
+fi
+
+# ─── 4i. Final verification ───
+echo "  ── Results ──"
+echo ""
+
+# Re-check
+VERIFY_RUNNING=false
+pgrep -u "$USER" gnome-keyring-daemon >/dev/null 2>&1 && VERIFY_RUNNING=true
+
+VERIFY_FILES=false
+[[ -d "$KEYRING_DIR" && "$(ls -A "$KEYRING_DIR" 2>/dev/null)" ]] && VERIFY_FILES=true
+
+if [[ "$VERIFY_RUNNING" == "true" ]]; then
+  echo "  ✅ Daemon:      Running"
+else
+  echo "  ✅ Daemon:      D-Bus activated (starts on demand)"
+fi
+
+if [[ "$VERIFY_FILES" == "true" ]]; then
+  echo "  ✅ Persistent:  Yes (files at $KEYRING_DIR)"
+else
+  echo "  ⚠️  Persistent:  No keyring files yet"
+fi
+
+# Verify wallet mnemonics via Node.js
+if [[ -f "$BACKUP_SCRIPT" && "$WALLET_DB_EXISTS" == "true" ]]; then
+  VERIFY_RESULT=$(NODE_PATH="$NODE_MODULES" node "$BACKUP_SCRIPT" verify 2>/dev/null | tail -1)
+  echo "  ✅ Wallets:     $VERIFY_RESULT"
+fi
+
+echo ""
+echo "  Behavior after setup:"
+echo "    • Keyring stored on disk, auto-unlocked on boot via D-Bus activation"
+echo "    • loginctl linger keeps D-Bus session alive between SSH sessions"
+echo "    • Wallet keys persist across reboots — no user interaction needed"
+echo "    • Keep agent wallet funds minimal — use QR code top-ups as needed"
+echo ""

package/setup.ts

@@ -1,7 +1,11 @@
 import * as p from "@clack/prompts";
-// import { execSync } from "node:child_process";
+import { execSync } from "node:child_process";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { ALGORAND_MCP, GOPLAUSIBLE_SERVICES } from "./lib/mcp-servers.js";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
 export interface AlgorandPluginConfig {
   enableX402: boolean;
 }
@@ -11,34 +15,14 @@ export async function runSetup(
 ): Promise<AlgorandPluginConfig | null> {
   p.intro("🔷 Algorand Plugin Setup — powered by GoPlausible");
 
-  // // Step 1: Verify algorand-mcp binary is available
-  // let mcpAvailable = false;
-  // let mcpPath = "";
-  // try {
-  //   mcpPath = execSync("npm list @goplausible/algorand-mcp", { encoding: "utf-8" }).trim();
-  //   mcpAvailable = true;
-  // } catch {
-  //   // Binary not found in PATH
-  // }
-
-  // if (mcpAvailable) {
-  //   p.note(
-  //     `MCP Server: ${ALGORAND_MCP.name}\n` +
-  //       `Type: ${ALGORAND_MCP.type} (local)\n` +
-  //       `Command: ${ALGORAND_MCP.command}\n` +
-  //       `Path: ${mcpPath}\n` +
-  //       `Status: ✅ Available`,
-  //     "Algorand MCP"
-  //   );
-  // } else {
-  //   p.log.warn(
-  //     `algorand-mcp binary not found in PATH.\n\n` +
-  //       `Options:\n` +
-  //       `  • Run with npx: npx algorand-mcp\n` +
-  //       `  • Install globally: npm install -g @goplausible/algorand-mcp\n` +
-  //       `  • Add node_modules/.bin to PATH`
-  //   );
-  // }
+  // Step 1: Keyring persistence check & setup
+  p.log.step("Checking keyring persistence for wallet storage...");
+  try {
+    const scriptPath = join(__dirname, "scripts", "setup-keyring.sh");
+    execSync(`bash "${scriptPath}" --setup`, { stdio: "inherit" });
+  } catch {
+    p.log.warn("Keyring setup script failed — you may need to configure manually.");
+  }
 
   // Step 2: x402 integration
   const enableX402 = await p.confirm({
@@ -59,7 +43,7 @@ export async function runSetup(
   p.note(
     `x402 Micropayments: ${config.enableX402 ? "Enabled" : "Disabled"}\n\n` +
       `MCP Server Setup:\n` +
-      `  The Algorand MCP server (${ALGORAND_MCP.command}) provides 99 blockchain tools.\n` +
+      `  The Algorand MCP server (${ALGORAND_MCP.command}) provides 107 blockchain tools.\n` +
       `  x402 micropayment and AP2 mandate verifiable credentials flows are fully supported in Algorand MCP.\n` ,
   );
 

package/skills/algorand-interaction/SKILL.md

@@ -43,8 +43,8 @@ Key points:
 
 1. **Check wallet**: `wallet_get_info` with target `network` — verify an account exists and is active
 2. **If no accounts**: Guide user to create one with `wallet_add_account` (sets nickname and spending limits)
-3. **If needs funding**: Generate ARC-26 QR with `generate_algorand_uri` or direct to testnet faucet: https://lora.algokit.io/testnet/fund
-4. **If needs USDC funding**: Generate ARC-26 QR with `generate_algorand_uri` or direct to testnet faucet: https://faucet.circle.com/
+3. **If needs funding**: Generate ARC-26 QR with `generate_algorand_qrcode` or direct to testnet faucet: https://lora.algokit.io/testnet/fund
+4. **If needs USDC funding**: Generate ARC-26 QR with `generate_algorand_qrcode` or direct to testnet faucet: https://faucet.circle.com/
 5. **Confirm network**: Always confirm which network (`mainnet`, `testnet`, `localnet`) before transactions
 
 ## Network Selection
@@ -164,7 +164,7 @@ For atomic (all-or-nothing) multi-transaction groups:
 
 **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`
+**ARC-26 URI** (1): `generate_algorand_qrcode`
 
 **Knowledge Base** (1): `get_knowledge_doc`
 
@@ -209,6 +209,31 @@ All prices and quantities use **microunits** (1,000,000 = $1.00 or 1 share). Ord
 
 > For detailed Alpha Arcade workflows (orderbook mechanics, multi-choice markets, split/merge shares, claiming, collateral model), load the `alpha-arcade-interaction` skill.
 
+## QR Code Display (ARC-26 URI)
+
+When generating QR codes with `generate_algorand_qrcode`, the tool returns:
+- UTF-8 text QR code (terminal-friendly)
+- PNG image as base64 (web-friendly)
+- URI string
+
+**Important:** MCP tool output may not render properly through mcporter → exec pipeline.
+After calling the tool, **extract and paste the QR code directly in your response**:
+
+1. Call the tool and capture output
+2. Extract the UTF-8 QR block (Unicode block characters)
+3. Extract the base64 PNG data
+4. Include both in your reply:
+
+```
+[paste UTF-8 QR here]
+```
+
+![QR Code](data:image/png;base64,[paste base64 here])
+
+URI: `algorand://ADDRESS?amount=X&asset=Y`
+
+This ensures the QR renders correctly in both terminal and web interfaces.
+
 ## References
 
 For detailed tool documentation:

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

@@ -782,20 +782,40 @@ Mainnet asset verification via Pera Wallet API. Use to check if assets are legit
 
 ## ARC-26 URI Tools
 
-### generate_algorand_uri
-- **Purpose**: Generate an Algorand payment URI and QR code per ARC-26 specification
+### generate_algorand_qrcode
+- **Purpose**: Generate an Algorand top up payment or asset transferURI and QR code per ARC-26 specification
 - **Parameters**:
 ```json
 {
   "address": "receiver_address",
   "label": "Payment label",
   "amount": 1000000,
-  "asset": 31566704,
+  "asset": 31566704,// optional, if asset transfer; omit or set to 0 for ALGO
   "note": "Payment note",
-  "xnote": "Exclusive note"
+  "xnote": "Exclusive immutable note"
 }
 ```
-- **Returns**: URI string + SVG QR code
+- **Returns**: UTF-8 text QR code (terminal-friendly), PNG image as base64 (web-friendly), URI string
+
+### QR Code Display
+
+**Important:** MCP tool output may not render properly through mcporter → exec pipeline.
+After calling the tool, **extract and paste the QR code directly in your response**:
+
+1. Call the tool and capture output
+2. Extract the UTF-8 QR block (Unicode block characters)
+3. Extract the base64 PNG data
+4. Include both in your reply:
+
+```
+[paste UTF-8 QR here]
+```
+
+![QR Code](data:image/png;base64,[paste base64 here])
+
+URI: `algorand://ADDRESS?amount=X&asset=Y`
+
+This ensures the QR renders correctly in both terminal and web interfaces.
 
 ---
 

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

@@ -23,7 +23,7 @@ wallet_add_account {
 
 ### Step 3: If account needs funding
 ```
-generate_algorand_uri {
+generate_algorand_qrcode {
   "address": "[wallet_address]",
   "amount": 5000000,
   "note": "Fund testnet account"
@@ -33,7 +33,7 @@ Or direct user to: https://lora.algokit.io/testnet/fund
 
 ### Step 4: If account needs USDC funding
 ```
-generate_algorand_uri {
+generate_algorand_qrcode {
   "address": "[wallet_address]",
   "asset": 10458941, // USDC on testnet
   "amount": 1000000, // 1 USDC with 6 decimals
@@ -599,7 +599,7 @@ send_raw_transaction {
 When balance is insufficient, generate an ARC-26 QR code for easy funding:
 
 ```
-generate_algorand_uri {
+generate_algorand_qrcode {
   "address": "[wallet_address]",
   "amount": 5000000,
   "note": "Fund account for transaction"