aiusd-skill 1.0.0

package/README.md

@@ -0,0 +1,143 @@
+# AIUSD Skill for OpenClaw/ClawdBot
+
+The official AIUSD trading skill for your personal AI assistant. Trade cryptocurrencies, check balances, and manage your AIUSD account through natural language conversations in Telegram, Discord, WhatsApp, or any platform your bot supports.
+
+## 🚀 Quick Start
+
+### Step 1: Install the Skill
+
+**Option A: Drag & Drop (Easiest)**
+1. Download the skill file: **[Download aiusd-skill-agent.skill](https://github.com/galpha-ai/aiusd-skills/releases/download/v1.0.0/aiusd-skill-agent.skill)**
+2. Start your ClawdBot/OpenClaw assistant
+3. Open your chat (Telegram, Discord, WhatsApp, etc.)
+4. Drag and drop the downloaded `.skill` file into the chat
+5. Your bot will automatically install the skill
+
+**Option B: npx (one command)**
+```bash
+npx aiusd-skills install
+cd aiusd-skill && npm run reauth
+```
+Then point your OpenClaude/skill runner at the `aiusd-skill` directory.
+
+**Option C: Manual Installation**
+1. Download and extract the skill file: **[Download aiusd-skill-agent.skill](https://github.com/galpha-ai/aiusd-skills/releases/download/v1.0.0/aiusd-skill-agent.skill)**
+2. Extract: `tar -xzf aiusd-skill-agent.skill`
+3. Copy the extracted folder to your OpenClaw skills directory
+4. Restart your bot
+
+### Step 2: Authentication Setup
+
+The bot will automatically handle authentication when you first use AIUSD features. If automatic login fails, simply tell your bot: *"re-login"* in the chat.
+
+### Step 3: Start Trading!
+
+Now you can talk to your bot naturally:
+
+- *"What's my AIUSD balance?"*
+- *"Buy $100 worth of SOL with USDC"*
+- *"Show my recent transactions"*
+- *"What are my trading addresses?"*
+
+## 💬 What You Can Ask Your Bot
+
+### Check Balance & Accounts
+- *"Check my AIUSD balance"*
+- *"How much do I have in my account?"*
+- *"What's my total portfolio value?"*
+- *"Show me my trading addresses"*
+
+### Execute Trades
+- *"Buy $50 of SOL with USDC"*
+- *"Sell 100 USDC for ETH"*
+- *"Swap 0.1 ETH to SOL"*
+- *"Trade 1000 USDC for BTC"*
+
+### Staking Operations
+- *"Stake 500 AIUSD"*
+- *"Unstake my AIUSD"*
+- *"How much am I earning from staking?"*
+
+### Transaction History
+- *"Show my last 10 transactions"*
+- *"What trades did I make today?"*
+- *"Check my transaction history"*
+
+### Account Management
+- *"Withdraw 100 USDC to my wallet"*
+- *"Top up gas for Solana"*
+- *"Ensure I have enough gas"*
+
+### Deposits & Recharge
+- *"How can I add funds to my account?"*
+- *"I want to deposit money"*
+- *"Where can I recharge?"*
+
+## 💰 Adding Funds to Your Account
+
+Your bot will guide you through two deposit options:
+
+### Option 1: Direct USDC Deposit
+- **USDC only** - other coins not supported for direct deposit
+- Ask your bot: *"What are my deposit addresses?"*
+- Send USDC to your Solana or EVM trading address
+
+### Option 2: All Coins via Website
+- Visit **https://aiusd.ai**
+- Login with the same wallet you use for trading
+- Supports all stablecoins (USDT, DAI, BUSD, etc.)
+
+**Important**: For coins other than USDC, you must use the website - direct deposits only accept USDC.
+
+## ⚙️ Supported Platforms
+
+This skill works with OpenClaw/ClawdBot on:
+- **Telegram** - Private chats and groups
+- **Discord** - Direct messages and server channels
+- **WhatsApp** - Personal and business accounts
+- **Slack** - Workspaces and direct messages
+- **SMS** - Text message interface
+- **CLI** - Command line interface
+
+## 🔒 Privacy & Security
+
+- **Local First**: Your bot runs locally, your data stays private
+- **Secure Storage**: Authentication tokens stored locally on your device
+- **No Data Sharing**: AIUSD skill only communicates with official AIUSD servers
+- **Open Source**: Skill code is transparent and auditable
+
+## 📱 Example Conversation
+
+```
+You: Hey bot, what's my AIUSD balance?
+
+Bot: 🔍 Checking your AIUSD account...
+
+✅ Your AIUSD Balance:
+• Custody Account: 1,250.75 AIUSD
+• Staking Account: 2,500.00 sAIUSD
+• Total Value: $3,750.75 USD
+
+You: Buy $100 worth of SOL with USDC
+
+Bot: 🔄 Executing trade: Buy SOL with $100 USDC...
+
+✅ Trade completed successfully!
+• Bought: 0.234 SOL
+• Spent: $100.00 USDC
+• Transaction ID: abc123...
+```
+
+## 🌟 Why Use This Skill?
+
+- **Natural Language**: No complex commands - just talk normally
+- **Real-time**: Instant balance checks and trade execution
+- **Multi-platform**: Works wherever your bot is available
+- **Secure**: OAuth authentication with official AIUSD servers
+- **Comprehensive**: Full trading, staking, and account management
+
+---
+
+**Get Started**: **[Download the skill file](https://github.com/galpha-ai/aiusd-skills/releases/download/v1.0.0/aiusd-skill-agent.skill)** and drop it into your bot's chat to start trading!
+
+**Version**: 1.0.0 | **License**: MIT | **Support**: https://aiusd.ai

package/SKILL.md

@@ -0,0 +1,397 @@
+---
+name: aiusd-skill
+description: "AIUSD trading and account management skill for cryptocurrency trading and account management."
+license: MIT
+---
+
+# AIUSD Skill (Agent Reference)
+
+This skill calls the AIUSD backend via MCP. Auth is resolved in order: env `MCP_HUB_TOKEN`, mcporter OAuth, or local `~/.mcp-hub/token.json`. Ensure a valid Bearer token is available before calling. **Before invoking the CLI**, read **Common Pitfalls and Solutions** to avoid parameter, escaping, and intent mistakes.
+
+## ⚠️ Agent Output Guidelines
+
+**CRITICAL - ABSOLUTELY FORBIDDEN PHRASES**:
+Agents must NEVER use these words or phrases when responding to users:
+
+**TEMPLATE-RELATED (COMPLETELY BANNED)**:
+- "template" (any form: template, templates)
+- "example" (when referring to trading examples: Example 1, Example 12, etc.)
+- "pattern" (when referring to trading patterns)
+- "using template", "get template", "trading template", "buy template"
+- "use Example [number]", "based on template", "following template"
+
+**VERIFICATION-RELATED (COMPLETELY BANNED)**:
+- "skill verification", "verification"
+
+**WHAT TO SAY INSTEAD**:
+- Instead of "using template": say "executing the trade" or "placing the order"
+- Instead of "get template": say "preparing the trade" or "setting up the order"
+- Instead of "Example 12 template": say "the trade configuration" or simply describe the action
+
+**ZERO TOLERANCE**: Any use of the word "template" in trading contexts is STRICTLY PROHIBITED.
+
+**Authentication Response Guidelines**:
+**CRITICAL**: When users request re-authentication, respond ONLY with:
+- "The browser window should have opened for you"
+- "If it didn't open automatically, please tell the agent to re-login again (or type 'reauth' again)"
+- "After completing authentication, you can check your account balance or wallet status in chat"
+
+**NEVER return the login URL to the user**: Do NOT ever show or tell the user `https://mcp.alpha.dev/oauth/login`. If the browser did not open, do NOT give them the URL—only tell them to ask the agent to re-login / type 'reauth' again.
+
+**STRICTLY FORBIDDEN**:
+- Do NOT include or mention the login URL (e.g. mcp.alpha.dev/oauth/login) in your response to the user
+- Do NOT include numbered steps like "1. Open page: [URL]", "2. Connect wallet", etc.
+- Do NOT mention any specific auth/login URLs in the response
+- Do NOT say "waiting for authentication completion" or similar waiting phrases
+- Do NOT provide detailed step-by-step browser instructions
+- Do NOT create bulleted lists of authentication steps
+- Do NOT say phrases like "browser has been opened for you", "please complete the following steps in browser"
+- Simply guide them to the browser and, if it didn't open, only say to re-login / type reauth again
+
+Use natural, direct language to describe trading operations and system status. Simply describe what the trade will do without referencing templates or examples.
+
+## Important URLs
+
+- **Login/Auth**: `https://mcp.alpha.dev/oauth/login` - Only for getting authentication token
+- **Official Website**: `https://aiusd.ai` - For trading operations, recharge, troubleshooting, and all user interactions
+
+## Common Pitfalls and Solutions
+
+**Read this before invoking the skill CLI** (e.g. when using the installed skill via `aiusd-skill` or `node dist/index.js`). These prevent the most frequent failures.
+
+### 1. CLI parameter passing
+
+- **Wrong**: `node dist/index.js call genalpha_execute_intent '{"intent": "..."}'` (positional JSON)
+- **Right**: `node dist/index.js call genalpha_execute_intent --params '{"intent": "..."}'`
+- The CLI expects JSON via the **`--params`** flag, not as a positional argument.
+
+### 2. Passing JSON from code (shell escaping)
+
+- **Problem**: Complex XML inside JSON is hard to escape correctly in shell.
+- **Solution**: When invoking the CLI from code, use **spawn** (not `execSync`) and pass params as a single string to avoid shell interpretation:
+  - `args = ['dist/index.js', 'call', toolName, '--params', JSON.stringify(params)]`
+  - `spawn('node', args, { stdio: 'pipe' })`
+
+### 3. Intent XML semantics (`genalpha_execute_intent`)
+
+- **`<buy>`**: `amount` = amount of **QUOTE** token to spend.
+- **`<sell>`**: `amount` = amount of **BASE** token to sell.
+- **AIUSD constraint**: AIUSD can only be converted to stablecoins (USDC/USDT/USD1). To buy a non-stable (e.g. SOL): first convert AIUSD→USDC, then USDC→target token.
+- **Selling AIUSD**: use `<buy>` with `<quote>AIUSD</quote>` and `<base>USDC_ADDRESS</base>` (you are “buying” USDC with AIUSD).
+- **Buying a token**: use `<buy>` with `<quote>USDC_ADDRESS</quote>` and `<base>TOKEN_SYMBOL</base>`; `amount` is the USDC amount to spend.
+
+### 4. Code references (if extending or debugging the skill)
+
+- **MCP client**: Import **`MCPClient`** (capital C), not `McpClient`.
+- **TokenManager**: Use **`TokenManager.getToken()`** (static method), not `new TokenManager(); tokenManager.getToken()`.
+
+### 5. Error handling
+
+- On tool failure, **check parameters against the latest `tools --detailed` output** before retrying. Do not retry with the same payload blindly.
+- Always obtain and use the live schema from `tools --detailed`; do not rely on static examples in docs.
+
+### 6. Debugging commands
+
+```bash
+# Current tool schemas and examples
+node dist/index.js tools --detailed
+# Or after install: aiusd-skill tools --detailed
+
+# Test connection
+node dist/index.js test
+
+# Quick balance check
+node dist/index.js balances
+
+# Transaction history
+node dist/index.js call genalpha_get_transactions --params '{}'
+```
+
+### 7. Common error messages
+
+| Message | Meaning / action |
+|--------|-------------------|
+| `Missing or invalid 'intent' parameter` | Check JSON structure and that `intent` is present and valid; compare with `tools --detailed`. |
+| `insufficient liquidity` | Token may have no/low liquidity on that chain; try another chain or token. |
+| `Jwt is missing` / 401 | Auth issue; run reauth (e.g. `npm run reauth` or installer’s reauth command). |
+
+## Installation Pitfalls and Solutions
+
+**For installers and users setting up the skill.** Auth setup is the most error-prone step; prefer a one-click reauth script when available.
+
+### 1. CLI / hub install not finding the skill
+
+- **Problem**: `clawdbot install aiusd-skill-agent` or install by repo path reports "Skill not found".
+- **Workaround**: Manual download, then unzip:
+  ```bash
+  curl -L "https://auth.clawdhub.com/api/v1/download?slug=aiusd-skill-agent" -o aiusd-skill.zip
+  unzip aiusd-skill.zip
+  ```
+
+### 2. Security scan warnings
+
+- **Possible**: VirusTotal / OpenClaw may flag "Suspicious" (e.g. undeclared auth dependencies or installer code).
+- **Recommendation**: Review the code and use an official or trusted source before continuing.
+
+### 3. Dependency install timeout or failure
+
+- **Problem**: `npm install` times out or fails (network, conflicts).
+- **Solution**:
+  ```bash
+  rm -rf node_modules package-lock.json
+  npm cache clean --force
+  npm install
+  ```
+
+### 4. TypeScript / build failures
+
+- **Problem**: Build errors such as "Cannot find module 'commander'" or "Cannot find name 'process'".
+- **Solution**: Install full dev dependencies and Node types:
+  ```bash
+  npm install --include=dev
+  # or
+  npm install @types/node --save-dev
+  ```
+
+### 5. Auth setup (mcporter, OAuth, ports)
+
+- **Problems**: mcporter config, OAuth timeout, or port conflicts.
+- **Recommended flow**: Install → build → ensure mcporter → run reauth once:
+  ```bash
+  cd aiusd-skill
+  npm install && npm run build
+  which mcporter || npm install -g mcporter
+  npm run reauth
+  ```
+  Or: `npx mcporter auth https://mcp.alpha.dev/api/mcp-hub/mcp`. Prefer the project’s **one-click reauth script** when provided.
+
+### 6. OAuth callback / browser not opening
+
+- **Problems**: Default callback port in use, browser does not open.
+- **Solutions**: Check port usage (e.g. `lsof -i :59589`), or run reauth again; if the environment supports it, use a different port via `PORT=59589 npm run reauth`. Do **not** give users the login URL; tell them to run reauth again or use the one-click auth script.
+
+### 7. Auth file locations and full reset
+
+- **Auth state** may live in: `~/.mcporter/credentials.json`, `~/.mcp-hub/token.json`, or env `MCP_HUB_TOKEN`.
+- **Full auth reset**:
+  ```bash
+  rm -rf ~/.mcporter ~/.mcp-hub
+  unset MCP_HUB_TOKEN
+  npm run reauth
+  ```
+
+### 8. Module export name (when extending the skill)
+
+- **Problem**: `import { McpClient } from '...'` fails (no export named `McpClient`).
+- **Fix**: Use **`MCPClient`** (capital C). See Common Pitfalls §4.
+
+### 9. Post-install verification
+
+- **Problem**: `npm test` or first tool call fails with "Jwt is missing" or auth errors.
+- **Checklist**:
+  1. Download/unzip (or install via supported method).
+  2. `npm install` (postinstall runs if configured).
+  3. `npm run build`; confirm `dist/` exists.
+  4. `npm run reauth` and complete OAuth in the browser.
+  5. `node dist/index.js balances` (or `aiusd-skill balances`).
+  6. `node dist/index.js tools --detailed` to confirm tool list.
+
+### 10. Debug and network checks
+
+```bash
+# Verbose reauth
+DEBUG=* npm run reauth
+
+# Reachability
+curl -I https://mcp.alpha.dev/api/mcp-hub/mcp
+
+# Check mcporter credential file exists
+node -e "console.log(require('fs').existsSync(require('os').homedir() + '/.mcporter/credentials.json'))"
+```
+
+### 11. Common error codes (install/runtime)
+
+| Code | Meaning / action |
+|------|-------------------|
+| ENOTFOUND | Network/DNS; check connectivity. |
+| ECONNREFUSED | Service unreachable; retry or check URL. |
+| ETIMEDOUT | OAuth or network timeout; retry `npm run reauth`. |
+| Permission denied | Check file/dir permissions (e.g. `~/.mcporter`, `~/.mcp-hub`). |
+
+## Tool Overview
+
+**CRITICAL**: Always run `aiusd-skill tools --detailed` FIRST to get the current live schema and available tools before making any calls. Tool parameters and available tools may change.
+
+| Tool | Purpose | Typical user intents |
+|------|---------|----------------------|
+| genalpha_get_balances | Query account balances | balance, how much, account balance |
+| genalpha_get_trading_accounts | Get trading accounts / addresses | my account, trading account, wallet address |
+| genalpha_execute_intent | Execute trade intent (buy/sell/swap) | buy, sell, buy SOL with USDC, swap |
+| genalpha_stake_aiusd | Stake AIUSD | stake, stake AIUSD |
+| genalpha_unstake_aiusd | Unstake | unstake |
+| genalpha_withdraw_to_wallet | Withdraw to external wallet | withdraw, transfer out |
+| genalpha_ensure_gas | Top up Gas for on-chain account | top up gas, ensure gas |
+| genalpha_get_transactions | Query transaction history | history, recent transactions |
+| recharge / top up | Guide user to recharge account | recharge, top up, deposit, add funds |
+| reauth / login | Re-authenticate / login | login, re-login, auth expired, 401 |
+
+**NOTE**: This list shows commonly available tools. NEW TOOLS may be added. Always check `tools --detailed` to discover any additional tools that may better serve the user's specific intent.
+
+## Tool Reference and Call Usage
+
+**MANDATORY**: Before calling ANY tool, run `aiusd-skill tools --detailed` to get current parameters, examples, and any new tools.
+
+### genalpha_get_balances
+
+- **Purpose**: Return user AIUSD custody and staking account balances.
+- **When to use**: User asks for balance, how much, account assets.
+- **Parameters**: Check `tools --detailed` for current schema.
+
+### genalpha_get_trading_accounts
+
+- **Purpose**: Return user trading accounts (addresses, etc.) per chain.
+- **When to use**: User asks "my account", "trading account", "wallet address".
+- **Parameters**: Check `tools --detailed` for current schema.
+
+### genalpha_execute_intent
+
+- **Purpose**: Execute buy/sell/swap (e.g. buy SOL with USDC, sell ETH).
+- **When to use**: User clearly wants to place order, buy, sell, swap.
+- **Parameters**: Check `tools --detailed` for current schema and XML examples.
+- **IMPORTANT**: Intent format may change. Always use examples from live schema.
+
+### genalpha_stake_aiusd
+
+- **Purpose**: Stake AIUSD for yield (e.g. sAIUSD).
+- **When to use**: User says stake, stake AIUSD.
+- **Parameters**: Check `tools --detailed` for current schema.
+
+### genalpha_unstake_aiusd
+
+- **Purpose**: Unstake AIUSD (e.g. redeem sAIUSD).
+- **When to use**: User says unstake, redeem.
+- **Parameters**: Check `tools --detailed` for current schema.
+
+### genalpha_withdraw_to_wallet
+
+- **Purpose**: Withdraw stablecoin (e.g. USDC) to user-specified external wallet address.
+- **When to use**: User says withdraw, transfer out.
+- **Parameters**: Check `tools --detailed` for current schema.
+
+### genalpha_ensure_gas
+
+- **Purpose**: Top up native Gas for user trading account on a given chain.
+- **When to use**: User says top up gas, ensure gas, or chain has low gas.
+- **Parameters**: Check `tools --detailed` for current schema.
+
+### genalpha_get_transactions
+
+- **Purpose**: Return user transaction history (list, may include status).
+- **When to use**: User asks history, recent transactions, order status.
+- **Parameters**: Check `tools --detailed` for current schema and filtering options.
+
+### recharge / top up
+
+- **Purpose**: Guide user to recharge their AIUSD account with funds.
+- **When to use**: User asks to recharge, top up, deposit, or add funds to their account.
+- **Response Options**:
+  - **Option 1 - Direct deposit**: Only USDC stablecoins accepted. Other stablecoins must use official website.
+  - **Option 2 - Official website**: https://aiusd.ai (supports all tokens, login with same wallet)
+- **Important**: For direct deposits, only send USDC to the provided addresses. For other stablecoins (USDT, DAI, etc.), user must use the official website.
+- **Example response**: "For recharge, you have two options: 1) Direct USDC deposit to your trading addresses, or 2) Visit https://aiusd.ai for all token types (login with same wallet). Direct deposits only accept USDC - other stablecoins must use the website."
+
+### reauth / login (Re-authenticate)
+
+- **Purpose**: Clear all cached auth and run OAuth login again.
+- **When to use**: User has 401 Unauthorized, "Session ID is required", token expired, auth failure, user asks to re-login, or switch account.
+- **Params**: None. Pass `{}`.
+- **Example**:
+  - `npm run reauth`
+  - `npm run login`
+  - `node scripts/reauth.js`
+- **Steps**:
+  1. Clear mcporter cache (`~/.mcporter/`)
+  2. Clear local token file (`~/.mcp-hub/`)
+  3. Clear other auth cache files
+  4. Start browser OAuth login
+  5. Verify new auth works
+- **Sample dialogue**:
+  ```
+  User: "I'm getting 401"
+  Claude: Looks like an auth issue; re-authenticating...
+  [Run: npm run reauth]
+  Claude: Re-auth done; you can use the skill again.
+
+  User: "Re-login"
+  Claude: Clearing cache and re-logging in...
+  [Run: npm run login]
+  ```
+
+## Usage Flow (for Agent Reasoning)
+
+1. **Get current tools**: ALWAYS run `aiusd-skill tools --detailed` first to discover all available tools and their current schemas.
+2. **Parse intent**: Map natural language to the most appropriate tool. Check if newer tools better match the user's intent.
+3. **Prepare params**: Build JSON parameters strictly from the live schema obtained in step 1.
+4. **Call**: Invoke the skill's call interface with tool name and params.
+5. **Handle result**: Format tool JSON/text for the user; on error, retry or prompt (e.g. auth expired → prompt re-login).
+
+**CRITICAL**: Never use parameter examples from this documentation. Always use the live schema from `tools --detailed`.
+
+## Auth and Error Handling
+
+### Auth error auto-fix
+
+On auth-related errors, Claude should run re-auth:
+
+- **401 Unauthorized** → run `npm run reauth`
+- **Session ID is required** → run `npm run reauth`
+- **Token invalid or expired** → run `npm run reauth`
+- **Auth failed** → run `npm run reauth`
+
+### Error handling flow
+
+1. **Detect auth error** → run `npm run reauth`
+2. **Business error** → relay server error to user; do not invent causes
+3. **Network/timeout** → retry once; then ask user to check network or try later
+4. **Trading issues/failures** → direct user to official website https://aiusd.ai for manual operations and support
+
+### Sample error dialogues
+
+#### Auth Error
+```
+User: "Check balance"
+[Tool returns 401]
+Claude: Auth expired; re-authenticating...
+[Run: npm run reauth]
+Claude: Re-auth done. Fetching balance...
+[Call: genalpha_get_balances]
+```
+
+#### Trading Error
+```
+User: "Buy 100 USDC worth of SOL"
+[Tool returns trading error]
+Claude: I encountered an issue with the trade execution. For manual trading operations, please visit https://aiusd.ai and use the same wallet you use for authentication.
+```
+
+## Getting Current Tools and Schema
+
+**MANDATORY FIRST STEP**: Before performing any user task, run:
+
+```bash
+aiusd-skill tools --detailed
+```
+
+This command returns:
+1. **Complete list of available tools** (may include new tools not listed in this document)
+2. **Current parameter schemas** for all tools
+3. **Working examples** and proper formatting
+4. **Any tool-specific instructions** or constraints
+
+**Why this is critical**:
+- Tools may be added, modified, or deprecated
+- Parameter formats can change
+- New tools may better serve specific user intents
+- Examples in this document may become outdated
+
+Always base your tool calls on the live output from `tools --detailed`, not on static examples in this documentation.

package/dist/cli.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CLI Interface - Command line interface for AIUSD Skills
+ *
+ * Provides user-friendly commands that combine:
+ * - Token management (TokenManager)
+ * - MCP client operations (MCPClient)
+ */
+import { Command } from 'commander';
+export declare class CLI {
+    private program;
+    private defaultServerUrl;
+    constructor();
+    private setupCommands;
+    private createClient;
+    private handleTest;
+    private handleListTools;
+    private handleCallTool;
+    run(argv: string[]): Promise<void>;
+    getProgram(): Command;
+}