|
| 1 | +# SDK Integration Guide |
| 2 | + |
| 3 | +> How PumpKit integrates with `@nirholas/pump-sdk` for on-chain Solana operations. |
| 4 | +
|
| 5 | +## Overview |
| 6 | + |
| 7 | +PumpKit wraps the [pump-fun-sdk](https://github.com/nirholas/pump-fun-sdk) to provide bot-friendly async functions for querying bonding curves, token prices, graduation progress, and buy/sell quotes. |
| 8 | + |
| 9 | +The bridge lives in `@pumpkit/core` and is exported from the barrel: |
| 10 | + |
| 11 | +```typescript |
| 12 | +import { |
| 13 | + getTokenPrice, |
| 14 | + getGraduationProgress, |
| 15 | + getBuyQuote, |
| 16 | + getSellQuote, |
| 17 | + getBondingCurveState, |
| 18 | +} from '@pumpkit/core'; |
| 19 | +``` |
| 20 | + |
| 21 | +## Setup |
| 22 | + |
| 23 | +Install `@nirholas/pump-sdk` as a peer dependency of your bot: |
| 24 | + |
| 25 | +```bash |
| 26 | +npm install @nirholas/pump-sdk @solana/web3.js bn.js |
| 27 | +``` |
| 28 | + |
| 29 | +## Functions |
| 30 | + |
| 31 | +### `getTokenPrice(connection, mint)` |
| 32 | + |
| 33 | +Returns the current buy/sell price per token and market cap. |
| 34 | + |
| 35 | +```typescript |
| 36 | +import { Connection, PublicKey } from '@solana/web3.js'; |
| 37 | +import { getTokenPrice } from '@pumpkit/core'; |
| 38 | + |
| 39 | +const connection = new Connection('https://api.mainnet-beta.solana.com'); |
| 40 | +const mint = new PublicKey('YourTokenMintAddress...'); |
| 41 | + |
| 42 | +const price = await getTokenPrice(connection, mint); |
| 43 | +if (price) { |
| 44 | + console.log('Buy price:', price.buyPricePerToken.toString()); |
| 45 | + console.log('Market cap:', price.marketCap.toString()); |
| 46 | + console.log('Graduated:', price.isGraduated); |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +**Returns:** `TokenPriceInfo | null` — `null` if the bonding curve doesn't exist. |
| 51 | + |
| 52 | +### `getGraduationProgress(connection, mint)` |
| 53 | + |
| 54 | +Returns how close a token is to graduating from bonding curve to AMM. |
| 55 | + |
| 56 | +```typescript |
| 57 | +import { getGraduationProgress } from '@pumpkit/core'; |
| 58 | + |
| 59 | +const progress = await getGraduationProgress(connection, mint); |
| 60 | +if (progress) { |
| 61 | + console.log(`${progress.progressBps / 100}% graduated`); |
| 62 | + console.log('Tokens remaining:', progress.tokensRemaining.toString()); |
| 63 | + console.log('SOL accumulated:', progress.solAccumulated.toString()); |
| 64 | +} |
| 65 | +``` |
| 66 | + |
| 67 | +**Returns:** `GraduationProgress | null` |
| 68 | + |
| 69 | +### `getBuyQuote(connection, mint, solAmount)` |
| 70 | + |
| 71 | +Calculates how many tokens you'd receive for a given SOL amount. |
| 72 | + |
| 73 | +```typescript |
| 74 | +import BN from 'bn.js'; |
| 75 | +import { getBuyQuote } from '@pumpkit/core'; |
| 76 | + |
| 77 | +const solAmount = new BN(1_000_000_000); // 1 SOL in lamports |
| 78 | +const quote = await getBuyQuote(connection, mint, solAmount); |
| 79 | +if (quote) { |
| 80 | + console.log('Tokens received:', quote.tokens.toString()); |
| 81 | + console.log('Price impact:', quote.priceImpact, '%'); |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +**Returns:** `{ tokens: BN, priceImpact: number } | null` |
| 86 | + |
| 87 | +### `getSellQuote(connection, mint, tokenAmount)` |
| 88 | + |
| 89 | +Calculates how much SOL you'd receive for selling a given token amount. |
| 90 | + |
| 91 | +```typescript |
| 92 | +import { getSellQuote } from '@pumpkit/core'; |
| 93 | + |
| 94 | +const tokenAmount = new BN('1000000000'); // token amount |
| 95 | +const quote = await getSellQuote(connection, mint, tokenAmount); |
| 96 | +if (quote) { |
| 97 | + console.log('SOL received:', quote.sol.toString(), 'lamports'); |
| 98 | + console.log('Price impact:', quote.priceImpact, '%'); |
| 99 | +} |
| 100 | +``` |
| 101 | + |
| 102 | +**Returns:** `{ sol: BN, priceImpact: number } | null` |
| 103 | + |
| 104 | +### `getBondingCurveState(connection, mint)` |
| 105 | + |
| 106 | +Fetches the raw bonding curve account state. |
| 107 | + |
| 108 | +```typescript |
| 109 | +import { getBondingCurveState } from '@pumpkit/core'; |
| 110 | + |
| 111 | +const state = await getBondingCurveState(connection, mint); |
| 112 | +if (state) { |
| 113 | + console.log('Complete:', state.complete); |
| 114 | + console.log('Creator:', state.creator); |
| 115 | + console.log('Virtual SOL reserves:', state.virtualSolReserves); |
| 116 | + console.log('Mayhem mode:', state.isMayhemMode); |
| 117 | +} |
| 118 | +``` |
| 119 | + |
| 120 | +**Returns:** `BondingCurveInfo | null` |
| 121 | + |
| 122 | +## Error Handling |
| 123 | + |
| 124 | +All bridge functions return `null` when the bonding curve account doesn't exist (e.g., token hasn't been created yet, or account was closed). Network errors are caught internally and also return `null`. |
| 125 | + |
| 126 | +```typescript |
| 127 | +const price = await getTokenPrice(connection, mint); |
| 128 | +if (!price) { |
| 129 | + console.log('Token not found or RPC error'); |
| 130 | + return; |
| 131 | +} |
| 132 | +``` |
| 133 | + |
| 134 | +## Architecture |
| 135 | + |
| 136 | +``` |
| 137 | +Your Bot |
| 138 | + ↓ |
| 139 | +@pumpkit/core (sdk-bridge.ts) |
| 140 | + ↓ |
| 141 | +@nirholas/pump-sdk (OnlinePumpSdk, analytics, bondingCurve) |
| 142 | + ↓ |
| 143 | +Solana RPC (getAccountInfo, etc.) |
| 144 | +``` |
| 145 | + |
| 146 | +The bridge uses `OnlinePumpSdk` internally to fetch Global, FeeConfig, and BondingCurve state, then passes them to the SDK's pure math functions (`getTokenPrice`, `getBuyTokenAmountFromSolAmount`, etc.). |
| 147 | + |
| 148 | +## When to Use the Bridge vs. SDK Directly |
| 149 | + |
| 150 | +| Scenario | Use | |
| 151 | +|----------|-----| |
| 152 | +| Quick price check in a bot command | Bridge (`getTokenPrice`) | |
| 153 | +| Building transaction instructions | SDK directly (`PUMP_SDK.buyInstructions()`) | |
| 154 | +| Batch queries for many tokens | SDK directly (manual batching with `getMultipleAccountsInfo`) | |
| 155 | +| One-off graduation check | Bridge (`getGraduationProgress`) | |
| 156 | +| Complex trading logic | SDK directly for full control | |
| 157 | + |
| 158 | +The bridge is for convenience. For advanced use cases, import from `@nirholas/pump-sdk` directly. |
0 commit comments