# Koin Ping: Blockchain intelligence - 2025-2026 @sjDev - LICENSE: MIT


![koinpin demo image.](koinping_demo_image.png)

A lightweight on-chain monitoring and alerting system designed to give users situational awareness over blockchain addresses they care about. Integrations with Discord, Slack, Telegram, Whatsapp enable real-time alerts.

# Overview: Real-time on-chain intelligence

Koin Ping observes on-chain activity and notifies users when her predefined conditions are met. Users configure the application to observe
specific addresses and send instant notifications via Discord, Slack, Telegram, Whatsapp or email if threshold conditions are met, such as a
transfer in/out that is above a specified quantity of the relevant amount.

The application 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 <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/.env.example backend/.env
# edit backend/.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 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 for development.

## Rationale

Crypto users may actively monitor addresses with webhooks integrating popular 
messaging platforms: Discord, Slack, Telegram.
This lightweight, reliable framework makes instant awareness of on-chain 
activity trivial, without polling block explorers manually. Koin Ping watches 
addresses, evaluates configurable alert rules (incoming transactions, outgoing 
transactions, "large" transfers, balance thresholds), and sends notifications.

## Design

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

```
koin_ping_0.2.0/
├── backend/                # 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.

---

*Guides for Discord, Slack, and Email coming soon.*

## License

MIT. See [LICENSE](LICENSE).

## Author

Steven Jannette