pumpfun-claims-bot
A read-only MCP server for querying PumpFun on-chain and enrichment data conversationally from AI assistants (Claude, Cursor, VS Code).
Look up token metadata —
get_token_inforeturns market cap, bonding curve progress, and flags for a mintAnalyze holders —
get_token_holderslists top holders with concentration metricsReview recent trading —
get_token_tradesgives volume and buy/sell countsCheck graduated pools —
get_pool_liquidityreturns PumpSwap AMM liquidity (optionally with USD market cap context)Screen for scam signals —
get_bundle_infodetects bundled launchesVet creators —
get_creator_profileshows launch count, scam estimate, and recent coins for a walletEnrich GitHub identities —
get_github_userfetches profile, repos, followers, and account age by username or numeric IDVerify claim status —
get_claim_historyreports whether a GitHub user claimed, how many times, and which mintsPrice SOL —
get_sol_pricereturns the current SOL/USD rateAll tools are read-only and synchronous (
taskSupport: forbidden); every tool exceptget_sol_priceandget_github_userrequires an explicit address argument
Fetches GitHub user profiles, repositories, follower counts, and account details to enrich token claim cards with developer reputation and credibility scoring.
Monitors Solana blockchain for PumpFun claim events and token graduations, providing real-time on-chain data for enrichment and alerting.
Publishes real-time PumpFun claim and graduation cards to a Telegram channel, including rich media and formatted messages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pumpfun-claims-bot show recent GitHub social fee claims with credibility scores"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PumpFun Claims Bot
Looking for interactive monitoring? The telegram-bot supports watch management, group chats, REST API, SSE streaming, and webhooks. Use this channel-bot for simple broadcast-only channels.
Related Source
Pump.fun GitHub Claims — nirholas/pumpfun-github-claims
is a focused companion repository for the @pumpfunclaims
feed. It provides standalone bot source and documentation for first reward
claims per GitHub developer and coin, with previous claimed coins as context.
Its implementation status
tracks the remaining coin-attribution work. This repository offers the broader
toolkit, including web dashboards, an MCP server, credibility scoring and
developer reputation tracking. Both repositories remain available as sources.
Related MCP server: Solana Token Launch Scanner
Features
What a GitHub claim actually proves
A claim card starts with a real on-chain withdrawal from a Pump.fun GitHub social-fee account. That is useful evidence, but it is not automatically proof that the GitHub user created, owns, or endorses a coin. Token metadata is user-supplied, lookalike accounts exist, and one social-fee account can be shared by several coins.
Label | Meaning |
Verified GitHub Fee Claim | Claiming GitHub user exactly matches the owner of the repository linked in token metadata. |
Creator-Wallet GitHub Fee Claim | Recipient wallet also created the token, but repository ownership was not established. |
Identity Mismatch | Claiming username differs from the linked repository owner; treat lookalikes as a red flag. |
Unverified | Withdrawal is real, but the GitHub-to-coin relationship is not proven. |
Unresolved Pooled | The fee account maps to multiple coins, so no primary CA or per-coin amount is selected. |
“First-ever” refers to the GitHub fee account, not necessarily the displayed coin. Trade buttons are shown only for verified repository or creator-wallet relationships. The feed is discovery evidence, never an endorsement.
Feed Types
Feed | Description | Toggle |
GitHub Social Fee Claims | GitHub devs claiming PumpFun social fee PDA rewards |
|
Token Graduations | Tokens graduating from bonding curve to PumpAMM |
|
Claim Intelligence
Every GitHub social fee claim card includes:
Feature | Description |
🟢 Credibility Score | Deterministic 0-100 verdict (Strong/Moderate/Caution/High Risk) synthesised from every trust signal, with a transparent ±factor breakdown |
📊 Dev Track Record | Persistent per-developer reputation — a repeat dev's prior tokens and their average credibility, so a serial fee-farmer whose newest coin looks clean is exposed on sight |
🚨 First-Time Alert |
|
⚠️ Fake Claim Detection | Detects when |
📊 Claim Counter | Sequential claim number tracked persistently across restarts |
💹 Lifetime SOL | Total SOL claimed from the PDA over all time |
👤 GitHub Profile | Username, bio, repos, followers, account age, location, blog |
𝕏 Social Links | Twitter/X profile with follower counts (from GitHub profile) |
🏅 Influencer Badge | Tier-based badge for high-follower GitHub/X accounts |
📈 Token Intel | Graduated/bonding curve status, curve progress %, created age, reply count |
🔗 Token Socials | Twitter, Telegram, website links from token metadata |
🏷️ Token Flags | NSFW, banned, cashback status indicators |
⚠️ Trust Signals | Warnings for new GitHub accounts (< 30 days), zero repos, fake claims |
🔗 Trading Links | Axiom, GMGN, Padre links with affiliate codes |
️ Token Image | Token image or GitHub avatar as photo card |
Graduation Cards
Rich graduation cards include creator profile, top holders analysis, 24h trading volume, dev wallet activity, pool liquidity, and bundle detection.
Influencer Tier System
Combines GitHub and X/Twitter follower data to classify claimers:
Tier | Badge | X Followers | GitHub Followers |
Mega | 🔥🔥 MEGA INFLUENCER | ≥ 100K | ≥ 10K |
Influencer | 🔥 Influencer | ≥ 10K | ≥ 1K |
Notable | ⭐ Notable | ≥ 1K | ≥ 100 |
Either threshold triggers the tier — a user with 50K X followers and 50 GitHub followers still qualifies as Influencer.
Credibility Score & Dev Track Record
Every claim card leads with a deterministic 0-100 credibility verdict synthesised from the trust signals the bot already gathers, plus the claiming dev's persistent track record across prior tokens.
The score is deterministic and transparent — same inputs always produce the same number, no model call, and every point is attributed to a named factor shown under the headline:
Tier | Badge | Score |
Strong | 🟢 | 75-100 |
Moderate | 🟡 | 55-74 |
Caution | 🟠 | 35-54 |
High Risk | 🔴 | 0-34 |
Scoring starts at a neutral 50 and adjusts by weighted factors: claim verification (+22, or -20 on a GitHub-owner mismatch), account age (+14 for 5y+ down to -18 for < 30 days), public repos, followers, starred non-fork repo, copycats (-10/-16), bundling, holder concentration, prior rugs, and bans.
Dev track record turns that one-shot score into memory. Every score is recorded against the claiming GitHub user id and persisted, so the next time that dev launches a token the card shows their history — exposing a serial fee-farmer whose newest coin looks clean, and crediting a builder with a real record:
🟢 Credibility: 100/100 · Strong
↑ claim verified · GitHub 6y · 42 repos · repo 150★
📊 Dev track record: 3 prior tokens · avg 🔴 19/100 (High Risk)Logic lives in src/credibility.ts (pure scoreCredibility) and src/dev-reputation.ts (persistent store), both fully covered by tests.
Architecture
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 Failover
The RpcFallback class manages multiple Solana RPC endpoints with automatic rotation:
Round-robin rotation after 3 consecutive failures on any endpoint
60-second cooldown per failed endpoint before retrying
Earliest-expiry fallback — if all endpoints are in cooldown, picks the one expiring soonest
Success resets — a single successful call resets the failure counter
Configure via
SOLANA_RPC_URLS(comma-separated)
Programs Monitored
Program | ID | Purpose |
PumpFees |
| Fee sharing, social fee PDA claims |
Pump |
| Bonding curve (graduations) |
PumpAMM |
| AMM (graduated pool events) |
Claim instructions decoded (v1 and the V2 variants from the October 2026 upgrade):
Instruction | Program | Notes |
| PumpFees | GitHub social fee claims; V2 can pay in a quote mint such as USDC |
| Pump | Creator vault to creator |
| Pump | Creator fees split to shareholders |
| PumpAMM | Pool creator fees moved back to the Pump vault (no payout event) |
| PumpAMM | Pool creator fees to creator |
| Pump, PumpAMM | Trader cashback |
sweep_creator_fee and sweep_protocol_fee (Pump and PumpAMM) are recognised but are never counted as a claim: a sweep only moves fees the curve or pool still holds into the creator vault, and pays nobody. A claim transaction usually carries a sweep first, then the claim; only the claim (vault to creator) is reported, and each claim is paid by its own event, so nothing is counted twice. A sweep-only transaction posts nothing.
Event decoders read the fields they need from the known prefix and ignore trailing bytes, so both pre-upgrade events and the longer October 2026 layouts decode. Since synthetic migration a curve completes inside the completing buy (CompleteEvent) and migrate later opens the pool (CompletePumpAmmMigrationEvent); the graduation feed posts each mint once, on whichever event it sees first.
Install
npm (MCP server — recommended for AI assistants)
Run the MCP server instantly with npx — no clone needed:
npx pumpfun-claims-botOr install globally:
npm install -g pumpfun-claims-bot
pumpfun-claims-botAdd to your MCP client config (Claude Desktop, Cursor, VS Code Copilot):
{
"mcpServers": {
"pumpfun": {
"command": "npx",
"args": ["pumpfun-claims-bot"]
}
}
}npm package: pumpfun-claims-bot on npm
From source (full bot + Telegram feed)
git clone https://github.com/nirholas/pumpfun-claims-bot.git
cd pumpfun-claims-bot && npm installQuick Start
1. Create a Telegram Bot
Message @BotFather on Telegram
/newbot→ follow prompts → copy the bot tokenCreate a public channel (e.g.,
@pumpfunclaims)Add the bot as an admin to the channel (must have "Post Messages" permission)
2. Configure Environment
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_FEE_DISTRIBUTIONS=false # distribute_creator_fees payouts, with REQUIRE_GITHUB=false (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
# 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)
LOG_LEVEL=info # debug | info | warn | error (default: info)
LOG_FORMAT=text # text | json, one JSON object per line (default: text)
# ── Health Check ──────────────────────────────────────────
# PORT=3000 # Set automatically by RailwayEnvironment Variables Reference
Variable | Required | Default | Description |
| ✅ | — | Bot token — message @BotFather → |
| ✅ | — | Channel to post to ( |
| ✅ |
| Primary Solana HTTP RPC — free tier at Helius, QuickNode, or Alchemy |
| — | Derived from | Solana WebSocket URL — same provider as |
| — | — | Comma-separated fallback RPC URLs — auto-rotates on 429 / 5xx / timeout |
| — |
| Post GitHub social fee claim cards |
| — |
| Post token graduation cards |
| — |
| Post |
| — |
| Skip claims that have no GitHub social fee PDA |
| — | — | GitHub PAT — create one here (no scopes needed) — raises rate limit from 60 → 5000 req/hr |
| — | — | X/Twitter |
| — | — | X/Twitter |
| — | — | Affiliate ref code for Axiom trading links |
| — | — | Affiliate ref code for GMGN trading links |
| — | — | Affiliate ref code for Padre trading links |
| — |
| HTTP polling interval when WebSocket is unavailable |
| — |
| Log verbosity: |
| — |
|
|
| — |
| Health check HTTP server port — set automatically by Railway |
| — |
| Enable the MCP (Model Context Protocol) server for AI assistant integrations |
| — |
| MCP server HTTP port (Streamable HTTP transport) |
3. Run
# Install dependencies
npm install
# Development (hot reload via tsx)
npm run dev
# Production
npm run build
npm start4. Deploy with Docker
docker build -t pumpfun-channel-bot .
docker run -d --env-file .env pumpfun-channel-bot5. Deploy to Railway
Railway auto-deploys from GitHub and provides persistent volumes for claim tracking data.
# 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 upSee railway.json for the deployment config:
{
"$schema": "https://railway.app/railway.schema.json",
"build": {
"builder": "DOCKERFILE",
"dockerfilePath": "Dockerfile"
},
"deploy": {
"restartPolicyType": "ON_FAILURE",
"restartPolicyMaxRetries": 10
}
}Project Structure
pumpfun-claims-bot/
├── src/
│ ├── index.ts # Entry point — wires monitors, enrichment, & Telegram posting
│ ├── config.ts # Environment variable loading & validation (fails fast on bad values)
│ ├── first-claim.ts # First-claim decision (local state, lifetime, PDA and wallet history)
│ ├── channel-publisher.ts # Telegram sends with typed retries, photo/text fallback, length limits
│ ├── telegram-html.ts # Escaping, http(s)-only links and message fitting for Telegram HTML
│ ├── 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)
│ ├── 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
│ ├── rpc-fallback.ts # Multi-RPC failover with round-robin
│ ├── health.ts # HTTP health check server
│ ├── persistence.ts # Atomic JSON state files under DATA_DIR
│ ├── bounded.ts # Size-capped sets, maps and TTL caches
│ ├── json-fields.ts # Typed readers for untrusted API JSON
│ ├── pump-events.ts # Anchor event decoders (claims, completion, migration)
│ ├── claim-attribution.ts # Which instruction in a claim transaction is the payout
│ ├── types.ts # Program IDs, discriminators, event types
│ └── logger.ts # Leveled logger (text or JSON lines)
├── src/__tests__/ # Vitest suites + shared fixtures
├── web/web/ # React dashboard prototype (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.jsonHow It Works
Claim Detection Pipeline
Transaction detected on PumpFees program
│
▼
Skip sweep_creator_fee / sweep_protocol_fee (not a payout)
│
▼
Identify instruction: claim_social_fee_pda or claim_social_fee_pda_v2?
│
├─ 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 Bootstrap
On startup, the bot fetches all SharingConfig accounts from the PumpFees program to build a reverse mapping from social fee PDA addresses to token mints. This enables resolving which token a social fee claim belongs to without additional RPC calls.
~148K mappings loaded at startup
Incremental updates via WebSocket subscription on
CreateFeeSharingConfigandUpdateFeeShareseventsLookup:
socialFeeIndex.getMintForPda(pdaAddress)→ token mintOne PDA → many mints — handles scammers who reuse PDAs across multiple tokens
Fake Claim Detection
Some users call the claim_social_fee_pda instruction targeting random token PDAs where they have no fees to collect. The bot detects these by checking:
The instruction discriminator matches
claim_social_fee_pdaorclaim_social_fee_pda_v2The transaction logs contain no
SocialFeePdaClaimedevent — OR the event showsamountLamports = 0The GitHub user ID and platform are still parsed from the instruction args (Anchor Borsh format)
Fake claims are posted with a ⚠️ FAKE CLAIM warning and a 🚩 Fake claim — no fees paid out trust signal.
First-Claim Tracking
The ClaimTracker maintains a persistent set of GitHub user IDs that have successfully claimed:
In-memory set for fast lookup during processing
Debounced disk persistence (5-second delay) to
data/github-first-claims.jsonSplit check/mark pattern:
hasGithubUserClaimed()checks without side effects,markGithubUserClaimed()only called after successful Telegram postClaim counter:
incrementGithubClaimCount()returns sequential claim number per userFirst-claim status is NOT set for fake claims
Three-Layer First-Claim Verification
Local dedup — Skip if already posted (survives restarts via persisted JSON)
On-chain verification —
lifetimeClaimedLamports == amountLamportsconfirms it's truly the first claim on-chainGraceful fallback — Skips first-claim banner if verification fails (prevents false positives after redeployment)
Example Claim Card
🚨🚨🚨 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
🔍 TXRequirements
Node.js >= 20.0.0
Telegram bot token (via @BotFather)
Telegram channel with the bot added as admin
Solana RPC endpoint — dedicated RPC recommended (Helius, QuickNode, Triton). Public mainnet works but may rate-limit.
GitHub token (optional) — raises API rate limit from 60 to 5,000 req/hr
Troubleshooting
Bot Not Posting Messages
Check bot permissions — The bot must be an admin in the channel with "Post Messages" permission
Verify CHANNEL_ID — Use
@channel_namefor public channels or the numeric ID (e.g.,-100xxx) for private channels. To find the numeric ID, forward a channel message to @userinfobotTelegram 403 error — Means the bot is NOT a member/admin of the channel. Add it via channel settings → Administrators → Add Administrator
Check logs — Set
LOG_LEVEL=debugto see all events the bot processes
Rate Limiting
Telegram limits bots to ~30 messages per second to a channel. The grammY framework handles rate limiting automatically:
Messages may be delayed but won't be dropped
The bot includes a retry helper that respects
retry_afterheadersFor very high activity, increase
POLL_INTERVAL_SECONDSto reduce event volume
RPC Connection Issues
Public RPC endpoints have rate limits — for production use a dedicated RPC
Set
SOLANA_RPC_URLSwith multiple endpoints for automatic failoverIf WebSocket disconnects, the bot falls back to HTTP polling at
POLL_INTERVAL_SECONDSThe
RpcFallbackclass provides round-robin across configured endpointsSet
LOG_LEVEL=debugto see connection status
Missing Claims
GitHub claims only? — Set
REQUIRE_GITHUB=trueto only post GitHub social fee claimsFeed disabled? — Verify
FEED_CLAIMS=trueis setSocialFeeIndex slow? — Initial bootstrap fetches ~148K accounts. This takes 30-60 seconds on startup. Check logs for
SocialFeeIndex: loaded N mappingsRate limited? — GitHub API allows 60 req/hr unauthenticated. Set
GITHUB_TOKENfor 5,000 req/hr
Pipeline Stats
The bot logs pipeline counters every 60 seconds:
Pipeline: 15 total → 8 social → 3 first / 5 repeat → 8 posted (skip: 7 cashback)total: All claim events received
social: GitHub social fee PDA claims
first/repeat: First-time vs. returning claimers
posted: Successfully posted to Telegram
skip cashback: Cashback claims (user refunds, not creator activity)
Web Dashboard
web/web/ holds a React dashboard (React 18, React Router 7, Vite, Tailwind).
Build it with cd web/web && npm ci && npm run build; deep links such as
/dashboard are client-side routes, so a static host must rewrite unknown paths
to index.html (vercel.json does this on Vercel).
The dashboard expects an API this bot does not serve: an SSE stream at
/api/v1/claims/stream and watch lists at /api/v1/watches (set VITE_API_URL
to point at one). Against this bot it falls back to simulated events, so treat it
as a UI prototype, not a live view of the channel.
Pages
Page | Route | Description |
Home |
| Landing page with project overview |
Dashboard |
| Event feed (SSE when an API is configured, simulated otherwise) |
Create Coin |
| Token creation interface |
Docs |
| API documentation & Telegram commands |
Packages |
| Package browser |
Dashboard Features
Server-Sent Events (SSE) — Real-time streaming via
/api/v1/claims/streamwith auto-reconnect (3s delay)Event Filters — filter the (simulated) feed by event type
Live Stats Bar — Counters for each event type
Watch Lists — Add/remove wallet addresses to monitor (
GET/POST/DELETE /api/v1/watches)Connection Status — Visual indicator with error messages
Mock Data Fallback — Simulated feed when SSE is unavailable
Tech Stack
Layer | Technology |
Framework | React 18 |
Router | React Router 7 |
Build | Vite 6 |
Styling | Tailwind CSS |
Language | TypeScript |
MCP Server
The bot includes a built-in Model Context Protocol (MCP) server that lets AI assistants (Claude, Copilot, Cursor, etc.) query PumpFun on-chain data conversationally.
MCP Tools
Tool | Description |
| Token metadata, market cap, bonding curve progress, flags |
| Top holders with concentration metrics |
| Recent trade activity — volume, buy/sell counts |
| PumpSwap AMM pool liquidity for graduated tokens |
| Bundle detection (scam indicator) |
| Creator launch history, scam estimate, recent coins |
| GitHub profile by username or numeric ID |
| Claim status for a GitHub user — count, mints claimed |
| Current SOL/USD price |
Usage: Stdio Transport (Claude Desktop / Cursor / VS Code)
Add to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"pumpfun": {
"command": "npx",
"args": ["pumpfun-claims-bot"]
}
}
}Or run from source:
# Development (tsx)
npm run mcp:dev
# Production (compiled)
npm run build && npm run mcpUsage: Streamable HTTP Transport (Embedded)
Run alongside the main bot by setting MCP_ENABLED=true:
MCP_ENABLED=true MCP_PORT=3001 npm run devThe MCP endpoint is available at POST /mcp on the configured port. Clients connect using the Streamable HTTP transport.
Example Queries
Once connected, ask your AI assistant:
"Look up token info for mint address 7xKXt...p3Bz"
"Has GitHub user 12345 ever claimed PumpFun fees?"
"Who are the top holders of this token?"
"Check if this token launch was bundled"
"What's the current SOL price?"
Health Check API
The bot exposes an HTTP health check server for Railway / Docker probes.
Endpoint | Method | Description |
| GET | Health status with uptime and stats |
| GET | Alias for |
Response:
{
"status": "ok",
"uptime": "12345s",
"uptimeMs": 12345000
}Returns 200 for
ok, 503 fordegradedDynamic stats injected via callback (pipeline counters, connection status)
Port configurable via
PORTorHEALTH_PORTenv vars (default: 3000)
Testing
The project uses Vitest: 204 tests across 12 suites, all green on npm test.
# Run all tests
npm test
# Watch mode (re-runs on file changes)
npm run test:watchTest Suites
Every suite lives in src/__tests__/ (plus fixtures.ts, shared sample data).
Suite | File | Coverage |
Claim Tracker |
| First-claim detection, persistence, counters, lifetime totals |
MCP Stdio |
| CLI initialization, tool discovery, release version, and clean protocol output |
Claim Routing |
| Which claims are posted, skipped, or routed to which feed |
Credibility |
| Deterministic 0-100 scoring, per-factor attribution, tier bounds |
Dev Reputation |
| Persistent per-developer track record and averages |
Formatters |
| HTML card generation, escaping, null handling, edge cases |
GitHub Client |
| URL parsing, id/login validation, API response handling |
Pump Client |
| Token, holder, trade, and creator API response handling |
RPC Fallback |
| Round-robin rotation, cooldowns, retryable error handling |
X Client |
| Influencer tiers, handle parsing, profile parsing |
E2E Pipeline |
| End-to-end claim tracking, formatting, GitHub feed |
First Claim |
| Every branch of the first-claim decision |
Channel Publisher |
| Telegram retry policy, photo/text fallback, length limit |
Telegram HTML |
| Escaping, safe links, sanitising, message fitting |
Config |
| Defaults and startup validation of every variable |
MCP HTTP |
| Concurrent sessions, input validation, unknown sessions |
Monitors |
| web3.js 3 responses, graduation polling and dedup |
Persistence |
| Atomic state files, size-capped collections |
Local Development
# Install dependencies
npm install
# Run with hot reload (tsx)
npm run dev
# Type-check without emitting
npm run typecheckSet LOG_LEVEL=debug — all events are logged to stdout regardless of whether they're posted to Telegram.
Tech Stack
Component | Technology |
Runtime | Node.js >= 20 (ESM) |
Language | TypeScript 5.7 (strict mode) |
Blockchain | Solana via |
Telegram | grammY framework |
Frontend | React 18 + Vite 5 + Tailwind CSS |
Testing | Vitest |
Container | Docker (multi-stage Alpine, non-root) |
MCP |
|
Hosting | Railway (auto-deploy from GitHub) |
Dependencies | 6 production, 4 dev — intentionally minimal |
Contributing
Contributions are welcome! See CONTRIBUTING.md for guidelines.
Fork the repo
Create a feature branch (
git checkout -b feat/my-feature)Run tests (
npm test) and typecheck (npm run typecheck)Open a Pull Request
Security
Found a vulnerability? Please report it responsibly — see SECURITY.md.
License
All rights reserved. See LICENSE.
Documentation
Full documentation site: https://nirholas.github.io/pumpfun-claims-bot/
Getting started covers install and first run.
Examples has copy-paste snippets.
Star History
Support the project
If pumpfun-claims-bot saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.
Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit
Built for AI agents too
Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/pumpfun-claims-bot and it has the context it needs.
More from the same author
All repositories by nirholas: the full catalog, grouped by topic
three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
Questions or ideas: open an issue or start a discussion
Contributors
Available Tools
9 toolsget_bundle_infoC
Detect if a token launch was bundled (scam indicator)
Inputs: mint (required).
get_claim_historyA
Check claim history for a GitHub user — whether they have claimed, claim count, and which token mints they claimed from
Inputs: githubUserId (required).
get_creator_profileA
Fetch PumpFun creator profile — username, launch count, scam estimate, recent coins
Inputs: wallet (required).
get_github_userB
Fetch GitHub user profile by username or numeric ID — repos, followers, bio, account age
Inputs: userId, username.
get_pool_liquidityB
Fetch PumpSwap AMM pool liquidity for a graduated token
Inputs: mint (required), usdMarketCap.
get_sol_priceA
Fetch current SOL/USD price
Inputs: no named parameters.
get_token_holdersB
Fetch top holders for a PumpFun token including concentration metrics
Inputs: mint (required).
get_token_infoB
Fetch PumpFun token metadata, market cap, bonding curve progress, and flags
Inputs: mint (required).
get_token_tradesB
Fetch recent trade activity for a PumpFun token (volume, buy/sell counts)
Inputs: mint (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools target distinct resources or actions: token metadata, holders, trades, liquidity, bundle detection, creator profile, GitHub profile, claim history, and SOL price. There is minor conceptual overlap between get_token_info flags and get_bundle_info, and between creator/GitHub profile lookups, but the boundaries are clear enough for selection.
All tools use the same get_ + snake_case noun phrase convention. Names are predictable and consistently structured across the entire set.
Nine tools is well-scoped for a PumpFun claims/analytics server, with each tool covering a distinct data retrieval need. No obvious redundancy or excessive surface area.
The surface covers token analytics, creator/GitHub identity, claim history, and SOL pricing, but despite the server being a claims bot there is no tool to actually submit or manage a claim. This is a notable lifecycle gap if claim execution is in scope.
Maintenance
Related MCP Connectors
Solana + pump.fun intel for agents: launch verdicts, token risk, dev/wallet records, smart money.
Solana + pump.fun intel for agents: launch verdicts, token risk, dev/wallet records, smart money.
Live Solana memecoin data: token scores, bundle detection, wallet and deployer history.
Live signals, trader intel and alerts from top fomo, pump.fun and hyperliquid traders. Read-only.
Related MCP Servers
- AlicenseAqualityDmaintenanceReal-time radar for Solana memecoins, Pump.fun launches, and KOL trades.86MIT
- AlicenseNot gradedqualityCmaintenanceScans new Solana token launches from pump.fun, Raydium, PumpSwap, and Orca with liquidity and holder data. Pay-per-call via x402 micropayments.MIT
- AlicenseAqualityBmaintenanceRug pull risk scores and on-chain forensics for memecoins on Solana, Ethereum, Base and Robinhood Chain - launch-bundle detection, funding-origin tracing, deployer history, insider networks and whale flow. 15 read-only tools.1517 npmMIT
- AlicenseAqualityBmaintenanceEnables agents to query real-time labelled pump.fun intelligence—launch risk cards, creator reputation, rug/graduation flags, wallet profiles, and market regime—with paid endpoints settled per request via x402 USDC on Solana and free sample/regime tools.271MIT