██████╗ ██╗   ██╗███╗   ███╗██████╗     ███████╗██████╗ ██╗  ██╗
██╔══██╗██║   ██║████╗ ████║██╔══██╗    ██╔════╝██╔══██╗██║ ██╔╝
██████╔╝██║   ██║██╔████╔██║██████╔╝    ███████╗██║  ██║█████╔╝ 
██╔═══╝ ██║   ██║██║╚██╔╝██║██╔═══╝     ╚════██║██║  ██║██╔═██╗ 
██║     ╚██████╔╝██║ ╚═╝ ██║██║         ███████║██████╔╝██║  ██╗
╚═╝      ╚═════╝ ╚═╝     ╚═╝╚═╝         ╚══════╝╚═════╝ ╚═╝  ╚═╝

⚡ See it in action

📖 Table of Contents

• Why Pump SDK? — What makes it different
• Quick Start (30 seconds) — Copy-paste and go
• Installation — npm, yarn, or pnpm
• Token Lifecycle — Bonding curve → graduation → AMM
• Usage Examples — Create, buy, sell, AMM, fees, cashback
• Analytics — Price impact, graduation, token price
• Architecture — Offline & online SDK layers
• Programs — 4 on-chain program addresses
• WebSocket Relay — Real-time token launch feed
• Live Dashboards — Browser-based monitoring
• MCP Server — 53 tools for AI agents
• Telegram Bot — Fee claim & CTO alerts
• PumpOS Web Desktop — 169 Pump-Store apps
• x402 Payments — HTTP 402 micropayments
• DeFi Agents — 43 production-ready AI agent definitions
• Lair Platform — Unified DeFi Telegram bot
• Plugin.delivery — 17 AI plugin APIs for SperaxOS
• Vanity Generators — Rust (100K+ keys/sec) + TypeScript
• Scripts & Makefile — Production CLI tools
• Testing & CI/CD — 6 GitHub Actions workflows
• Tutorials — 19 hands-on guides
• Documentation — Full guides and references
• Contributing — Help make Pump SDK better

🏆 Why Pump SDK?

✨ Features

📦 Installation

npm install @pump-fun/pump-sdk

yarn add @pump-fun/pump-sdk

pnpm add @pump-fun/pump-sdk

Peer Dependencies

npm install @solana/web3.js @coral-xyz/anchor @solana/spl-token bn.js

🚀 Quick Start

import { Connection, Keypair, Transaction, sendAndConfirmTransaction } from "@solana/web3.js";
import BN from "bn.js";
import {
  OnlinePumpSdk,
  PUMP_SDK,
  getBuyTokenAmountFromSolAmount,
} from "@pump-fun/pump-sdk";

// 1. Connect
const connection = new Connection("https://api.devnet.solana.com", "confirmed");
const sdk = new OnlinePumpSdk(connection);

// 2. Create a token and buy in one transaction
const mint = Keypair.generate();
const global = await sdk.fetchGlobal();
const feeConfig = await sdk.fetchFeeConfig();
const solAmount = new BN(0.5 * 1e9); // 0.5 SOL

const tokenAmount = getBuyTokenAmountFromSolAmount({
  global, feeConfig, mintSupply: null, bondingCurve: null, amount: solAmount,
});

const instructions = await PUMP_SDK.createV2AndBuyInstructions({
  global,
  mint: mint.publicKey,
  name: "My Token",
  symbol: "MTK",
  uri: "https://example.com/metadata.json",
  creator: wallet.publicKey,
  user: wallet.publicKey,
  amount: tokenAmount,
  solAmount,
  mayhemMode: false,
});

// 3. Send it
const tx = new Transaction().add(...instructions);
const sig = await sendAndConfirmTransaction(connection, tx, [wallet, mint]);
console.log("Created & bought:", sig);

[!TIP]
🤖 AI Coding Assistants: Building on Pump protocol?

• npm install @pump-fun/pump-sdk — Token creation, trading, fee sharing
• Works with Claude, GPT, Cursor via MCP server
• See AGENTS.md for integration instructions

🔄 Token Lifecycle

┌─────────────────────────┐                          ┌───────────────────────┐
│     Bonding Curve        │    graduation           │      AMM Pool         │
│     (Pump Program)       │ ─────────────────────►  │      (PumpAMM Program │
│                          │   complete = true       │                       │
│  • createV2              │                         │  • Pool-based swap    │
│  • buy / sell            │                         │  • LP fees            │
│  • Price discovery       │                         │  • Graduated trading  │
└─────────────────────────┘                          └───────────────────────┘

💻 Usage

Create a Token

import { Keypair } from "@solana/web3.js";
import { PUMP_SDK } from "@pump-fun/pump-sdk";

const mint = Keypair.generate();

const instruction = await PUMP_SDK.createV2Instruction({
  mint: mint.publicKey,
  name: "My Token",
  symbol: "MTK",
  uri: "https://example.com/metadata.json",
  creator: wallet.publicKey,
  user: wallet.publicKey,
  mayhemMode: false,
});

import BN from "bn.js";
import { getBuyTokenAmountFromSolAmount } from "@pump-fun/pump-sdk";

const global = await sdk.fetchGlobal();
const feeConfig = await sdk.fetchFeeConfig();
const solAmount = new BN(0.5 * 1e9); // 0.5 SOL

const tokenAmount = getBuyTokenAmountFromSolAmount({
  global, feeConfig, mintSupply: null, bondingCurve: null, amount: solAmount,
});

const instructions = await PUMP_SDK.createV2AndBuyInstructions({
  global,
  mint: mint.publicKey,
  name: "My Token",
  symbol: "MTK",
  uri: "https://example.com/metadata.json",
  creator: wallet.publicKey,
  user: wallet.publicKey,
  amount: tokenAmount,
  solAmount,
  mayhemMode: false,
});

const tx = new Transaction().add(...instructions);
const sig = await sendAndConfirmTransaction(connection, tx, [wallet, mint]);

Buy Tokens

import BN from "bn.js";
import { getBuyTokenAmountFromSolAmount, PUMP_SDK } from "@pump-fun/pump-sdk";

const mint = new PublicKey("...");
const user = wallet.publicKey;
const solAmount = new BN(0.1 * 1e9); // 0.1 SOL

const global = await sdk.fetchGlobal();
const feeConfig = await sdk.fetchFeeConfig();
const { bondingCurveAccountInfo, bondingCurve, associatedUserAccountInfo } =
  await sdk.fetchBuyState(mint, user);

const tokenAmount = getBuyTokenAmountFromSolAmount({
  global, feeConfig,
  mintSupply: bondingCurve.tokenTotalSupply,
  bondingCurve, amount: solAmount,
});

const instructions = await PUMP_SDK.buyInstructions({
  global, bondingCurveAccountInfo, bondingCurve, associatedUserAccountInfo,
  mint, user, solAmount, amount: tokenAmount,
  slippage: 2, // 2% slippage tolerance
});

Sell Tokens

import { getSellSolAmountFromTokenAmount, PUMP_SDK } from "@pump-fun/pump-sdk";

const { bondingCurveAccountInfo, bondingCurve } = await sdk.fetchSellState(mint, user);
const sellAmount = new BN(15_828);

const instructions = await PUMP_SDK.sellInstructions({
  global, bondingCurveAccountInfo, bondingCurve, mint, user,
  amount: sellAmount,
  solAmount: getSellSolAmountFromTokenAmount({
    global, feeConfig,
    mintSupply: bondingCurve.tokenTotalSupply,
    bondingCurve, amount: sellAmount,
  }),
  slippage: 1,
});

Creator Fees

// Check accumulated fees across both programs
const balance = await sdk.getCreatorVaultBalanceBothPrograms(wallet.publicKey);
console.log("Creator fees:", balance.toString(), "lamports");

// Collect fees
const instructions = await sdk.collectCoinCreatorFeeInstructions(wallet.publicKey);

import { PUMP_SDK, isCreatorUsingSharingConfig } from "@pump-fun/pump-sdk";

// 1. Create a sharing config
const ix = await PUMP_SDK.createFeeSharingConfig({ creator: wallet.publicKey, mint, pool: null });

// 2. Set shareholders (shares must total 10,000 bps = 100%)
const ix2 = await PUMP_SDK.updateFeeShares({
  authority: wallet.publicKey,
  mint,
  currentShareholders: [],
  newShareholders: [
    { address: walletA, shareBps: 5000 }, // 50%
    { address: walletB, shareBps: 3000 }, // 30%
    { address: walletC, shareBps: 2000 }, // 20%
  ],
});

// 3. Check & distribute
const result = await sdk.getMinimumDistributableFee(mint);
if (result.canDistribute) {
  const { instructions } = await sdk.buildDistributeCreatorFeesInstructions(mint);
  const tx = new Transaction().add(...instructions);
}

import { PUMP_SDK } from "@pump-fun/pump-sdk";

// Initialize volume tracking (one-time)
const ix = await PUMP_SDK.initUserVolumeAccumulator({
  payer: wallet.publicKey,
  user: wallet.publicKey,
});

// Check unclaimed rewards
const rewards = await sdk.getTotalUnclaimedTokensBothPrograms(wallet.publicKey);
console.log("Unclaimed rewards:", rewards.toString());

// Claim rewards
const instructions = await sdk.claimTokenIncentivesBothPrograms(
  wallet.publicKey, wallet.publicKey,
);

import { PUMP_SDK, canonicalPumpPoolPda } from "@pump-fun/pump-sdk";

const pool = canonicalPumpPoolPda(mint);

// Buy on AMM
const buyIx = await PUMP_SDK.ammBuyInstruction({
  pool,
  user: wallet.publicKey,
  baseAmountOut: new BN(1_000_000), // tokens to receive
  maxQuoteAmountIn: new BN(0.1 * 1e9), // max SOL to spend
});

// Sell on AMM
const sellIx = await PUMP_SDK.ammSellInstruction({
  pool,
  user: wallet.publicKey,
  baseAmountIn: new BN(1_000_000), // tokens to sell
  minQuoteAmountOut: new BN(0.05 * 1e9), // min SOL to receive
});

// Deposit liquidity
const depositIx = await PUMP_SDK.ammDepositInstruction({
  pool,
  user: wallet.publicKey,
  baseTokenAmount: new BN(10_000_000),
  quoteTokenAmount: new BN(1 * 1e9),
  minLpTokenAmount: new BN(1),
});

// Withdraw liquidity
const withdrawIx = await PUMP_SDK.ammWithdrawInstruction({
  pool,
  user: wallet.publicKey,
  lpTokenAmount: new BN(100_000),
  minBaseTokenAmount: new BN(1),
  minQuoteTokenAmount: new BN(1),
});

// Claim from Pump program
const pumpCashback = await PUMP_SDK.claimCashbackInstruction({
  user: wallet.publicKey,
});

// Claim from AMM program
const ammCashback = await PUMP_SDK.ammClaimCashbackInstruction({
  user: wallet.publicKey,
});

// Create a social fee PDA for a user on a platform
const createSocialFee = await PUMP_SDK.createSocialFeePdaInstruction({
  payer: wallet.publicKey,
  userId: "user123",
  platform: "twitter",
});

// Claim social fee PDA
const claimSocialFee = await PUMP_SDK.claimSocialFeePdaInstruction({
  claimAuthority: wallet.publicKey,
  recipient: wallet.publicKey,
  userId: "user123",
  platform: "twitter",
});

📊 Analytics

Offline pure functions for price analysis — no RPC calls needed.

import {
  calculateBuyPriceImpact,
  calculateSellPriceImpact,
  getGraduationProgress,
  getTokenPrice,
  getBondingCurveSummary,
} from "@pump-fun/pump-sdk";

// Price impact of buying 1 SOL worth
const impact = calculateBuyPriceImpact({
  global, feeConfig, mintSupply: bondingCurve.tokenTotalSupply,
  bondingCurve, solAmount: new BN(1e9),
});
console.log(`Impact: ${impact.impactBps} bps, tokens: ${impact.outputAmount}`);

// How close to graduation?
const progress = getGraduationProgress(global, bondingCurve);
console.log(`${(progress.progressBps / 100).toFixed(1)}% graduated`);

// Current price per token
const price = getTokenPrice({ global, feeConfig, mintSupply: bondingCurve.tokenTotalSupply, bondingCurve });
console.log(`Buy: ${price.buyPricePerToken} lamports/token`);

// Full summary in one call
const summary = getBondingCurveSummary({ global, feeConfig, mintSupply: bondingCurve.tokenTotalSupply, bondingCurve });

🏗️ Architecture

The SDK is split into two layers:

┌──────────────────────────────────────────────────────────────────┐
│                        Your Application                          │
├──────────────────────────────┬───────────────────────────────────┤
│      PumpSdk (Offline)       │      OnlinePumpSdk (Online)       │
│                              │                                   │
│  • 42 instruction builders   │  • Fetch on-chain state           │
│  • Decode accounts           │  • Simulate transactions          │
│  • Pure computation          │  • *BothPrograms variants         │
│  • No connection needed      │  • Wraps PumpSdk + Connection     │
│                              │                                   │
│  Export: PUMP_SDK singleton   │  Export: OnlinePumpSdk class      │
├──────────────────────────────┴───────────────────────────────────┤
│  bondingCurve.ts │ analytics.ts │ fees.ts │ pda.ts │ state.ts │ tokenIncentives.ts │
│  tokenIncentives.ts │ errors.ts                                  │
├──────────────────────────────────────────────────────────────────┤
│     Anchor IDLs: pump │ pump_amm │ pump_fees │ mayhem            │
└──────────────────────────────────────────────────────────────────┘

src/
├── index.ts            # Public API — re-exports everything
├── sdk.ts              # PumpSdk — 42 instruction builders, 14 account decoders, 27 event decoders
├── onlineSdk.ts        # OnlinePumpSdk — fetchers + BothPrograms aggregators
├── bondingCurve.ts     # Pure math for price quoting
├── analytics.ts        # Price impact, graduation progress, token price, bonding curve summary
├── fees.ts             # Fee tier calculation logic
├── errors.ts           # Custom error classes
├── pda.ts              # PDA derivation helpers (incl. socialFeePda)
├── state.ts            # 40+ TypeScript types for on-chain accounts & events
├── tokenIncentives.ts  # Volume-based reward calculations
└── idl/                # Anchor IDLs for all three programs
    ├── pump.ts / pump.json           # 29 instructions
    ├── pump_amm.ts / pump_amm.json   # 25 instructions
    └── pump_fees.ts / pump_fees.json # 17 instructions

🔗 Programs

The SDK interacts with four on-chain Solana programs:

📡 WebSocket Relay Server

The WebSocket relay server connects to PumpFun's API, parses new token launches, and broadcasts structured events to browser clients.

cd websocket-server && npm install && npm run dev

Architecture: PumpFun API ◀── SolanaMonitor ──▶ Relay Server (:3099/ws) ──▶ Browsers

Production: wss://pump-fun-websocket-production.up.railway.app/ws

See websocket-server/README.md for setup, message format, and deployment.

📊 Live Dashboards

Two standalone dashboards in live/ for real-time PumpFun monitoring — powered by the WebSocket relay:

Both support multi-endpoint failover and custom RPC endpoint input.

🤖 MCP Server

The included MCP server exposes 53 tools to AI assistants like Claude, GPT, and Cursor — covering the full Pump protocol plus wallet operations.

cd mcp-server && npm install && npm run build

Deploys to Railway, Cloudflare Workers, or Vercel. See mcp-server/README.md for setup.

📡 Telegram Bot + API

The included Telegram bot monitors PumpFun activity on Solana with real-time notifications:

• Fee claims & cashback — Track creator fee claims and cashback rewards for watched wallets
• CTO alerts — Detect creator fee redirection (creator takeover) events
• Token launch monitor — Real-time detection of new token mints with cashback coin flag
• 🎓 Graduation alerts — Notifies when a token completes its bonding curve or migrates to PumpAMM
• 🐋 Whale trade alerts — Configurable SOL threshold for large buy/sell notifications with progress bar
• 💎 Fee distribution alerts — Tracks creator fee distributions to shareholders with share breakdown

10 commands:

Also ships a REST API for programmatic access: per-client watches, paginated claim queries, SSE streaming, and HMAC-signed webhooks.

# Bot only
cd telegram-bot && npm install && npm run dev

# Bot + API
npm run dev:full

# API only (no Telegram)
npm run api

See telegram-bot/README.md for setup and API reference.

🌐 PumpOS Web Desktop

The website is a static HTML/CSS/JS web desktop (PumpOS) featuring:

• 169 Pump-Store apps — DeFi dashboards, trading tools, charts, wallets, Pump SDK tools, and more
• Live trades dashboard — real-time token launches and trades via WebSocket relay
• PWA support — service worker (sw.js), installable web manifest, offline capability
• Wallet connect — in-browser Solana wallet management
• Smart money tracking — on-chain whale and smart money analytics
• Command palette — keyboard-driven navigation and search
• Plugin system — extensible via plugin-demo.html
• BIOS boot screen — animated startup sequence at bios.html
• Built-in API — serverless endpoints for coins, market data, and portfolio
• Bonding curve calculator — interactive constant-product AMM price simulation
• Fee tier explorer — visualize market-cap-based tiered fee schedules
• Token launch simulator — animated token lifecycle from creation to graduation
• SDK API reference — interactive documentation for all 42 SDK methods

website/
├── index.html          # PumpOS desktop shell
├── live.html           # Live token launches + trades dashboard
├── chart.html          # Chart application
├── bios.html           # BIOS boot screen
├── plugin-demo.html    # Plugin system demo
├── sw.js               # Service worker (offline support)
├── Pump-Store/         # 169 installable apps
│   ├── apps/           # Individual app HTML files
│   └── db/v2.json      # App registry
├── scripts/            # 27 JS modules (wallet, widgets, kernel, etc.)
├── api/                # Serverless API endpoints
└── assets/             # Images, icons, wallpapers

💳 x402 Payment Protocol

The x402/ package implements HTTP 402 Payment Required as a real micropayment protocol using Solana USDC.

import { x402Paywall } from "@pump-fun/x402";

app.use("/api/premium", x402Paywall({
  recipient: "YourWalletAddress...",
  amountUsdc: 0.01, // $0.01 per request
}));

See x402/README.md for setup and examples.

🤖 DeFi Agents

The packages/defi-agents/ directory ships 43 production-ready AI agent definitions for DeFi, portfolio management, trading, and Web3 workflows.

• Universal format — works with any AI platform (Claude, GPT, LLaMA, local models)
• 18-language i18n — full locale translations
• RESTful API — agents served from a static JSON API
• Agent manifest — agents-manifest.json registry with metadata, categories, and counts
• Includes — pump-fun-sdk-expert agent specialized for this SDK

# Browse agents
cat packages/defi-agents/agents-manifest.json | jq '.totalAgents'
# 43

🏰 Lair Telegram Platform

lair-tg/ is a unified Telegram bot platform for DeFi intelligence, non-custodial wallet management, and token launching.

• 6 packages — api, bot, launch, mcp, os, shared
• 15+ data sources — CoinGecko, DexScreener, GeckoTerminal, Birdeye, and more
• AI assistant — GPT-4o with function calling for market analysis
• Token deployment — launch tokens via bonding curve from Telegram
• Alerts — meme tracker, whale monitoring, price alerts

See lair-tg/README.md for architecture and setup.

🔌 Plugin.delivery

The packages/plugin.delivery/ directory is an AI plugin index with a full SDK, gateway, and developer tools for building function-calling plugins.

• 17 API plugins — pump-fun-sdk, coingecko, dexscreener, defillama, beefy, lido, 1inch, thegraph, ens-lookup, gas-estimator, phishing-detector, sanctions-check, contract-scanner, audit-checker, grants-finder, address-labels, gateway
• Plugin SDK — TypeScript SDK with React hooks (usePluginSettings, usePluginState, useWatchPluginMessage)
• OpenAPI compatible — auto-generated client from OpenAPI specs
• Vercel edge deployment — serverless API functions

See packages/plugin.delivery/README.md for details.

🔑 Vanity Address Generators

Generate custom Solana addresses with a desired prefix or suffix — using the official solana-sdk (Rust) and @solana/web3.js (TypeScript).

# Rust generator
cd rust && cargo build --release
./target/release/pump-vanity --prefix pump --threads 8

# TypeScript generator
cd typescript && npm install && npm start -- --prefix pump

Both generators zeroize key material after use and write keypairs with 0600 permissions. See rust/README.md and typescript/README.md for full documentation.

🛠️ Shell Scripts & Makefile

Production shell scripts in scripts/ wrapping solana-keygen:

The Makefile provides 20+ targets for the full workflow:

make generate PREFIX=pump          # Generate a vanity address
make batch PREFIX=pump COUNT=10    # Batch generate
make verify FILE=keypair.json      # Verify a keypair
make test                          # Run all tests
make help                          # Show all targets

🧪 Testing & CI/CD

Test suites in tests/ covering unit, integration, stress, fuzz, and benchmark tests:

tests/
├── benchmarks/     # Performance comparison and scaling tests
├── cli/            # CLI generation and verification tests
├── integration/    # Output compatibility, security properties, keypair validity
├── stress/         # Rapid generation and long-running stability
├── fuzz/           # Fuzz testing for edge cases
└── fixtures/       # Shared test data

npm test                           # Run SDK unit tests (Jest)
make test                          # Run all test suites
bash docs/run-all-tests.sh         # Run comprehensive cross-language tests

CI/CD via 6 GitHub Actions workflows:

📚 Tutorials

19 hands-on guides in tutorials/ covering every SDK feature:

📖 Documentation

Also see: FAQ · Roadmap · Changelog

📂 Full Repository Structure

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 Additional Resources

MIT