@nirholas/pump-sdk

v1.36.0

Published

16 days ago

TypeScript SDK for the Pump protocol on Solana: token creation, bonding curves, AMM pools, fee sharing, and volume rewards

0High
0Medium
0Low

nirholas

solana pump pumpfun bonding-curve token amm defi sdk typescript mcp cli pump-fun-cli command-line solana-cli terminal

What is Pump SDK?

Pump SDK is the community TypeScript SDK for the Pump.fun protocol on Solana. It provides offline-first instruction builders for every on-chain operation — token creation, bonding curve trading, AMM pool management, tiered fee configuration, creator fee sharing, volume-based token incentives, and social referral fees.

The SDK never sends transactions itself. It returns TransactionInstruction[] that you compose into transactions with your preferred signing and sending strategy.

📋 Table of Contents

🚀 Live Demos & Resources

Token Launchpad: launch and trade real Pump tokens from your browser, built entirely on this SDK
SDK Docs & Live Dashboards (trades, launches, vanity: sdk.pumpk.it/live)
pump.fun UI Template
DeFi Agents API
PumpKit
PumpKit Site
Telegram PumpFun Github Claim Tracker Bot
Telegram PumpFun Graduation/Migration Tracker Bot
Pumpfun Claim Tracker (best bot — currently offline while building)

📈 Proof & Virality

Proof the GitHub Claim Tracker bot is profitable to monitor
→ View tweet

Went mega viral
→ View tweet

just shipped a real-time PumpFun intelligence bot on Telegram
17 commands. zero cost. fully on-chain.
/price → instant token price & bonding curve
/monitor → live token launch feed
/cto → creator takeover alerts
/watch → wallet fee claim tracking
/quote → buy/sell estimates
/graduated → AMM graduation status
/alerts → customize your notifications
all powered by the open-source pump-fun-sdk

→ View original post

The post that started it all
→ View tweet

Looking for more? Check out PumpKit 💊💚

Open-source framework for building PumpFun Telegram bots on Solana. Claim monitors, channel feeds, group trackers, whale alerts — build your own or use ours.
PumpKit Web App + Documentation

🚀 Quick Start

Installation

# npm
npm install @nirholas/pump-sdk

# yarn
yarn add @nirholas/pump-sdk

# pnpm
pnpm add @nirholas/pump-sdk

Peer Dependencies

The SDK requires these Solana packages (install them if not already present):

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

Minimal Example

import { Connection, PublicKey } from "@solana/web3.js";
import { OnlinePumpSdk } from "@nirholas/pump-sdk";

// 1. Create an online SDK instance
const connection = new Connection("https://api.mainnet-beta.solana.com");
const sdk = new OnlinePumpSdk(connection);

// 2. Fetch current token state
const mint = new PublicKey("YourTokenMintAddress...");
const summary = await sdk.fetchBondingCurveSummary(mint);

console.log("Market Cap:", summary.marketCap.toString(), "lamports");
console.log("Graduated:", summary.isGraduated);
console.log("Progress:", summary.progressBps / 100, "%");

💻 The `pump` CLI

The SDK ships with a binary. No wallet, no API key, and no configuration are needed for anything that reads the chain.

npm install -g @nirholas/pump-sdk

pump curve <mint>                  # price, market cap, graduation meter, fee tier
pump quote buy <mint> --sol 1      # what 1 SOL really buys, after fees and impact
pump watch <mint>                  # live dashboard
pump doctor                        # check your RPC, wallet, and balance in one shot

Or without installing anything: npx -p @nirholas/pump-sdk pump curve <mint>.

FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump live on the bonding curve
────────────────────────────────────────────────────────────

  Market cap   93.705347 SOL
  Buy price    0.000000096 SOL per token
  Sell price   0.000000091 SOL per token
  Trading fee  1.25% 0.95% protocol + 0.3% creator

  Graduation  ███████████████░░░░░░░░░ 61.39%

  SOL to graduate   60.684661 SOL
  SOL in curve      24.921536 SOL
  Tokens left       306.21M of 793.1M

| Command | What it does | |---|---| | pump curve / price / pool / global | Read curve, price, AMM pool, and protocol state | | pump quote buy\|sell | Price a trade offline: output, fees, effective price, impact | | pump buy / sell | Trade, auto-routing between the bonding curve and PumpAMM | | pump create | Launch a token, optionally with an atomic first buy | | pump vanity | Grind a ...pump mint address | | pump fees / incentives | Check and claim creator fees and volume rewards | | pump watch | Live-refreshing dashboard, or a JSON price feed | | pump events | Decode the Pump events in any transaction | | pump pda | Derive any Pump program address | | pump doctor / config | Diagnose and configure |

Safe by construction. Reads never load a keypair. Every trade is simulated before anything is sent, prints exactly what is about to happen, and waits for an explicit yes. --simulate sends nothing; --yes is the scripting escape hatch; a piped command with neither refuses rather than spending funds unattended.

Scriptable. Every command takes --json and writes nothing else to stdout in that mode:

pump curve <mint> --json | jq .marketCapSol
pump watch <mint> --json --interval 10 | jq -r '"\(.at)  \(.marketCapSol) SOL"'
pump events <sig> --json | jq '.events[] | select(.type=="trade")'

Full reference: docs/cli.md. Ten-minute walkthrough: tutorial 45.

🧪 50 Runnable Examples

The repo ships fifty tested, runnable examples covering the entire SDK surface. Each one runs with a single command, exports its logic for offline testing, and has a matching step-by-step tutorial.

git clone https://github.com/nirholas/pump-fun-sdk && cd pump-fun-sdk && npm install
npm run example        # list all 50
npm run example 11     # offline buy quotes
npm run test:examples  # run every example's test suite offline

| Range | Category | |-------|----------| | 01-10 | Token Lifecycle: create, buy, sell, mayhem mode, cashback | | 11-20 | Curve Math & Fees: offline quotes, tiers, price impact | | 21-30 | Accounts & Events: every PDA, every decoder | | 31-40 | Live Data: mainnet reads, batching, WebSocket feeds | | 41-50 | AMM & Advanced: pools, liquidity, fee sharing, incentives, vanity mints |

Full catalog: docs/examples.md · Browse: examples/ · Tutorials: tutorials/examples/

📖 Usage Examples

Create a Token

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

const mintKeypair = Keypair.generate();
const creator = wallet.publicKey;

const createIx = await PUMP_SDK.createV2Instruction({
  mint: mintKeypair.publicKey,
  name: "My Token",
  symbol: "MYTKN",
  uri: "https://arweave.net/metadata.json",
  creator,
  user: creator,
  mayhemMode: false,
});

// createIx is a TransactionInstruction — add to a Transaction and send

Warning: Do NOT use createInstruction — it is deprecated (v1). Always use createV2Instruction.

Create a Token With a `...pump` Vanity Mint

Mint addresses ending in pump (like the ones on pump.fun) are produced by grinding keypairs off-chain. The SDK exposes this as a first-class helper — swap Keypair.generate() for generateVanityMint() and the rest of the flow is unchanged.

import { generateVanityMint, PUMP_SDK } from "@nirholas/pump-sdk";

// Grind until we find a mint whose address ends in "pump" (~11M attempts, ~1–4 min in Node)
const { keypair: mintKeypair } = await generateVanityMint({ suffix: "pump" });

const createIx = await PUMP_SDK.createV2Instruction({
  mint: mintKeypair.publicKey,  // ← ends in "pump"
  name: "My Token",
  symbol: "MYTKN",
  uri: "https://arweave.net/metadata.json",
  creator: wallet.publicKey,
  user: wallet.publicKey,
  mayhemMode: false,
});

// Sign the transaction with BOTH the payer and the mint keypair.
// tx.sign([wallet, mintKeypair]);

Supports prefix, suffix, caseInsensitive, maxAttempts, onProgress, and AbortSignal. For patterns longer than 4 characters, use the multi-threaded Rust generator at rust/. See Tutorial 13: Vanity Mints for the full end-to-end flow and a runnable devnet example.

Buy Tokens on the Bonding Curve

import { Connection, PublicKey } from "@solana/web3.js";
import BN from "bn.js";
import { getBuyTokenAmountFromSolAmount, OnlinePumpSdk } from "@nirholas/pump-sdk";

const connection = new Connection("https://api.mainnet-beta.solana.com");
const sdk = new OnlinePumpSdk(connection);

const mint = new PublicKey("TokenMintAddress...");
const user = wallet.publicKey;

// Fetch all required state in parallel — buyState includes tokenProgram (auto-detected)
const [buyState, global, feeConfig] = await Promise.all([
  sdk.fetchBuyState(mint, user),
  sdk.fetchGlobal(),
  sdk.fetchFeeConfig(),
]);

assert(!buyState.bondingCurve.complete, "Token has already graduated to AMM");

// Calculate expected tokens for 0.1 SOL
const solAmount = new BN(100_000_000); // 0.1 SOL in lamports
const expectedTokens = getBuyTokenAmountFromSolAmount({
  global,
  feeConfig,
  mintSupply: buyState.bondingCurve.tokenTotalSupply,
  bondingCurve: buyState.bondingCurve,
  amount: solAmount,
});

// buyState spreads: bondingCurveAccountInfo, bondingCurve, associatedUserAccountInfo, tokenProgram
const buyIxs = await sdk.buyInstructions({
  ...buyState,
  mint,
  user,
  amount: expectedTokens,
  solAmount,
  slippage: 0.05,         // 5% slippage tolerance
});
// buyIxs is TransactionInstruction[] — compose into a VersionedTransaction and send

Note: fetchBuyState auto-detects whether the token uses SPL Token or Token-2022 and returns tokenProgram accordingly. Always spread ...buyState into buyInstructions to ensure the correct program is used.

Sell Tokens

import BN from "bn.js";
import { getSellSolAmountFromTokenAmount, OnlinePumpSdk } from "@nirholas/pump-sdk";

const sdk = new OnlinePumpSdk(connection);

// Fetch required state in parallel
// Pass buyState.tokenProgram if you have it to avoid a second mint account fetch
const [sellState, global, feeConfig] = await Promise.all([
  sdk.fetchSellState(mint, user),
  sdk.fetchGlobal(),
  sdk.fetchFeeConfig(),
]);

const tokenAmount = new BN(1_000_000_000); // amount in raw units (6 decimals)
const expectedSol = getSellSolAmountFromTokenAmount({
  global,
  feeConfig,
  mintSupply: sellState.bondingCurve.tokenTotalSupply,
  bondingCurve: sellState.bondingCurve,
  amount: tokenAmount,
});

// sellState spreads: bondingCurveAccountInfo, bondingCurve, tokenProgram
const sellIxs = await sdk.sellInstructions({
  ...sellState,
  mint,
  user,
  amount: tokenAmount,
  solAmount: expectedSol,
  slippage: 0.05,
});

Note: fetchSellState returns tokenProgram (auto-detected from the mint). Always spread ...sellState into sellInstructions.

Check Graduation Progress

import { OnlinePumpSdk } from "@nirholas/pump-sdk";

const sdk = new OnlinePumpSdk(connection);
const progress = await sdk.fetchGraduationProgress(mint);

console.log(`Progress: ${progress.progressBps / 100}%`);
console.log(`Graduated: ${progress.isGraduated}`);
console.log(`Tokens remaining: ${progress.tokensRemaining.toString()}`);
console.log(`SOL accumulated: ${progress.solAccumulated.toString()}`);

Set Up Fee Sharing

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

// Create a fee sharing config (creator only, before or after graduation)
const createConfigIx = await PUMP_SDK.createFeeSharingConfig({
  creator: wallet.publicKey,
  mint: tokenMint,
  pool: null,  // null for pre-graduation tokens
});

// Update shareholders (must total exactly 10,000 BPS = 100%)
const updateIx = await PUMP_SDK.updateFeeShares({
  authority: wallet.publicKey,
  mint: tokenMint,
  currentShareholders: [wallet.publicKey],
  newShareholders: [
    { address: wallet.publicKey, shareBps: 7000 },         // 70%
    { address: new PublicKey("Partner..."), shareBps: 3000 }, // 30%
  ],
});

Warning: Shares must total exactly 10,000 BPS. The SDK throws InvalidShareTotalError otherwise. Maximum 10 shareholders.

📚 API Reference

See docs/api-reference.md for the complete API documentation with full TypeScript signatures, parameters, and examples.

Core Classes

| Class | Description | |-------|-------------| | PumpSdk | Offline instruction builder — no RPC connection required | | OnlinePumpSdk | Extends PumpSdk with RPC fetchers for account state | | PUMP_SDK | Pre-instantiated singleton of PumpSdk |

Bonding Curve Functions

| Function | Returns | Description | |----------|---------|-------------| | getBuyTokenAmountFromSolAmount(...) | BN | Tokens received for a given SOL amount | | getBuySolAmountFromTokenAmount(...) | BN | SOL cost for a given token amount | | getSellSolAmountFromTokenAmount(...) | BN | SOL received for selling tokens | | bondingCurveMarketCap(...) | BN | Current market cap in lamports | | newBondingCurve(global) | BondingCurve | Fresh bonding curve from global config |

Analytics Functions

| Function | Returns | Description | |----------|---------|-------------| | calculateBuyPriceImpact(...) | PriceImpactResult | Price impact for a buy trade | | calculateSellPriceImpact(...) | PriceImpactResult | Price impact for a sell trade | | getGraduationProgress(...) | GraduationProgress | Bonding curve completion percentage | | getTokenPrice(...) | TokenPriceInfo | Current buy/sell price per token | | getBondingCurveSummary(...) | BondingCurveSummary | Complete bonding curve overview |

Fee Functions

| Function | Returns | Description | |----------|---------|-------------| | getFee(...) | BN | Fee amount for a trade | | computeFeesBps(...) | CalculatedFeesBps | Current fee basis points (protocol + creator) | | calculateFeeTier(...) | Fees | Fee tier for a given market cap |

Token Incentive Functions

| Function | Returns | Description | |----------|---------|-------------| | totalUnclaimedTokens(...) | BN | Unclaimed $PUMP reward tokens | | currentDayTokens(...) | BN | Tokens earned today |

🔗 On-Chain Programs

| Program | ID | Purpose | |---------|----|---------| | Pump | 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P | Bonding curve creation, buying, selling, migration | | PumpAMM | pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA | Graduated AMM pools — trading, liquidity, fees | | PumpFees | pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ | Fee sharing config and social fee PDAs |

🔧 Configuration

Constructor

The SDK has no required environment variables. You configure it via the constructor:

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | connection | Connection | Only for OnlinePumpSdk | Solana RPC connection |

Key Constants

| Constant | Value | Description | |----------|-------|-------------| | PUMP_PROGRAM_ID | 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P | Main Pump program | | PUMP_AMM_PROGRAM_ID | pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA | AMM program | | PUMP_FEE_PROGRAM_ID | pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ | Fee program | | PUMP_TOKEN_MINT | pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn | $PUMP token mint | | MAX_SHAREHOLDERS | 10 | Maximum shareholders in fee sharing | | ONE_BILLION_SUPPLY | 1000000000000000 | 1B tokens with 6 decimals | | BONDING_CURVE_NEW_SIZE | 151 | Bonding curve account size in bytes |

⚠️ Error Handling

The SDK defines typed errors for fee sharing validation:

| Error | Cause | Fix | |-------|-------|-----| | NoShareholdersError | Empty shareholders array | Provide at least 1 shareholder | | TooManyShareholdersError | More than 10 shareholders | Reduce to ≤ 10 shareholders | | ZeroShareError | A shareholder has 0 or negative BPS | Set all shares to positive values | | InvalidShareTotalError | Shares don't sum to 10,000 BPS | Ensure shares total exactly 10,000 | | DuplicateShareholderError | Same address appears twice | Remove duplicate addresses | | ShareCalculationOverflowError | BPS sum exceeds safe integer range | Check share values | | PoolRequiredForGraduatedError | pool is null for a graduated coin | Pass the pool address from fetchPool() |

Common Pitfalls

Warning: Never use JavaScript number for token or lamport amounts. Always use BN from bn.js. JavaScript numbers lose precision above 2^53.

Warning: Check bondingCurve.complete before trading. If true, the token has graduated to AMM — use ammBuyInstruction/ammSellInstruction instead.

Warning: createInstruction is deprecated. Use createV2Instruction for all new token creation.

❓ FAQ

Q: Do I need an RPC connection to use the SDK? No. PumpSdk (and the PUMP_SDK singleton) builds instructions offline. Only use OnlinePumpSdk when you need to fetch on-chain state.

Q: How do I know if a token has graduated to AMM? Check bondingCurve.complete === true or use sdk.isGraduated(mint). Graduated tokens trade on PumpAMM, not the bonding curve.

Q: What is slippage in buy/sell instructions? A decimal fraction (e.g., 0.05 = 5%). The SDK adjusts maxSolCost (buy) or minSolOutput (sell) to protect against price movement.

Q: Why do amounts use BN instead of number? Solana token amounts (lamports, token units) regularly exceed JavaScript's safe integer limit (2^53). BN provides arbitrary-precision arithmetic.

Q: What's the difference between Pump and PumpAMM programs? Pump handles the bonding curve phase (creation → graduation). PumpAMM handles post-graduation trading with constant-product AMM pools.

Q: How does fee sharing work? Token creators can split their creator fees among up to 10 shareholders. Each shareholder gets a share in basis points (1/10,000). The total must equal exactly 10,000 BPS (100%).

Q: What is Mayhem Mode? A special token creation mode with randomized bonding curve parameters. Tokens created with mayhemMode: true have unpredictable pricing dynamics.

Q: Can I use the SDK in the browser? Yes. The SDK has no Node.js-specific dependencies. The ESM build works in modern browsers with a bundler.

🏗️ Architecture

See docs/architecture.md for detailed system design, data flow diagrams, and module explanations.

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for:

Development setup
Branch naming and commit conventions
Testing requirements
PR process

📄 License

🙏 Acknowledgments

Pump.fun — The protocol this SDK interfaces with
Solana Labs — Blockchain infrastructure and @solana/web3.js
Coral (Anchor) — IDL-based program interaction via @coral-xyz/anchor
bn.js — Arbitrary-precision arithmetic for financial math
@pump-fun/pump-swap-sdk — AMM swap integration

Documentation

Full documentation site: https://nirholas.github.io/pump-fun-sdk/

Getting started covers install and first run.
Examples has copy-paste snippets.