koin_ping_0.2.0/README.md

Koin Ping

A lightweight on-chain monitoring and alerting system designed to give users situational awareness over blockchain addresses they care about.

Overview

Koin Ping observes on-chain activity and notifies users when predefined conditions are met. It does not execute transactions, manage wallets, or speculate on prices.

Getting Started

Prerequisites

• Go 1.24+
• Node.js 18+ and npm (or yarn — preferred per repo policy)
• PostgreSQL 15+
• golangci-lint v2 (for make lint)

Setup

# Clone and enter the repo
git clone <repo-url>
cd koin_ping_0.2.0

# Install pre-commit hook
make hooks

# Install frontend dependencies
cd frontend && npm install && cd ..

# Copy and fill in environment variables
cp backend-go/.env.example backend-go/.env
# edit backend-go/.env with your DATABASE_URL, FIREBASE_PROJECT_ID, ETH_RPC_URL

# Run checks (requires golangci-lint)
make check

# Start the API server
make run

# Start the poller (separate terminal)
cd backend-go && go run ./cmd/poller

# Start the frontend dev server (separate terminal)
cd frontend && npm run dev

The API listens on http://localhost:3001 and the frontend on http://localhost:3000 by default.

Rationale

Crypto users who hold or actively monitor addresses need a lightweight, reliable way to know when on-chain activity occurs without polling block explorers manually. Koin Ping fills that gap: it watches a set of Ethereum addresses, evaluates configurable alert rules (incoming transactions, outgoing transactions, large transfers, balance thresholds), and notifies the user through Discord webhooks.

Design

The system is split into two independently deployable processes and one frontend:

koin_ping_0.2.0/
├── backend-go/                # Go monorepo root
│   ├── cmd/api/               # HTTP REST API server
│   ├── cmd/poller/            # Blockchain polling daemon
│   └── internal/
│       ├── config/            # Environment-based config loading
│       ├── database/          # pgx connection pool
│       ├── domain/            # Shared domain types
│       ├── firebase/          # Firebase auth client
│       ├── handlers/          # HTTP handler wiring
│       ├── middleware/         # Auth middleware
│       ├── models/            # SQL persistence layer
│       ├── notifications/     # Discord webhook delivery
│       ├── protocols/ethereum/ # Ethereum JSON-RPC client
│       ├── services/          # Observer and evaluator business logic
│       └── wei/               # ETH/Wei conversion utilities
└── frontend/                  # React + Vite SPA
    └── src/
        ├── api/               # Fetch wrappers for the REST API
        ├── components/        # Reusable UI components
        ├── contexts/          # React contexts (auth, etc.)
        ├── firebase/          # Firebase SDK initialization
        └── pages/             # Top-level route pages

API server (cmd/api): standard-library net/http with Firebase JWT authentication middleware. Exposes CRUD endpoints for addresses, alert rules, alert events, and notification configuration.

Poller (cmd/poller): long-running daemon that polls Ethereum via JSON-RPC, compares observed transactions against persisted alert rules, fires alert events to the database, and dispatches Discord notifications.

Frontend (frontend/): React 19 SPA built with Vite. Authenticates with Firebase, communicates with the API via fetch, and renders the address/alert management UI.

Setting Up Your Alert Platforms

Koin Ping can send real-time alerts to Telegram, Discord, Slack, and Email. Each channel is configured per-user through the Notification Settings panel on the Alerts page.

Below are step-by-step guides for setting up each platform.

---

Telegram

To receive alerts via Telegram, you need to create a bot and get your chat ID.

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather (look for the blue verified checkmark).
2. Open the conversation with BotFather and send: /newbot
3. BotFather will ask for a display name — enter something like Koin Ping Alerts.
4. BotFather will ask for a username — it must end in bot, e.g. MyKoinPingBot.
5. BotFather will reply with your Bot Token — a string that looks like 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Copy it.

2. Get Your Chat ID

1. In Telegram, search for the bot username you just created and open the chat.

2. Tap Start or send any message (e.g. hello).

3. Open the following URL in your browser, replacing YOUR_BOT_TOKEN with the token from step 1:

   https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates
   

4. In the JSON response, find the "chat" object — the "id" field is your Chat ID (a numeric value).

   Tip: If the "result" array is empty, make sure you sent a message to your bot first, then refresh the page.

3. Save in Koin Ping

1. Go to the Alerts page in Koin Ping.
2. In the Notification Settings panel, find the Telegram section.
3. Paste your Bot Token and Chat ID into the corresponding fields.
4. Click Save Settings.
5. Click Test All Channels to verify — you should receive a test message from your bot in Telegram.

---

Discord

To receive alerts in a Discord channel, you need to create a webhook.

1. Create a Discord Webhook

1. Open Discord and navigate to the server where you want to receive alerts.

2. Go to the channel you want alerts posted in (or create a new one, e.g. #koin-alerts).

3. Click the gear icon next to the channel name to open Channel Settings.

4. Go to Integrations > Webhooks.

5. Click New Webhook.

6. Give it a name (e.g. Koin Ping) and click Copy Webhook URL.

   The URL will look like: https://discord.com/api/webhooks/123456789/AbCdEfGhIjKl...

2. Save in Koin Ping

1. Go to the Alerts page in Koin Ping.
2. In the Notification Settings panel, find the Discord section.
3. Paste your Webhook URL into the field.
4. Click Save Settings.
5. Click Test All Channels to verify — you should see a test message appear in your Discord channel.

---

Slack

To receive alerts in a Slack channel, you need to create an Incoming Webhook.

1. Create a Slack App with Incoming Webhooks

1. Go to https://api.slack.com/apps and click Create New App.
2. Choose From scratch, give it a name (e.g. Koin Ping), and select your workspace.
3. In the app settings, go to Incoming Webhooks in the left sidebar.
4. Toggle Activate Incoming Webhooks to On.
5. Click Add New Webhook to Workspace.
6. Select the channel where you want alerts posted (e.g. #koin-alerts) and click Allow.
7. Copy the Webhook URL — it will start with https://hooks.slack.com/services/...

2. Save in Koin Ping

1. Go to the Alerts page in Koin Ping.
2. In the Notification Settings panel, find the Slack section.
3. Paste your Webhook URL into the field.
4. Click Save Settings.
5. Click Test All Channels to verify — you should see a test message appear in your Slack channel.

---

Email

Koin Ping sends email alerts and digests via Resend. To enable email notifications, the application owner must configure a Resend account and verified sending domain.

For Application Owners (Deployment Setup)

1. Create an account at resend.com.

2. Go to resend.com/domains and add your sending domain.

3. Add the DNS records Resend provides (SPF, DKIM, etc.) to your domain's DNS settings.

4. Once verified, create an API key at resend.com/api-keys.

5. Set the following in your .env file:

   RESEND_API_KEY=re_your_api_key_here
   EMAIL_FROM=Your App <alerts@yourdomain.com>
   

6. Restart the API server and poller to pick up the changes.

For Users

1. Go to the Alerts page in Koin Ping.
2. In the Notification Settings panel, find the Email section.
3. Enter the email address where you want to receive alerts.
4. Click Save Settings.
5. Click Verify Email to receive a confirmation message.
6. Click Test All Channels to verify — you should receive a test alert at your email address.

License

MIT. See LICENSE.

Author

Steven Jannette