Ever Green Documentation

Ever Green is a real-time EVM blockchain event monitoring platform. It watches on-chain events using SQL, delivers matched signals via Webhooks, Redis, or Kafka, and handles chain reorganizations automatically.

Quickstart

The fastest way to get started is to sign in through the dashboard, create a watch with a SQL query, and configure a delivery target. Watches execute against every new block and deliver matched rows to your endpoint.

1. Create a watch via the API

{
  "name": "large-erc20-transfers",
  "sql": "SELECT l.transaction_hash, l.address, l.data FROM main.logs l WHERE l.topic0 = '0xddf252ad...' AND CAST(l.data AS BIGINT) > 1000000",
  "abi_set": ["ERC20.json"],
  "target": {
    "type": "queue",
    "provider": "redis",
    "topic": "mangroves.signals"
  },
  "retries": 3,
  "status": "enabled"
}

2. Query live blockchain data

{
  "sql": "SELECT number, hash FROM main.blocks ORDER BY number DESC LIMIT 5",
  "max_rows": 100,
  "timeout_ms": 3000
}

Queries run against an in-memory Apache Arrow store backed by DataFusion. Available tables are main.blocks, main.transactions, and main.logs.

Core Concepts

Watch Operators

A watch is a SQL query that runs against every incoming block. When the query returns rows, those rows are packaged as a delivery payload and sent to the configured target (webhook, Redis, or Kafka). Watches support macros like {{block_number}}, {{chain_id}}, and '{{block_hash}}' for dynamic filtering.

Delivery Pipeline

The delivery system uses an outbox pattern with idempotency keys. Each matched payload is assigned a unique key based on the watch ID, block number, and outbox cursor. If delivery fails, the system retries up to the configured max attempts before moving the payload to a dead-letter queue.

Reorg Retractions

When the chain reorganizes, Ever Green automatically retracts deliveries from orphaned blocks. Pending outbox entries for reverted blocks are cancelled, and already-delivered payloads receive retraction notices so downstream consumers can undo any actions.

Watches API

List all watches. For project-scoped users, returns only watches belonging to the current project.

Create a new watch, or perform actions on an existing watch by including id and action (enable, disable, or delete) in the request body.

Query API

Execute a SQL query against live blockchain data. The request body accepts sql (the query), max_rows (limit, default 100), and timeout_ms (default 2000). The response includes column names, rows, row count, elapsed time, and a truncation flag.

Delivery Records

Retrieve recent delivery records. Each record includes the watch ID, block information, target configuration, attempt count, disposition (e.g. WebhookDelivered, QueuePublished, RetryScheduled, DeadLettered), and optionally the matched row sample.

Telemetry

Returns aggregate delivery statistics: enqueued, delivered, retry, suppressed, deadlettered, retracted counts, plus detailed retraction breakdowns for delivery keys and pending outbox entries.

Authentication

Ever Green supports three authentication modes that can be used independently or combined: password-based accounts, OAuth (GitHub and Google), and shared operator tokens.

Session cookies

The web dashboard uses session cookies set during login. API routes check for a valid session cookie or a Bearer token in the Authorization header.

API Keys

Create a project-scoped API key. The request body takes label (a human-readable name) and role (either editor or viewer). The response includes the full raw key, which is only shown once.

curl -sS 'https://your-host/auth/whoami' \
  -H "Authorization: Bearer mgr_your_api_key_here"

OAuth (GitHub / Google)

OAuth is initiated by redirecting to /api/auth/github or /api/auth/google. The callback exchanges the authorization code for a session cookie. OAuth providers are enabled via environment variables (GITHUB_CLIENT_ID, GOOGLE_CLIENT_ID, etc.).

Webhook Delivery

Webhooks deliver matched payloads as HTTP POST requests to the configured endpoint URL. The payload includes the watch ID, block information, idempotency key, and matched rows. Failed deliveries are retried with exponential backoff.

Redis Streams

Redis delivery publishes matched payloads to a Redis Stream using the configured topic name. Each message includes the full delivery payload as JSON fields. Redis must be configured at the daemon level via REDIS_URL.

Kafka Delivery

Kafka delivery publishes matched payloads to a Kafka topic. The producer is configured at the daemon level via KAFKA_BROKERS. Kafka delivery is available on Builder and Scale plans (or self-hosted). Messages use the watch ID as the partition key for ordered processing.

MCP Integration

Ever Green exposes an MCP (Model Context Protocol) server that allows AI agents and copilots to create watches, run queries, and inspect delivery state through tool calls. MCP traffic is metered the same way as HTTP API calls.

MANGROVES_HTTP_BASE_URL='https://api.onchainsql.xyz' \
MANGROVES_API_KEY='egp_your_project_key' \
evergreen-mcp

Customers should use the packaged MCP client, not a source checkout. We ship Ever Green MCP as a standalone binary and as a Docker image, both pointing at the public API host with a project-scoped API key.

curl -fsSL https://downloads.onchainsql.xyz/evergreen-mcp/latest/evergreen-mcp-darwin-arm64.tar.gz -o evergreen-mcp.tar.gz
tar -xzf evergreen-mcp.tar.gz
chmod +x evergreen-mcp

MANGROVES_HTTP_BASE_URL='https://api.onchainsql.xyz' \
MANGROVES_API_KEY='egp_your_project_key' \
./evergreen-mcp

docker run --rm -i \
  -e MANGROVES_HTTP_BASE_URL='https://api.onchainsql.xyz' \
  -e MANGROVES_API_KEY='egp_your_project_key' \
  ghcr.io/msbeni/evergreen-mcp:latest

Example client configs ship with the release bundle: claude-desktop.example.json and cursor.example.json .

Public image URL: ghcr.io/msbeni/evergreen-mcp:latest . Binary bundles are published at: https://downloads.onchainsql.xyz/evergreen-mcp/latest/ .

Reorg Handling

When a chain reorganization is detected, Ever Green performs two retraction operations: it cancels pending outbox entries for blocks that were reverted, and it marks already-delivered payloads with a retraction disposition. Downstream consumers receive retraction notices so they can roll back any actions taken based on the orphaned block data.

Self-hosting

The Ever Green daemon is distributed as a single Rust binary. Configure it with environment variables for your RPC endpoint, database URL, and optional queue providers. Self-hosted deployments have no quota limits and full access to all features.

# Required
MANGROVES_RPC_URL=https://your-rpc-endpoint
DATABASE_URL=postgres://user:pass@localhost/evergreen

# Optional delivery targets
REDIS_URL=redis://localhost:6379
KAFKA_BROKERS=localhost:9092

# Optional auth
MANGROVES_WEB_UI_TOKEN=your-operator-token
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...