From c52d4902b18e3ed30505e7bf68faadee5f386157 Mon Sep 17 00:00:00 2001 From: efren Date: Thu, 16 Apr 2026 10:01:05 -0700 Subject: [PATCH] feat: add Hermes gateway agent skills for Telegram, Discord, Slack, WhatsApp Adds four new skills that deploy the MoonPay CLI as a persistent messaging bot on each platform via the Hermes Agent gateway (NousResearch/hermes-agent). Each skill covers: Hermes install, platform bot creation, env config, MoonPay CONTEXT.md system prompt, gateway start, and error handling. Co-Authored-By: Claude Sonnet 4.6 --- skills/moonpay-discord/SKILL.md | 127 ++++++++++++++++++++++++++++ skills/moonpay-slack/SKILL.md | 140 +++++++++++++++++++++++++++++++ skills/moonpay-telegram/SKILL.md | 137 ++++++++++++++++++++++++++++++ skills/moonpay-whatsapp/SKILL.md | 140 +++++++++++++++++++++++++++++++ 4 files changed, 544 insertions(+) create mode 100644 skills/moonpay-discord/SKILL.md create mode 100644 skills/moonpay-slack/SKILL.md create mode 100644 skills/moonpay-telegram/SKILL.md create mode 100644 skills/moonpay-whatsapp/SKILL.md diff --git a/skills/moonpay-discord/SKILL.md b/skills/moonpay-discord/SKILL.md new file mode 100644 index 0000000..e0af76f --- /dev/null +++ b/skills/moonpay-discord/SKILL.md @@ -0,0 +1,127 @@ +--- +name: moonpay-discord +description: Deploy the MoonPay CLI as a Discord bot using Hermes Agent gateway. Use when the user wants to check prices, swap tokens, or manage wallets from a Discord server or DM. +tags: [gateway, messaging, automation] +--- + +# MoonPay on Discord + +Deploy a Discord bot powered by the MoonPay CLI. The bot responds in DMs and in any channel it's mentioned in. + +## Prerequisites + +- MoonPay CLI authenticated: `mp user retrieve` +- Python 3.11+: `python3 --version` +- Hermes Agent installed (see below) +- A Discord bot token (from Discord Developer Portal) + +## Install Hermes Agent + +```bash +curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash +source ~/.bashrc # or source ~/.zshrc +hermes --version +``` + +## Create a Discord bot + +1. Go to [discord.com/developers/applications](https://discord.com/developers/applications) → **New Application** +2. Name it (e.g. `MoonPay Agent`) → Create +3. Left sidebar → **Bot** → **Reset Token** → copy the token +4. Under **Privileged Gateway Intents**, enable: + - **Message Content Intent** (required to read messages) + - **Server Members Intent** (optional) +5. Left sidebar → **OAuth2 → URL Generator**: + - Scopes: `bot` + - Bot permissions: `Send Messages`, `Read Message History`, `View Channels` +6. Copy the generated URL → open in browser → add bot to your server + +## Configure Hermes + +```bash +# Write the bot token +hermes config set gateway.discord.bot_token YOUR_DISCORD_BOT_TOKEN + +# Optional: restrict to specific Discord user IDs +hermes config set gateway.discord.allowed_users 123456789012345678 + +# Or via environment variables +echo 'DISCORD_BOT_TOKEN=YOUR_DISCORD_BOT_TOKEN' >> ~/.hermes/.env +echo 'DISCORD_ALLOWED_USERS=123456789012345678' >> ~/.hermes/.env +``` + +To get your Discord user ID: Discord → Settings → Advanced → enable **Developer Mode** → right-click your name → **Copy User ID**. + +## Add MoonPay context + +```bash +mkdir -p ~/.hermes +cat > ~/.hermes/CONTEXT.md << 'EOF' +# MoonPay Agent + +You are a crypto-native AI assistant powered by the MoonPay CLI (`mp`). + +## Rules +- Prices, balances, trending tokens → always call `mp` — never guess +- Swaps require confirmation: quote first, then execute only if user says yes +- Wallet keys never leave the machine; all signing is local + +## Key commands +- `mp wallet list` — list wallets +- `mp token balance list --wallet --chain ` — portfolio +- `mp token search --query --chain solana` — find a token +- `mp token swap --wallet --chain --from-token --from-amount --to-token ` — swap +- `mp token trending list --chain solana --limit 5` — trending tokens +- `mp prediction-market market trending list --provider polymarket --limit 5` — prediction markets +- `mp buy --token sol --amount 1 --wallet --email ` — fiat buy link + +## Format +- Keep replies under 2000 characters (Discord message limit) +- Numbers: commas for thousands, up to 6 decimals for small tokens +- Prediction market prices as cents (65¢ = 65% implied probability) +EOF +``` + +## Start the gateway + +```bash +# Foreground (test first) +hermes gateway + +# Background as a persistent service +hermes gateway install +hermes gateway start +hermes gateway status +``` + +## Verify + +In Discord, DM the bot or @mention it in a channel: +``` +@MoonPayAgent what are my wallets? +``` + +Expected: the agent calls `mp wallet list` and replies with your wallet names and addresses. + +## Logs + +```bash +tail -f ~/.hermes/logs/agent.log +tail -f ~/.hermes/logs/errors.log +``` + +## Error handling + +| Error | Cause | Fix | +|-------|-------|-----| +| `discord.errors.LoginFailure` | Bad bot token | Regenerate token in Developer Portal | +| Bot doesn't read messages | Missing Message Content Intent | Enable it in Developer Portal → Bot → Intents | +| `mp: command not found` | PATH not set in service | Add `MP_PATH=$(which mp)` to `~/.hermes/.env` | +| Bot only responds in DMs | Missing channel permissions | Re-invite with correct OAuth2 permissions | + +## Related skills + +- [moonpay-auth](../moonpay-auth/) — authenticate the MoonPay CLI +- [moonpay-telegram](../moonpay-telegram/) — same setup for Telegram +- [moonpay-slack](../moonpay-slack/) — same setup for Slack +- [moonpay-swap-tokens](../moonpay-swap-tokens/) — swap command reference diff --git a/skills/moonpay-slack/SKILL.md b/skills/moonpay-slack/SKILL.md new file mode 100644 index 0000000..f2909b6 --- /dev/null +++ b/skills/moonpay-slack/SKILL.md @@ -0,0 +1,140 @@ +--- +name: moonpay-slack +description: Deploy the MoonPay CLI as a Slack bot using Hermes Agent gateway. Use when the user wants to check crypto prices, swap tokens, or manage wallets from Slack. +tags: [gateway, messaging, automation] +--- + +# MoonPay on Slack + +Deploy a Slack bot powered by the MoonPay CLI. Uses Socket Mode — no public URL required. + +## Prerequisites + +- MoonPay CLI authenticated: `mp user retrieve` +- Python 3.11+: `python3 --version` +- Hermes Agent installed (see below) +- A Slack workspace where you can install apps + +## Install Hermes Agent + +```bash +curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash +source ~/.bashrc # or source ~/.zshrc +hermes --version +``` + +## Create a Slack app + +1. Go to [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch** +2. Name it (e.g. `MoonPay Agent`), pick your workspace → Create + +### Enable Socket Mode (no public URL needed) + +3. Left sidebar → **Socket Mode** → toggle **Enable Socket Mode** → ON +4. Generate an **App-Level Token**: name it `hermes`, scope `connections:write` → copy the `xapp-...` token + +### Set OAuth scopes + +5. Left sidebar → **OAuth & Permissions** → **Bot Token Scopes** → Add: + - `chat:write` — send messages + - `im:history` — read DMs + - `im:read` — receive DM events + - `app_mentions:read` — receive @mentions (optional, for channel use) + +### Enable events + +6. Left sidebar → **Event Subscriptions** → toggle ON +7. Under **Subscribe to bot events**, add: + - `message.im` — DMs + - `app_mention` — @mentions (optional) + +### Install the app + +8. Left sidebar → **Install App** → **Install to Workspace** → Allow +9. Copy the **Bot User OAuth Token** (`xoxb-...`) + +## Configure Hermes + +```bash +echo 'SLACK_BOT_TOKEN=xoxb-your-bot-token' >> ~/.hermes/.env +echo 'SLACK_APP_TOKEN=xapp-your-app-token' >> ~/.hermes/.env + +# Optional: restrict to specific Slack user IDs +echo 'SLACK_ALLOWED_USERS=U01234567' >> ~/.hermes/.env +``` + +To get your Slack user ID: Slack → click your profile → **More** → **Copy member ID**. + +## Add MoonPay context + +```bash +mkdir -p ~/.hermes +cat > ~/.hermes/CONTEXT.md << 'EOF' +# MoonPay Agent + +You are a crypto-native AI assistant powered by the MoonPay CLI (`mp`). + +## Rules +- Prices, balances, trending tokens → always call `mp` — never guess +- Swaps require confirmation: quote first, then execute only if user says yes +- Wallet keys never leave the machine; all signing is local + +## Key commands +- `mp wallet list` — list wallets +- `mp token balance list --wallet --chain ` — portfolio +- `mp token search --query --chain solana` — find a token +- `mp token swap --wallet --chain --from-token --from-amount --to-token ` — swap +- `mp token trending list --chain solana --limit 5` — trending tokens +- `mp prediction-market market trending list --provider polymarket --limit 5` — prediction markets +- `mp buy --token sol --amount 1 --wallet --email ` — fiat buy link + +## Format +- Keep replies concise — Slack messages, not essays +- Numbers: commas for thousands, up to 6 decimals for small tokens +- Prediction market prices as cents (65¢ = 65% implied probability) +EOF +``` + +## Start the gateway + +```bash +# Foreground (test first) +hermes gateway + +# Background as a persistent service +hermes gateway install +hermes gateway start +hermes gateway status +``` + +## Verify + +DM the bot in Slack: +``` +what are my wallets? +``` + +Expected: the agent calls `mp wallet list` and replies with your wallet names and addresses. + +## Logs + +```bash +tail -f ~/.hermes/logs/agent.log +tail -f ~/.hermes/logs/errors.log +``` + +## Error handling + +| Error | Cause | Fix | +|-------|-------|-----| +| `invalid_auth` | Bad bot token | Reinstall the app, copy fresh `xoxb-` token | +| `AppNotConnected` | Missing `xapp-` token or Socket Mode off | Check `SLACK_APP_TOKEN` and Socket Mode toggle | +| Bot doesn't receive DMs | Missing `im:history` scope | Add scope → reinstall app | +| `mp: command not found` | PATH not set in service | Add `MP_PATH=$(which mp)` to `~/.hermes/.env` | + +## Related skills + +- [moonpay-auth](../moonpay-auth/) — authenticate the MoonPay CLI +- [moonpay-telegram](../moonpay-telegram/) — same setup for Telegram +- [moonpay-discord](../moonpay-discord/) — same setup for Discord +- [moonpay-swap-tokens](../moonpay-swap-tokens/) — swap command reference diff --git a/skills/moonpay-telegram/SKILL.md b/skills/moonpay-telegram/SKILL.md new file mode 100644 index 0000000..9facb99 --- /dev/null +++ b/skills/moonpay-telegram/SKILL.md @@ -0,0 +1,137 @@ +--- +name: moonpay-telegram +description: Deploy the MoonPay CLI as a persistent Telegram bot using Hermes Agent gateway. Use when the user wants to control wallets, swap tokens, check prices, or run prediction markets from Telegram. +tags: [gateway, messaging, automation] +--- + +# MoonPay on Telegram + +Deploy a Telegram bot powered by the MoonPay CLI. Once running, any message to the bot executes MoonPay operations on the user's behalf. + +## Prerequisites + +- MoonPay CLI authenticated: `mp user retrieve` +- Python 3.11+: `python3 --version` +- Hermes Agent installed (see below) +- A Telegram bot token from [@BotFather](https://t.me/BotFather) + +## Install Hermes Agent + +```bash +curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash +source ~/.bashrc # or source ~/.zshrc +hermes --version +``` + +## Create a Telegram bot + +1. Open Telegram → search **@BotFather** → `/newbot` +2. Follow prompts: choose a name (e.g. `MoonPay Agent`) and username (e.g. `moonpay_agent_bot`) +3. Copy the token: `7123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxx` + +To restrict access to yourself only, get your Telegram user ID: +- Message [@userinfobot](https://t.me/userinfobot) → it replies with your numeric ID + +## Configure Hermes + +```bash +# Write the bot token to Hermes config +hermes config set gateway.telegram.bot_token 7123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxx + +# Optional: restrict to your Telegram user ID only (recommended) +hermes config set gateway.telegram.allowed_users 123456789 + +# Or use environment variables +echo 'TELEGRAM_BOT_TOKEN=7123456789:AAFxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> ~/.hermes/.env +echo 'TELEGRAM_ALLOWED_USERS=123456789' >> ~/.hermes/.env +``` + +## Add MoonPay context + +Create a context file so the agent knows to use the MoonPay CLI: + +```bash +mkdir -p ~/.hermes +cat > ~/.hermes/CONTEXT.md << 'EOF' +# MoonPay Agent + +You are a crypto-native AI assistant powered by the MoonPay CLI (`mp`). + +## Rules +- Prices, balances, trending tokens → always call `mp` — never guess +- Swaps require confirmation: quote first, then execute only if user says yes +- Wallet keys never leave the machine; all signing is local + +## Key commands +- `mp wallet list` — list wallets +- `mp token balance list --wallet --chain ` — portfolio +- `mp token search --query --chain solana` — find a token +- `mp token swap --wallet --chain --from-token --from-amount --to-token ` — swap +- `mp token trending list --chain solana --limit 5` — trending tokens +- `mp prediction-market market trending list --provider polymarket --limit 5` — prediction markets +- `mp buy --token sol --amount 1 --wallet --email ` — fiat buy link + +## Format +- Keep replies short — Telegram messages, not essays +- Numbers: commas for thousands, up to 6 decimals for small tokens +- Prediction market prices as cents (65¢ = 65% implied probability) +EOF +``` + +## Start the gateway + +```bash +# Foreground (test first) +hermes gateway + +# Background as a persistent service +hermes gateway install # registers as systemd/launchd service +hermes gateway start # starts the service +hermes gateway status # confirm it's running +``` + +## Verify + +Send your bot a message on Telegram: +``` +what are my wallets? +``` + +Expected: the agent calls `mp wallet list` and replies with your wallet names and addresses. + +## Logs + +```bash +# Live logs +tail -f ~/.hermes/logs/agent.log + +# Gateway-specific errors +tail -f ~/.hermes/logs/errors.log +``` + +## Webhook mode (cloud deployments) + +For Fly.io, Railway, or any server with a public URL — webhook is more reliable than polling: + +```bash +echo 'TELEGRAM_WEBHOOK_URL=https://your-app.fly.dev/telegram' >> ~/.hermes/.env +echo 'TELEGRAM_WEBHOOK_PORT=8443' >> ~/.hermes/.env +echo 'TELEGRAM_WEBHOOK_SECRET=your-random-secret' >> ~/.hermes/.env +hermes gateway start +``` + +## Error handling + +| Error | Cause | Fix | +|-------|-------|-----| +| `Conflict: terminated by other getUpdates request` | Two gateway instances running | `hermes gateway stop` then restart | +| `Unauthorized` | Bad bot token | Re-run BotFather, copy token again | +| `mp: command not found` | PATH not set in service | Add `MP_PATH` to `~/.hermes/.env`: `MP_PATH=$(which mp)` | +| Agent doesn't respond | Allowed-users mismatch | Check `TELEGRAM_ALLOWED_USERS` matches your user ID | + +## Related skills + +- [moonpay-auth](../moonpay-auth/) — authenticate the MoonPay CLI +- [moonpay-discord](../moonpay-discord/) — same setup for Discord +- [moonpay-swap-tokens](../moonpay-swap-tokens/) — swap command reference +- [moonpay-trading-automation](../moonpay-trading-automation/) — scheduled DCA and alerts diff --git a/skills/moonpay-whatsapp/SKILL.md b/skills/moonpay-whatsapp/SKILL.md new file mode 100644 index 0000000..2165302 --- /dev/null +++ b/skills/moonpay-whatsapp/SKILL.md @@ -0,0 +1,140 @@ +--- +name: moonpay-whatsapp +description: Deploy the MoonPay CLI as a WhatsApp bot using Hermes Agent gateway. Use when the user wants to check crypto prices, swap tokens, or manage wallets directly from WhatsApp. +tags: [gateway, messaging, automation] +--- + +# MoonPay on WhatsApp + +Deploy a WhatsApp bot powered by the MoonPay CLI. Hermes uses a built-in Baileys bridge — no Meta Business API or paid tier required. You pair via QR code, just like WhatsApp Web. + +## Prerequisites + +- MoonPay CLI authenticated: `mp user retrieve` +- Python 3.11+: `python3 --version` +- Hermes Agent installed (see below) +- A WhatsApp account (personal number) +- Node.js 20+: `node --version` (required by the Baileys bridge) + +## Install Hermes Agent + +```bash +curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash +source ~/.bashrc # or source ~/.zshrc +hermes --version +``` + +## Pair via QR code + +Hermes includes an interactive setup wizard that installs the Baileys bridge and pairs your WhatsApp account: + +```bash +hermes whatsapp +``` + +The wizard will: +1. Install the Baileys bridge (`npm install` in a local directory) +2. Display a QR code in the terminal +3. On your phone: **WhatsApp → Linked Devices → Link a Device** → scan the QR code +4. Confirm pairing — the session is saved to `~/.hermes/whatsapp/` + +Once paired, the bridge runs as a background process that Hermes connects to. + +## Configure access control + +```bash +# Restrict to your own WhatsApp number (recommended) +# Format: country code + number, no + or spaces +echo 'WHATSAPP_ENABLED=true' >> ~/.hermes/.env +echo 'WHATSAPP_ALLOWED_USERS=15551234567' >> ~/.hermes/.env +``` + +## Add MoonPay context + +```bash +mkdir -p ~/.hermes +cat > ~/.hermes/CONTEXT.md << 'EOF' +# MoonPay Agent + +You are a crypto-native AI assistant powered by the MoonPay CLI (`mp`). + +## Rules +- Prices, balances, trending tokens → always call `mp` — never guess +- Swaps require confirmation: quote first, then execute only if user says yes +- Wallet keys never leave the machine; all signing is local + +## Key commands +- `mp wallet list` — list wallets +- `mp token balance list --wallet --chain ` — portfolio +- `mp token search --query --chain solana` — find a token +- `mp token swap --wallet --chain --from-token --from-amount --to-token ` — swap +- `mp token trending list --chain solana --limit 5` — trending tokens +- `mp prediction-market market trending list --provider polymarket --limit 5` — prediction markets +- `mp buy --token sol --amount 1 --wallet --email ` — fiat buy link + +## Format +- Short replies — WhatsApp messages, not essays +- Numbers: commas for thousands, up to 6 decimals for small tokens +- Prediction market prices as cents (65¢ = 65% implied probability) +EOF +``` + +## Start the gateway + +```bash +# Foreground (test first) +hermes gateway + +# Background as a persistent service +hermes gateway install +hermes gateway start +hermes gateway status +``` + +## Verify + +Message yourself on WhatsApp (the paired number): +``` +what are my wallets? +``` + +Expected: the agent calls `mp wallet list` and replies with your wallet names and addresses. Responses are prefixed with `⚕ Hermes Agent` to distinguish them from your own messages. + +## Logs + +```bash +tail -f ~/.hermes/logs/agent.log +tail -f ~/.hermes/logs/errors.log +``` + +## Re-pairing + +If the session expires or you get `Connection Closed` errors: + +```bash +hermes gateway stop +rm -rf ~/.hermes/whatsapp/ +hermes whatsapp # scan QR again +hermes gateway start +``` + +## Error handling + +| Error | Cause | Fix | +|-------|-------|-----| +| `Connection Closed` | WhatsApp session expired | Re-pair with `hermes whatsapp` | +| QR code not displaying | Terminal too narrow | Expand terminal window to at least 80 columns | +| `mp: command not found` | PATH not set in service | Add `MP_PATH=$(which mp)` to `~/.hermes/.env` | +| Agent replies to wrong chats | `WHATSAPP_ALLOWED_USERS` not set | Add your number (digits only, no `+`) | +| Node.js not found | Bridge dependency missing | Install Node.js 20+: `nvm install 20` | + +## Note on Terms of Service + +Baileys uses WhatsApp Web's unofficial API. This works reliably for personal use but is technically against WhatsApp's ToS. For production or business use, consider the official [WhatsApp Business API](https://developers.facebook.com/docs/whatsapp/). + +## Related skills + +- [moonpay-auth](../moonpay-auth/) — authenticate the MoonPay CLI +- [moonpay-telegram](../moonpay-telegram/) — same setup for Telegram (official API) +- [moonpay-discord](../moonpay-discord/) — same setup for Discord +- [moonpay-swap-tokens](../moonpay-swap-tokens/) — swap command reference