X402 Crypto Signals Openclaw

README

# x402 Crypto Signals — OpenClaw / Hermes Plugin

An autonomous 24/7 crypto trade signals system built as a plugin for **[OpenClaw](https://openclaw.ai)** and **[Hermes Agent](https://github.com/NousResearch/hermes-agent)**. The team of AI agents consumes real-time market data via **[x402 USDC micropayments](https://x402.org)** on Base mainnet, synthesizes trade signals, and publishes them to a Telegram channel — fully unattended.

> ⚠️ **Disclaimer:** All output is informational only and is NOT financial advice. Forecasts are probabilistic model outputs. Past signals do not guarantee future returns. Use at your own risk.

---

## Architecture

```
run-cycle.sh (every 30 min)
│
├── [PARALLEL] market-scout   ← x402 → kronossignals.com
│   └── wallet-keeper (signs x402 payments)
│
├── [PARALLEL] news-sentinel  ← x402 → x402scan.com discovery
│   └── wallet-keeper
│
├── signal-forge              ← synthesizes TradeSignal
│
└── channel-captain           ← publishes to Telegram

watchdog.sh (every 5 min)    ← health checks + auto-recovery + operator alerts
```

### Agents

| Agent | Role |
|---|---|
| `wallet-keeper` | EVM wallet custody, x402 payment signing, spend controls |
| `market-scout` | x402-gated market data: price, funding, OI, forecast |
| `news-sentinel` | x402-gated news & sentiment intelligence |
| `signal-forge` | Trade signal synthesis from market + news data |
| `channel-captain` | Telegram formatting, publishing, subscription gating |
| `watchdog` | Health monitor, heartbeat, auto-recovery, operator DMs |

### Data Sources

- **[Kronos Signals API](https://kronossignals.com)** — pay-per-call real-time crypto data (price, derivatives, ML forecasts, fear/greed, OHLC, volatility)
- **[x402scan.com](https://x402scan.com)** — discovery directory for additional x402-gated API sellers
- All data calls paid autonomously via x402 EIP-3009 USDC micropayments on **Base mainnet**

---

## Quick Start

### Prerequisites

- [OpenClaw](https://openclaw.ai) **or** [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed
- A funded EVM wallet on Base mainnet (USDC for API calls)
- A Telegram bot token + channel

### Install

```bash
git clone https://github.com/YOUR_USERNAME/x402-crypto-signals-openclaw
cd x402-crypto-signals-openclaw

# Auto-detects OpenClaw or Hermes, configures cron/scheduler, creates .env template
bash scripts/install.sh
```

### Configure

```bash
# Fill in your keys (wallet private key, Telegram tokens, watchlist)
nano .env
```

Required variables:

| Variable | Description |
|---|---|
| `WALLET_PRIVATE_KEY` | EVM private key (Base network) for x402 payments |
| `TELEGRAM_BOT_TOKEN` | Telegram bot token (from @BotFather) |
| `TELEGRAM_CHANNEL_ID` | Channel to publish signals (`@mychannel` or `-100123...`) |
| `OPERATOR_TELEGRAM_CHAT_ID` | Your personal chat ID for watchdog alerts |
| `WATCHLIST_TOKENS` | Comma-separated tokens: `BTC,ETH,SOL` |
| `CHANNEL_WALLET_ADDRESS` | USDC address (Base) for subscription revenue |

See [`.env.example`](.env.example) for all options including spend controls.

### Test

```bash
# Run one cycle manually
bash scripts/run-cycle.sh

# Check logs
tail -f ~/.crypto-signals/cron.log
```

The cron / Hermes scheduler then runs it **automatically 24/7**.

---

## Scheduling

**OpenClaw** (via cron):
```cron
*/30 * * * *  /path/to/plugin/scripts/run-cycle.sh
*/5  * * * *  /path/to/plugin/scripts/watchdog.sh
0 9  * * 1    /path/to/plugin/scripts/run-cycle.sh weekly-summary
```

**Hermes Agent** (built-in scheduler):
```bash
hermes schedule add --name crypto-signals-cycle   --cron "*/30 * * * *" --skill crypto-signals-plugin/crypto-signals-router
hermes schedule add --name crypto-signals-watchdog --cron "*/5 * * * *"  --skill crypto-signals-plugin/watchdog
hermes schedule add --name crypto-signals-weekly   --cron "0 9 * * 1"   --skill crypto-signals-plugin/channel-captain
```

**Linux VPS** (systemd timer, most reliable):
```bash
sudo cp config/crypto-signals-watchdog.{service,timer} /etc/systemd/system/
sudo systemctl enable --now crypto-signals-watchdog.timer
```

---

## Estimated Costs

Per 30-min cycle (BTC+ETH+SOL snapshots + screeners):
- 3 × `/snapshot` at $0.08 = $0.24
- `/funding-extremes` at $0.01 = $0.01
- `/fear-greed` at $0.01 = $0.01
- **~$0.26 USDC/cycle → ~$12.50/day** at 48 cycles

Configurable via `DAILY_SPEND_CAP_USDC` in `.env` (default: `10.0`). Watchdog auto-pauses cycles if the daily cap is hit.

---

## Security Notes

- **Never commit `.env`** — it is gitignored. Store your `WALLET_PRIVATE_KEY` securely.
- The wallet-keeper agent enforces `MAX_SINGLE_PAYMENT_USDC` and `DAILY_SPEND_CAP_USDC` caps.
- Watchdog sends Telegram DM alerts to `OPERATOR_TELEGRAM_CHAT_ID` on anomalies.
- Full wallet address is never logged or transmitted in alerts (truncated to first 6 + last 4 chars).

---

## File Structure

```
x402-crypto-signals-openclaw/
├── plugin.json                         # Plugin manifest
├── .env.example                        # Environment template (copy → .env)
├── .gitignore
├── README.md
├── agents/
│   ├── wallet-keeper.md                # x402 wallet & spend controls
│   ├── market-scout.md                 # Market data fetcher
│   ├── news-sentinel.md                # News & sentiment
│   ├── signal-forge.md                 # Signal synthesis
│   ├── channel-captain.md              # Telegram publisher
│   └── watchdog.md                     # Health monitor
├── skills/
│   ├── crypto-signals-router/SKILL.md  # Team orchestration router
│   └── kronos-signals-api/SKILL.md     # Kronos API reference skill
├── scripts/
│   ├── install.sh                      # Installer (auto-detects runtime)
│   ├── run-cycle.sh                    # Main 30-min cycle
│   └── watchdog.sh                     # 5-min health check
└── config/
    ├── crypto-signals-watchdog.service # systemd service unit
    └── crypto-signals-watchdog.timer   # systemd timer unit
```

---

## Related

- [x402 Protocol](https://x402.org)
- [Kronos Signals API](https://kronossignals.com) — [OpenAPI spec](https://kronossignals.com/api/openapi.json)
- [x402scan.com](https://x402scan.com) — x402 API discovery directory
- [OpenClaw](https://openclaw.ai)
- [Hermes Agent](https://github.com/NousResearch/hermes-agent)

---

## License

MIT