PumpFun Claims Bot

Нужен интерактивный мониторинг? telegram-bot поддерживает управление списками отслеживания, групповые чаты, REST API, SSE-стриминг и вебхуки. Используйте этого channel-бота для простых каналов, где нужна только публикация.

Возможности

Типы лент

Аналитика клеймов

Каждая карточка клейма социальной комиссии GitHub включает:

Карточки градуаций

Богатые карточки градуаций включают профиль создателя, анализ топ-холдеров, объём торгов за 24 часа, активность кошелька разработчика, ликвидность пула и детекцию бандлов.

Система уровней инфлюенсеров

Объединяет данные подписчиков GitHub и X/Twitter для классификации клеймеров:

Достаточно одного порога из пары — пользователь с 50K подписчиков в X и 50 подписчиков в GitHub всё равно попадает в уровень Инфлюенсер.

Оценка достоверности и история разработчика

Каждая карточка клейма начинается с детерминированного вердикта достоверности 0-100, синтезированного из сигналов доверия, которые бот уже собирает, а также с постоянной истории разработчика по его предыдущим токенам.

Оценка детерминирована и прозрачна — одинаковые входные данные всегда дают одно и то же число, без вызова модели, и каждый балл привязан к именованному фактору, показанному под заголовком:

Расчёт начинается с нейтральных 50 и корректируется взвешенными факторами: проверка клейма (+22 или -20 при несовпадении владельца GitHub), возраст аккаунта (+14 за 5+ лет, вплоть до -18 за < 30 дней), публичные репозитории, подписчики, звёзды на не-форк-репозитории, копикаты (-10/-16), бандлинг, концентрация холдеров, предыдущие скамы и баны.

История разработчика превращает разовую оценку в память. Каждая оценка сохраняется за идентификатором клеймящего GitHub-пользователя и персистится, поэтому при следующем запуске токена этим разработчиком карточка покажет его историю — выставляя напоказ серийного сборщика комиссий, чья новая монета выглядит чистой, и отдавая должное билдеру с реальными заслугами:

🟢 Credibility: 100/100 · Strong
   ↑ claim verified · GitHub 6y · 42 repos · repo 150★
📊 Dev track record: 3 prior tokens · avg 🔴 19/100 (High Risk)

Логика находится в src/credibility.ts (чистая функция scoreCredibility) и src/dev-reputation.ts (постоянное хранилище), обе полностью покрыты тестами.

AI-резюме клеймов

Первые клеймы получают однострочную AI-оценку, сгенерированную Groq (llama-3.3-70b-versatile):

• Анализирует 30+ сигналов: метаданные токена, профиль GitHub, историю создателя, торговую активность

• Максимум 120 символов — прямо, со своей позицией, с фокусом на трейдера

• Тайм-аут 5 секунд с корректным запасным вариантом (пустая строка при сбое)

• HTML-санитизированный вывод, безопасный для Telegram

Примеры:

«Настоящий GitHub-проект, разработчик заклеймил быстро» · «Форк популярного репозитория, действуйте с осторожностью»

Related MCP server: NoesisAPI

Архитектура

Solana RPC (WebSocket + HTTP polling)
        │
        ▼
┌───────────────────┐
│  SocialFeeIndex   │──▶ Bootstraps ~148K SharingConfig → mint mappings
└────────┬──────────┘
         │
┌────────▼──────────┐
│   ClaimMonitor    │──▶ Decodes PumpFees program claim transactions
│   EventMonitor    │──▶ Decodes Pump program logs (graduations)
└────────┬──────────┘
         │ FeeClaimEvent / GraduationEvent
┌────────▼──────────┐
│ Enrichment Layer  │
│  ├─ GitHub API    │──▶ User profile, repos, followers
│  ├─ X/Twitter API │──▶ Follower counts, influencer tier
│  ├─ PumpFun API   │──▶ Token info, creator profile, holders, trades
│  ├─ ClaimTracker  │──▶ First-claim detection, persistent counts
│  └─ Fake Detect   │──▶ Instruction called but no payout (amountLamports=0)
└────────┬──────────┘
         │ ClaimFeedContext
┌────────▼──────────┐
│    Formatters     │──▶ Rich HTML cards with sections & emoji layout
└────────┬──────────┘
         │
┌────────▼──────────┐
│   grammY Bot      │──▶ Posts photo + caption to Telegram channel
│   (retry + rate   │    Falls back to text-only if photo fails
│    limiting)      │
└───────────────────┘

Отказоустойчивость Multi-RPC

Класс RpcFallback управляет несколькими Solana RPC-эндпоинтами с автоматической ротацией:

• Ротация по кругу после 3 подряд неудач на любом эндпоинте

• Пауза 60 секунд для каждого сбойного эндпоинта перед повторной попыткой

• Фолбэк по ближайшему истечению — если все эндпоинты на паузе, выбирается тот, чья пауза истекает раньше всех

• Успех сбрасывает счётчик — один успешный вызов сбрасывает счётчик неудач

• Настройка через SOLANA_RPC_URLS (через запятую)

Отслеживаемые программы

Установка

npm (MCP-сервер — рекомендуется для AI-ассистентов)

Запустите MCP-сервер мгновенно с помощью npx — клонирование не требуется:

npx pumpfun-claims-bot

Или установите глобально:

npm install -g pumpfun-claims-bot
pumpfun-claims-bot

Добавьте в конфигурацию MCP-клиента (Claude Desktop, Cursor, VS Code Copilot):

{
  "mcpServers": {
    "pumpfun": {
      "command": "npx",
      "args": ["pumpfun-claims-bot"]
    }
  }
}

npm-пакет: pumpfun-claims-bot на npm

Из исходников (полный бот + Telegram-лента)

git clone https://github.com/nirholas/pumpfun-claims-bot.git
cd pumpfun-claims-bot && npm install

Быстрый старт

1. Создайте Telegram-бота

1. Напишите @BotFather в Telegram

2. /newbot → следуйте подсказкам → скопируйте токен бота

3. Создайте публичный канал (например, @pumpfunclaims)

4. Добавьте бота в канал как администратора (требуется разрешение «Отправлять сообщения»)

2. Настройте окружение

cp .env.example .env

# ── Required ──────────────────────────────────────────────
TELEGRAM_BOT_TOKEN=your-bot-token-from-botfather
CHANNEL_ID=@your_channel_name    # or numeric chat ID like -100xxx

# ── Solana RPC ────────────────────────────────────────────
SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=your-key
SOLANA_WS_URL=wss://mainnet.helius-rpc.com/?api-key=your-key

# Comma-separated fallback RPCs (rotates on 429/5xx/timeout)
SOLANA_RPC_URLS=https://mainnet.helius-rpc.com/?api-key=key1,https://your-other-rpc.com

# ── Feed Toggles (all default false except FEED_CLAIMS) ───
FEED_CLAIMS=true                 # GitHub social fee claims (default: true)
FEED_GRADUATIONS=false           # Token graduations to PumpAMM (default: false)
FEED_LAUNCHES=false              # New token launches (default: false)
FEED_WHALES=false                # Large buy/sell whale alerts (default: false)
FEED_FEE_DISTRIBUTIONS=false     # Creator fee distribution events (default: false)

# ── Claim Filter ──────────────────────────────────────────
REQUIRE_GITHUB=true              # Only post claims with GitHub social fee PDA (default: true)

# ── Enrichment APIs ───────────────────────────────────────
GITHUB_TOKEN=ghp_your_token      # Raises GitHub rate limit: 60 → 5000 req/hr
GROQ_API_KEY=gsk_your_key        # Groq API for AI one-liner summaries

# X/Twitter follower counts & influencer detection
# Get cookies from x.com DevTools → Application → Cookies
# X_AUTH_TOKEN=your_auth_token_cookie
# X_CT0_TOKEN=your_ct0_cookie

# ── Affiliate Ref Codes ───────────────────────────────────
# Appended to Axiom / GMGN / Padre trading links in cards
# AXIOM_REF=your_ref
# GMGN_REF=your_ref
# PADRE_REF=your_ref

# ── Tuning ────────────────────────────────────────────────
POLL_INTERVAL_SECONDS=30         # HTTP polling fallback interval (default: 30)
WHALE_THRESHOLD_SOL=10           # Minimum SOL for whale alerts (default: 10)
LOG_LEVEL=info                   # debug | info | warn | error (default: info)

# ── Health Check ──────────────────────────────────────────
# PORT=3000                      # Set automatically by Railway

Справочник переменных окружения

3. Запуск

# Install dependencies
npm install

# Development (hot reload via tsx)
npm run dev

# Production
npm run build
npm start

4. Развертывание с Docker

docker build -t pumpfun-channel-bot .
docker run -d --env-file .env pumpfun-channel-bot

5. Развертывание на Railway

Railway автоматически развертывает из GitHub и предоставляет постоянные тома для данных отслеживания заявок.

# Install Railway CLI
npm install -g @railway/cli
railway login

# Create & link project
railway init
railway link

# Set environment variables
railway variables set TELEGRAM_BOT_TOKEN=your-token
railway variables set CHANNEL_ID=@your_channel_name
railway variables set SOLANA_RPC_URL=https://mainnet.helius-rpc.com/?api-key=your-key
railway variables set SOLANA_WS_URL=wss://mainnet.helius-rpc.com/?api-key=your-key
railway variables set FEED_CLAIMS=true
railway variables set REQUIRE_GITHUB=true

# Create persistent volume for claim tracker data
railway volume create --mount /app/data

# Deploy
railway up

См. railway.json для конфигурации развертывания:

{
  "$schema": "https://railway.app/railway.schema.json",
  "build": {
    "builder": "DOCKERFILE",
    "dockerfilePath": "Dockerfile"
  },
  "deploy": {
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

Структура проекта

pumpfun-claims-bot/
├── src/
│   ├── index.ts              # Entry point — wires monitors, enrichment, & Telegram posting
│   ├── config.ts             # Environment variable loading & validation
│   ├── mcp-server.ts         # MCP server — exposes tools via Streamable HTTP or stdio
│   ├── mcp-stdio.ts          # Standalone MCP entry point (stdio transport)
│   ├── claim-monitor.ts      # PumpFees program monitor (WebSocket + HTTP polling)
│   ├── claim-routing.ts      # Decides which claims are posted, skipped, or re-routed
│   ├── claim-tracker.ts      # First-claim detection + claim counter (persisted to disk)
│   ├── credibility.ts        # Deterministic 0-100 credibility scoring
│   ├── dev-reputation.ts     # Persistent per-developer track record store
│   ├── event-monitor.ts      # Pump program log decoder (graduations, launches)
│   ├── social-fee-index.ts   # SocialFeeIndex — maps SharingConfig PDAs → mints (~148K)
│   ├── formatters.ts         # Rich HTML card builders for Telegram
│   ├── pump-client.ts        # PumpFun HTTP API client (token info, creator profiles)
│   ├── github-client.ts      # GitHub API client (user profiles, rate-limited cache)
│   ├── x-client.ts           # X/Twitter profile fetcher + influencer tier logic
│   ├── groq-client.ts        # Groq AI one-liner summaries
│   ├── rpc-fallback.ts       # Multi-RPC failover with round-robin
│   ├── health.ts             # HTTP health check server
│   ├── types.ts              # Program IDs, discriminators, event types
│   └── logger.ts             # Leveled console logger
├── src/__tests__/            # Vitest suites (203 tests) + shared fixtures
├── packages/web/             # React dashboard, mock-data build (see Web Dashboard)
├── web/web/                  # React dashboard, live-SSE build (see Web Dashboard)
├── leaderboard-bot/          # Separate Telegram bot: GitHub dev earnings leaderboard
├── data/                     # Persisted state (gitignored, Railway volume mount)
│   └── github-first-claims.json
├── Dockerfile                # Multi-stage Docker build
├── railway.json              # Railway deployment config
├── package.json
└── tsconfig.json

Как это работает

Конвейер обнаружения заявок

Transaction detected on PumpFees program
  │
  ▼
Identify instruction: claim_social_fee_pda?
  │
  ├─ YES ──▶ Parse platform (2 = GitHub) + user_id from Anchor args
  │           │
  │           ▼
  │        Check amountLamports from SocialFeePdaClaimed event
  │           │
  │           ├─ amountLamports > 0 ──▶ Real claim
  │           │   ├─ Check ClaimTracker: first time for this GitHub user?
  │           │   │   ├─ YES ──▶ 🚨 FIRST TIME CLAIM banner
  │           │   │   └─ NO  ──▶ Standard claim card
  │           │   └─ Enrich: GitHub API + PumpFun API + X profile
  │           │
  │           └─ amountLamports = 0 ──▶ ⚠️ FAKE CLAIM (instruction called, no payout)
  │
  └─ NO ───▶ Other claim type (creator fee, cashback, etc.)

Инициализация SocialFeeIndex

При запуске бот получает все аккаунты SharingConfig из программы PumpFees для построения обратного сопоставления адресов PDA социальных комиссий с минтами токенов. Это позволяет определить, к какому токену относится заявка на социальную комиссию, без дополнительных RPC-вызовов.

• ~148K сопоставлений загружается при запуске

• Инкрементальные обновления через WebSocket-подписку на события CreateFeeSharingConfig и UpdateFeeShares

• Поиск: socialFeeIndex.getMintForPda(pdaAddress) → минт токена

• Один PDA → много минтов — обрабатывает мошенников, которые переиспользуют PDA для нескольких токенов

Обнаружение фейковых заявок

Некоторые пользователи вызывают инструкцию claim_social_fee_pda для случайных PDA токенов, где у них нет комиссий для получения. Бот обнаруживает такие вызовы, проверяя:

1. Дискриминатор инструкции совпадает с claim_social_fee_pda

2. В логах транзакции нет события SocialFeePdaClaimed — ИЛИ событие показывает amountLamports = 0

3. Идентификатор пользователя GitHub и платформа по-прежнему извлекаются из аргументов инструкции (формат Anchor Borsh)

Фейковые заявки публикуются с предупреждением ⚠️ FAKE CLAIM и сигналом доверия 🚩 Fake claim — no fees paid out.

Отслеживание первых заявок

ClaimTracker поддерживает постоянный набор идентификаторов пользователей GitHub, которые успешно подали заявку:

• Набор в памяти для быстрого поиска во время обработки

• Отложенная запись на диск (задержка 5 секунд) в data/github-first-claims.json

• Раздельный паттерн проверки/отметки: hasGithubUserClaimed() проверяет без побочных эффектов, markGithubUserClaimed() вызывается только после успешной публикации в Telegram

• Счетчик заявок: incrementGithubClaimCount() возвращает порядковый номер заявки для каждого пользователя

• Статус первой заявки НЕ устанавливается для фейковых заявок

Трехуровневая проверка первой заявки

1. Локальная дедупликация — пропуск, если уже опубликовано (переживает перезапуски через сохраненный JSON)

2. Проверка в цепочке — lifetimeClaimedLamports == amountLamports подтверждает, что это действительно первая заявка в цепочке

3. Безопасный откат — пропускает баннер первой заявки, если проверка не удалась (предотвращает ложные срабатывания после повторного развертывания)

Пример карточки заявки

🚨🚨🚨 FIRST TIME CLAIM 🚨🚨🚨

🐙 $PUMP — PumpCoin  💹 $45K
  ↳ GitHub dev claimed PumpFun social fees

📊 Claim #1 · 0.1043 SOL lifetime ($15.65)

🏦 0.1043 SOL ($15.65)
  ↳ 8mNp...4rWz

👤 nirholas (Nicholas)
  ↳ 📦 45 · 👁 200 · 📅 5y ago
  TypeScript SDK builder
𝕏 nichxbt · 1.2K

📈 Bonding curve (72%) · Created 3h ago · 💬 12
𝕏 @pump_coin · 💬 TG · 🌐 pumpcoin.io

⚠️ GitHub account created 15d ago

CA: 7xKXt...p3Bz
Axiom · GMGN · Padre

🔍 TX

Требования

• Node.js >= 20.0.0

• Токен бота Telegram (через @BotFather)

• Канал Telegram с ботом, добавленным как администратор

• RPC-эндпоинт Solana — рекомендуется выделенный RPC (Helius, QuickNode, Triton). Публичная mainnet работает, но может ограничивать частоту запросов.

• Токен GitHub (необязательно) — повышает лимит API с 60 до 5 000 запросов в час

Устранение неполадок

Бот не публикует сообщения

1. Проверьте права бота — бот должен быть администратором канала с правом "Отправка сообщений"

2. Проверьте CHANNEL_ID — используйте @channel_name для публичных каналов или числовой ID (например, -100xxx) для приватных. Чтобы найти числовой ID, перешлите сообщение из канала @userinfobot

3. Ошибка Telegram 403 — означает, что бот НЕ является участником/администратором канала. Добавьте его через настройки канала → Администраторы → Добавить администратора

4. Проверьте логи — установите LOG_LEVEL=debug, чтобы видеть все события, которые обрабатывает бот

Ограничение частоты запросов

Telegram ограничивает ботов примерно 30 сообщениями в секунду на канал. Фреймворк grammY автоматически обрабатывает ограничение частоты:

• Сообщения могут задерживаться, но не будут отброшены

• Бот включает помощник повтора, который учитывает заголовки retry_after

• При очень высокой активности увеличьте POLL_INTERVAL_SECONDS, чтобы уменьшить объем событий

Проблемы с RPC-подключением

• Публичные RPC-эндпоинты имеют ограничения частоты — для продакшена используйте выделенный RPC

• Установите SOLANA_RPC_URLS с несколькими эндпоинтами для автоматического переключения

• Если WebSocket отключается, бот переключается на HTTP-опрос с интервалом POLL_INTERVAL_SECONDS

• Класс RpcFallback обеспечивает циклический перебор настроенных эндпоинтов

• Установите LOG_LEVEL=debug, чтобы видеть статус подключения

Отсутствующие заявки

• Только заявки GitHub? — установите REQUIRE_GITHUB=true, чтобы публиковать только заявки на социальные комиссии GitHub

• Лента отключена? — проверьте, что установлено FEED_CLAIMS=true

• SocialFeeIndex медленный? — начальная инициализация загружает ~148K аккаунтов. Это занимает 30-60 секунд при запуске. Проверьте логи на наличие SocialFeeIndex: loaded N mappings

• Ограничение частоты? — GitHub API позволяет 60 запросов/час без аутентификации. Установите GITHUB_TOKEN для 5 000 запросов/час

Статистика конвейера

Бот записывает счетчики конвейера каждые 60 секунд:

Pipeline: 15 total → 8 social → 3 first / 5 repeat → 8 posted (skip: 7 cashback)

• total: все полученные события заявок

• social: заявки на социальные комиссии GitHub PDA

• first/repeat: впервые подавшие vs. повторные заявители

• posted: успешно опубликовано в Telegram

• skip cashback: кэшбэк-заявки (возвраты пользователям, не активность создателей)

Веб-панель

В репозиторий включены два React-фронтенда, и это не одно и то же приложение:

Перечисленные ниже возможности описывают web/web/. Оба каталога сегодня собираются без ошибок; объединение их в один — всё ещё открытая задача.

Глубокие ссылки (/dashboard, /docs, ...) — это клиентские маршруты, поэтому любой статический хостинг должен перенаправлять неизвестные пути на index.html. Каждое приложение теперь поставляется с vercel.json, содержащим такое перенаправление; на хостинге, отличном от Vercel, настройте эквивалентный SPA-fallback.

Страницы

Возможности панели управления

• Server-Sent Events (SSE) — потоковая передача в реальном времени через /api/v1/claims/stream с автоматическим переподключением (задержка 3 с)

• Фильтры событий — Все, Запуски, Киты, Выпуски, Клеймы, Распределения

• Живая панель статистики — счётчики для каждого типа событий

• Списки наблюдения — добавление/удаление адресов кошельков для мониторинга (GET/POST/DELETE /api/v1/watches)

• Богатые карточки событий — запуски токенов, сделки китов, выпуски, клеймы комиссий с полным контекстом

• Статус подключения — визуальный индикатор с сообщениями об ошибках

• Резервные мок-данные — имитация ленты, когда SSE недоступен

Технологический стек

MCP-сервер

Бот включает встроенный Model Context Protocol (MCP) сервер, который позволяет ИИ-ассистентам (Claude, Copilot, Cursor и др.) запрашивать ончейн-данные PumpFun в диалоговом режиме.

MCP-инструменты

Использование: транспорт Stdio (Claude Desktop / Cursor / VS Code)

Добавьте в конфигурацию вашего MCP-клиента (например, claude_desktop_config.json):

{
  "mcpServers": {
    "pumpfun": {
      "command": "npx",
      "args": ["pumpfun-claims-bot"]
    }
  }
}

Или запустите из исходников:

# Development (tsx)
npm run mcp:dev

# Production (compiled)
npm run build && npm run mcp

Использование: потоковый HTTP-транспорт (встроенный)

Запускается вместе с основным ботом при установке MCP_ENABLED=true:

MCP_ENABLED=true MCP_PORT=3001 npm run dev

Конечная точка MCP доступна по адресу POST /mcp на настроенном порту. Клиенты подключаются с использованием потокового HTTP-транспорта.

Примеры запросов

После подключения спросите вашего ИИ-ассистента:

• «Найди информацию о токене по адресу минта 7xKXt...p3Bz»

• «Подавал ли пользователь GitHub 12345 когда-либо клеймы на комиссии PumpFun?»

• «Кто крупнейшие держатели этого токена?»

• «Проверь, был ли запуск этого токена бандлом»

• «Какая текущая цена SOL?»

API проверки состояния

Бот предоставляет HTTP-сервер проверки состояния для проб Railway / Docker.

Ответ:

{
  "status": "ok",
  "uptime": "12345s",
  "uptimeMs": 12345000
}

• Возвращает 200 для ok, 503 для degraded

• Динамическая статистика внедряется через колбэк (счётчики конвейера, статус подключения)

• Порт настраивается через переменные окружения PORT или HEALTH_PORT (по умолчанию: 3000)

Тестирование

Проект использует Vitest: 203 теста в 11 наборах, все проходят при npm test.

# Run all tests
npm test

# Watch mode (re-runs on file changes)
npm run test:watch

Наборы тестов

Каждый набор находится в src/__tests__/ (плюс fixtures.ts — общие примеры данных).

Локальная разработка

# Install dependencies
npm install

# Run with hot reload (tsx)
npm run dev

# Type-check without emitting
npm run typecheck

Установите LOG_LEVEL=debug — все события записываются в stdout независимо от того, публикуются ли они в Telegram.

Технологический стек

Участие в разработке

Вклад приветствуется! См. CONTRIBUTING.md с рекомендациями.

1. Сделайте форк репозитория

2. Создайте ветку для функции (git checkout -b feat/my-feature)

3. Запустите тесты (npm test) и проверку типов (npm run typecheck)

4. Откройте Pull Request

Безопасность

Нашли уязвимость? Пожалуйста, сообщите о ней ответственно — см. SECURITY.md.

Лицензия

Все права защищены. См. LICENSE.

Документация

Полный сайт документации: https://nirholas.github.io/pumpfun-claims-bot/

• Начало работы — установка и первый запуск.

• Примеры — готовые фрагменты для копирования.