# 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 ```bash # Clone and enter the repo git clone 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](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](https://resend.com). 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](https://resend.com). 2. Go to [resend.com/domains](https://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](https://resend.com/api-keys). 5. Set the following in your `.env` file: ``` RESEND_API_KEY=re_your_api_key_here EMAIL_FROM=Your App ``` 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](LICENSE). ## Author Steven Jannette