pump-fun-sdk

<p align="center">    
  <h1 align="center">Pump SDK</h1> 
  <p align="center">
    TypeScript SDK for the Pump protocol on Solana — token creation, bonding curves, AMM pools, fee sharing, and volume rewards.
  </p>
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@nirholas/pump-sdk"><img src="https://img.shields.io/npm/v/@nirholas/pump-sdk.svg?style=flat-square&color=blue" alt="npm version" /></a>
  <a href="https://github.com/nirholas/pump-fun-sdk/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@nirholas/pump-sdk.svg?style=flat-square" alt="license" /></a>
  <a href="https://www.npmjs.com/package/@nirholas/pump-sdk"><img src="https://img.shields.io/npm/dm/@nirholas/pump-sdk.svg?style=flat-square" alt="downloads" /></a>
  <img src="https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square&logo=typescript" alt="TypeScript" />
  <img src="https://img.shields.io/badge/Solana-1.98+-purple?style=flat-square&logo=solana" alt="Solana" />
</p>

---

## What is Pump SDK?

Pump SDK is the community TypeScript SDK for the [Pump.fun](https://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

- [Quick Start](#-quick-start)
- [Usage Examples](#-usage-examples)
  - [Create a Token](#create-a-token)
  - [Create a Token With a `...pump` Vanity Mint](#create-a-token-with-a-pump-vanity-mint)
  - [Buy Tokens on the Bonding Curve](#buy-tokens-on-the-bonding-curve)
  - [Sell Tokens](#sell-tokens)
  - [Check Graduation Progress](#check-graduation-progress)
  - [Set Up Fee Sharing](#set-up-fee-sharing)
- [API Reference](#-api-reference)
- [On-Chain Programs](#-on-chain-programs)
- [Configuration](#-configuration)
- [Error Handling](#-error-handling)
- [FAQ](#-faq)
- [Architecture](#-architecture)
- [Contributing](#-contributing)
- [License](#-license)
- [Acknowledgments](#-acknowledgments)

---
## 🚀 Live Demos & Resources

- **[SDK Docs & Live Dashboards](https://sdk.pumpk.it)** (trades, launches, vanity: [sdk.pumpk.it/live](https://sdk.pumpk.it/live/))
- **[pump.fun UI Template](https://demo.pumpk.it)**
- **[DeFi Agents API](https://agents.pumpk.it)**
- **[PumpKit](https://github.com/nirholas/pumpkit)**
- **[PumpKit Site](https://pumpk.it)**
- **[Telegram PumpFun Github Claim Tracker Bot](https://t.me/pumpfunclaims)**
- **[Telegram PumpFun Graduation/Migration Tracker Bot](https://t.me/trackpumpfun)**
- **[Pumpfun Claim Tracker](https://t.me/pfclaimsbot)** (best bot — currently offline while building)

## 📈 Proof & Virality

**Proof the GitHub Claim Tracker bot is profitable to monitor**  
[→ View tweet](https://x.com/nichxbt/status/2033377591592444056)

**Went mega viral**  
[→ View tweet](https://x.com/RoundtableSpace/status/2027417189918064915)

> **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](https://x.com/nichxbt/status/2027304823712817503)

**The post that started it all**  
[→ View tweet](https://x.com/nichxbt/status/2027087471683698811)

# 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](https://pumpk.it)

---

## 🚀 Quick Start

### Installation

```bash
# 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):

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

### Minimal Example

```typescript
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, "%");
```

---

## 📖 Usage Examples

### Create a Token

```typescript
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.

```typescript
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/`](rust/). See
[Tutorial 13: Vanity Mints](tutorials/13-vanity-addresses.md) for the full
end-to-end flow and a runnable devnet example.

### Buy Tokens on the Bonding Curve

```typescript
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

```typescript
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

```typescript
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: ${pro