---
name: eventmesh
description: Real-time event subscriptions for AI agents. Describe what you want to know about — price movements, news, on-chain activity, social media — and get push notifications. No polling, no connectors, just natural language.
metadata: {"version": "0.2.0","api_base":"https://api.eventmesh.cc","category":"events","cli":"eventmeshcc"}
---

# Eventmesh

Real-time event subscriptions for AI agents. Describe what you care about in plain English — Eventmesh delivers matching events. No connectors to configure, no APIs to learn, no polling.

**CLI:** `eventmeshcc` · **API:** `https://api.eventmesh.cc`

---

## How it works

1. **Subscribe** in natural language → Eventmesh picks the right data source and filter.
2. **Match** is structured (price thresholds, address transfers, market resolution) or semantic (news topics, tweet themes).
3. **Deliver** events to your agent — server-side webhook, local hook server, or stdout stream.

You pay per delivered event (1 credit = $0.01 USDC, prepaid). See `references/topup.md`.

Good fits:
- Trading bots reacting to price/TVL/prediction-market moves.
- Notification agents (Telegram/Discord/Slack via OpenClaw or Hermes).
- Watchers on on-chain wallets, contracts, NFT transfers.
- News, social, sports, DeFi feeds without writing connectors.

---

## Install the skill locally

```bash
mkdir -p ~/.claude/skills/eventmesh
curl -s https://eventmesh.cc/skill.md > ~/.claude/skills/eventmesh/SKILL.md
```

The reference files (`references/connectors.md`, `references/cli.md`, `references/openclaw.md`, `references/hermes.md`, `references/claude-code.md`, `references/topup.md`) live at `https://eventmesh.cc/references/<name>.md`. Fetch them on-demand — don't bundle everything into context up front.

---

## Step 1 — Install and log in

```bash
npm i -g eventmeshcc
eventmeshcc login
```

**Login is fully automatic — no email, no API key, no user input required.** The CLI auto-creates an account using a device fingerprint; if you've logged in before, it retrieves your existing account. The API key is saved to `~/.eventmesh/config`.

> **Important for agents:** Do NOT ask the user for an email or API key. Just run `eventmeshcc login`. Email is an optional account-recovery parameter — omit it unless the user explicitly offers one.

Verify: `eventmeshcc account`. Existing key? `export EVENTMESH_API_KEY=em_...`.

---

## Step 2 — Subscribe

Describe what you want. Eventmesh figures out the source, filter, and delivery.

```bash
eventmeshcc subscribe "notify me when BTC crosses 100k"
```

```json
{ "id": "sub_abc123", "intent": "notify me when BTC crosses 100k", "match_type": "structured", "status": "paused" }
```

> Subscriptions start **paused** by default. Use `--active` to start delivering immediately, or activate later with `eventmeshcc resume <id>`. For server-side webhook delivery (`--webhook`), `--active` is recommended — events deliver with no listener required.

For the full intent grammar per connector (crypto prices, on-chain, Solana DeFi, crypto news, general news, Twitter, DeFi TVL, basketball, soccer, football, baseball, hockey, tennis, weather, Polymarket/Kalshi) → **`references/connectors.md`**.

For all CLI flags → **`references/cli.md`**.

---

## Step 3 — Listen for events

Pick the delivery mode that fits the host. **Don't build your own polling/cron/file-watching solution** — `subscribe --webhook` and `listen` cover every case.

| Situation | Mode | See |
|---|---|---|
| You have any HTTP endpoint that can receive POSTs | `subscribe --webhook <url>` (server-side, no process) | `references/cli.md` |
| OpenClaw user wanting Telegram/Discord notifications | `listen` → `/hooks/agent` | `references/openclaw.md` |
| Hermes user wanting agent-driven delivery | `subscribe --webhook` → Hermes route | `references/hermes.md` |
| Claude Code user wanting events to wake the session | `listen --hook-port` → `/hooks/wake` | `references/claude-code.md` |
| Programmatic stream (subprocess, pipe) | `listen --stdout` (NDJSON) | `references/cli.md` |

> **Run only ONE listener process per account.** Multiple listeners compete for the same WebSocket and cause disconnects. Pass all subscription IDs to a single `listen` call.

---

## Managing subscriptions

```bash
eventmeshcc list                   # all subscriptions
eventmeshcc inspect <id>           # full details
eventmeshcc resume <id>            # activate
eventmeshcc pause <id>             # pause (events queue server-side)
eventmeshcc delete <id> [--force]  # remove permanently
```

Lifecycle: `PAUSED → resume → ACTIVE → events flow → pause → PAUSED` / `→ delete → gone`. Paused subscriptions still accumulate events server-side — delivered on reconnect.

---

## Anti-patterns (general)

| Anti-pattern | Why it's bad | Do this instead |
|---|---|---|
| Asking the user for an email or API key before login | Login is automatic via device fingerprint | Just run `eventmeshcc login` |
| Building a custom poller/cron/file-watcher to consume events | Eventmesh already pushes — you're reinventing the bus | `subscribe --webhook` or `listen` |
| Multiple `listen` processes for different subscriptions | WebSocket session conflicts cause disconnects | One `listen` call with all sub IDs |
| Vague intents like `"crypto news"` | Floods the channel with low-relevance matches | Be specific: `"important bitcoin regulation news"` |
| Creating duplicate subscriptions on every agent run | Wastes credits and clutters the list | Always `eventmeshcc list` first |

Host-specific anti-patterns (process lifecycle, exec timeouts, gateway restarts) are documented in the relevant `references/<host>.md`.

---

## Reference files

| File | Contents |
|---|---|
| `references/connectors.md` | Every connector + example intents + per-connector rules |
| `references/cli.md` | All CLI commands, flags, env vars, payload formats |
| `references/openclaw.md` | OpenClaw `/hooks/agent` setup, `nohup`/`disown`, startup hook, healthcheck |
| `references/hermes.md` | Hermes route config, payload templating, auth caveat |
| `references/claude-code.md` | Claude Code `/hooks/wake` setup |
| `references/topup.md` | x402 payment flow (Base + Solana), EIP-712 details |

**Agent guidance:** read this `skill.md` first. Fetch a reference file when the user's situation matches its scope (e.g., they're on OpenClaw → fetch `references/openclaw.md`; they ask about a connector you're unsure of → fetch `references/connectors.md`). Do not pre-fetch everything.