pumpfun-python 0.1.0__tar.gz

pumpfun_python-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,16 @@
+---
+name: Bug report
+about: Report a bug
+labels: bug
+---
+
+**Describe the bug**
+
+**To Reproduce**
+
+**Expected behavior**
+
+**Environment**
+- Python version:
+- pumpfun-python version:
+- solders version:

pumpfun_python-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,9 @@
+---
+name: Feature request
+about: Suggest a feature
+labels: enhancement
+---
+
+**Describe the feature**
+
+**Use case**

pumpfun_python-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,5 @@
+## What
+
+## Why
+
+## Testing

pumpfun_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -v
+      - run: ruff check .
+
+  type-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: mypy pumpfun/

pumpfun_python-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+htmlcov/
+.coverage
+.mypy_cache/
+.ruff_cache/

pumpfun_python-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0 (2025-07-10)
+
+### Added
+- PumpFun bonding curve v2 buy/sell instruction builders (16/14 accounts)
+- PumpSwap AMM constant-product swap instruction builder (13 accounts)
+- On-chain bonding curve state reader with full field parsing
+- PumpSwap pool state reader (legacy + Pump AMM layouts)
+- Price calculation helpers — `calculate_buy_amount`, `calculate_sell_amount`, `calculate_swap_output`
+- PDA derivation — bonding curve, creator vault, volume accumulators, fee config, ATA
+- All program IDs and discriminators for PumpFun, PumpSwap, and Pump AMM
+- Full type hints with py.typed marker

pumpfun_python-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing to pumpfun-python
+
+## Development Setup
+
+```bash
+git clone https://github.com/JinUltimate1995/pumpfun-python.git
+cd pumpfun-python
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+## Code Quality
+
+```bash
+ruff check .
+mypy pumpfun/
+```
+
+## Pull Requests
+
+1. Fork the repo
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a PR

pumpfun_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JinUltimate1995
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pumpfun_python-0.1.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: pumpfun-python
+Version: 0.1.0
+Summary: Buy and sell on PumpFun bonding curves + PumpSwap AMM. Directly from Python.
+Project-URL: Homepage, https://github.com/JinUltimate1995/pumpfun-python
+Project-URL: Repository, https://github.com/JinUltimate1995/pumpfun-python
+Project-URL: Issues, https://github.com/JinUltimate1995/pumpfun-python/issues
+Author: JinUltimate1995
+License-Expression: MIT
+License-File: LICENSE
+Keywords: amm,async,bonding-curve,crypto,defi,dex,pumpfun,pumpswap,python,solana,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: solders>=0.21
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pumpfun-python
+
+**Buy and sell on PumpFun bonding curves + PumpSwap AMM. Directly from Python. No Jupiter needed.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Typed](https://img.shields.io/badge/typed-py.typed-blue.svg)](https://peps.python.org/pep-0561/)
+
+---
+
+## Why?
+
+PumpFun tokens start on a **bonding curve** and graduate to a **PumpSwap AMM pool**. Jupiter doesn't always route through these — and when it does, you're at the mercy of their routing engine. This library builds the raw Solana instructions so you can swap directly.
+
+- **Pre-graduation** — buy/sell against the PumpFun bonding curve (v2, 16/14 accounts)
+- **Post-graduation** — swap on PumpSwap AMM pools (constant-product, 13 accounts)
+- **Zero dependencies beyond solders + httpx** — no SDK bloat
+- **Production-tested** — extracted from a live trading system
+
+---
+
+## Install
+
+```bash
+pip install pumpfun-python
+```
+
+Or from source:
+
+```bash
+pip install git+https://github.com/JinUltimate1995/pumpfun-python.git
+```
+
+---
+
+## Quick Start
+
+### 💰 Calculate buy/sell amounts (no RPC needed)
+
+```python
+from pumpfun import calculate_buy_amount, calculate_sell_amount
+
+# How many tokens for 0.1 SOL?
+tokens = calculate_buy_amount(
+    sol_amount_lamports=100_000_000,  # 0.1 SOL
+    virtual_sol_reserves=30_000_000_000,
+    virtual_token_reserves=1_000_000_000_000,
+)
+print(f"Tokens received: {tokens:,}")
+
+# How much SOL for selling 1M tokens?
+sol_out = calculate_sell_amount(
+    token_amount=1_000_000,
+    virtual_sol_reserves=30_000_000_000,
+    virtual_token_reserves=1_000_000_000_000,
+)
+print(f"SOL received: {sol_out / 1e9:.6f}")
+```
+
+### 📈 Read bonding curve state
+
+> **RPC calls require your own Solana RPC endpoint.** Get a free key from [Helius](https://helius.dev), [QuickNode](https://quicknode.com), or use the public endpoint (rate-limited).
+
+```python
+import asyncio
+from pumpfun import fetch_bonding_curve_state
+
+async def main():
+    state = await fetch_bonding_curve_state(
+        rpc_url="https://api.mainnet-beta.solana.com",
+        token_mint="YourTokenMintAddress",
+    )
+    print(f"Reserves: {state.virtual_sol_reserves} SOL, {state.virtual_token_reserves} tokens")
+    print(f"Complete (graduated): {state.complete}")
+    print(f"Creator: {state.creator}")
+
+asyncio.run(main())
+```
+
+### 🔨 Build a buy instruction
+
+```python
+from solders.pubkey import Pubkey
+from pumpfun import build_buy_instruction, get_bonding_curve_pda
+
+user = Pubkey.from_string("YourWalletAddress")
+token_mint = Pubkey.from_string("TokenMintAddress")
+bonding_curve = get_bonding_curve_pda(token_mint)
+
+ix = build_buy_instruction(
+    user=user,
+    token_mint=token_mint,
+    bonding_curve=bonding_curve,
+    sol_amount_lamports=100_000_000,  # 0.1 SOL max
+    min_tokens_out=950_000,           # slippage protection
+    creator=Pubkey.from_string("CreatorAddress"),
+    fee_recipient=Pubkey.from_string("62qc2CNXwrYqQScmEdiZFFAnJR262PxWEuNQtxfafNgV"),
+)
+# Add `ix` to your transaction
+```
+
+### 🏊 PumpSwap AMM swap
+
+```python
+from pumpfun import calculate_swap_output, build_swap_instruction, fetch_pool_state
+
+# Read pool state
+pool = await fetch_pool_state(rpc_url, "PoolAddress")
+
+# Calculate output
+amount_out, fee = calculate_swap_output(
+    amount_in=100_000_000,  # 0.1 SOL
+    reserve_in=5_000_000_000,
+    reserve_out=1_000_000_000_000,
+    lp_fee_bps=pool.lp_fee_basis_points,
+    protocol_fee_bps=pool.protocol_fee_basis_points,
+)
+```
+
+---
+
+## API Reference
+
+### Bonding Curve (pre-graduation)
+
+| Function | Description |
+|---|---|
+| `calculate_buy_amount()` | Tokens received for SOL input (1% fee) |
+| `calculate_sell_amount()` | SOL received for token input (1% fee) |
+| `build_buy_instruction()` | Build PumpFun v2 BUY ix (16 accounts) |
+| `build_sell_instruction()` | Build PumpFun v2 SELL ix (14 accounts) |
+| `fetch_bonding_curve_state()` | Read reserves, creator, completion from chain |
+| `fetch_fee_recipient()` | Read fee recipient from Global account |
+
+### PumpSwap AMM (post-graduation)
+
+| Function | Description |
+|---|---|
+| `calculate_swap_output()` | Output amount for constant-product swap |
+| `build_swap_instruction()` | Build PumpSwap swap ix (13 accounts) |
+| `fetch_pool_state()` | Read pool vaults, mints, fees from chain |
+
+### PDA Helpers
+
+| Function | Description |
+|---|---|
+| `get_bonding_curve_pda()` | Derive bonding curve PDA for a mint |
+| `get_associated_token_address()` | Derive ATA (SPL Token or Token-2022) |
+
+### Constants
+
+All program IDs are exported: `PUMP_FUN_PROGRAM`, `PUMP_SWAP_PROGRAM`, `PUMP_AMM_PROGRAM`, plus system programs, discriminators, and fee accounts.
+
+---
+
+## Account Layout Notes
+
+**BUY instruction** uses 16 accounts + 1 remaining account (bonding-curve-v2 PDA).
+
+**SELL instruction** uses 14 accounts + 1 remaining — but **creator_vault [8] and token_program [9] are SWAPPED** relative to buy. This is an undocumented PumpFun quirk that causes failed transactions if you copy the buy layout.
+
+**Pump AMM pools** (pAMMBay program) can have **reversed base/quote** — base_mint=SOL, quote_mint=TOKEN. The `PoolState.base_is_sol` flag indicates this.
+
+---
+
+## Also by JinUltimate1995
+
+- **[jupiter-swap-python](https://github.com/JinUltimate1995/jupiter-swap-python)** — Jupiter swap client for Python. Async. Typed.
+- **[solana-rpc-resilient](https://github.com/JinUltimate1995/solana-rpc-resilient)** — Fault-tolerant Solana RPC with automatic failover.
+- **[dexscreener-python](https://github.com/JinUltimate1995/dexscreener-python)** — DexScreener API client for Python.
+
+---
+
+## License
+
+MIT

pumpfun_python-0.1.0/README.md

@@ -0,0 +1,176 @@
+# pumpfun-python
+
+**Buy and sell on PumpFun bonding curves + PumpSwap AMM. Directly from Python. No Jupiter needed.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Typed](https://img.shields.io/badge/typed-py.typed-blue.svg)](https://peps.python.org/pep-0561/)
+
+---
+
+## Why?
+
+PumpFun tokens start on a **bonding curve** and graduate to a **PumpSwap AMM pool**. Jupiter doesn't always route through these — and when it does, you're at the mercy of their routing engine. This library builds the raw Solana instructions so you can swap directly.
+
+- **Pre-graduation** — buy/sell against the PumpFun bonding curve (v2, 16/14 accounts)
+- **Post-graduation** — swap on PumpSwap AMM pools (constant-product, 13 accounts)
+- **Zero dependencies beyond solders + httpx** — no SDK bloat
+- **Production-tested** — extracted from a live trading system
+
+---
+
+## Install
+
+```bash
+pip install pumpfun-python
+```
+
+Or from source:
+
+```bash
+pip install git+https://github.com/JinUltimate1995/pumpfun-python.git
+```
+
+---
+
+## Quick Start
+
+### 💰 Calculate buy/sell amounts (no RPC needed)
+
+```python
+from pumpfun import calculate_buy_amount, calculate_sell_amount
+
+# How many tokens for 0.1 SOL?
+tokens = calculate_buy_amount(
+    sol_amount_lamports=100_000_000,  # 0.1 SOL
+    virtual_sol_reserves=30_000_000_000,
+    virtual_token_reserves=1_000_000_000_000,
+)
+print(f"Tokens received: {tokens:,}")
+
+# How much SOL for selling 1M tokens?
+sol_out = calculate_sell_amount(
+    token_amount=1_000_000,
+    virtual_sol_reserves=30_000_000_000,
+    virtual_token_reserves=1_000_000_000_000,
+)
+print(f"SOL received: {sol_out / 1e9:.6f}")
+```
+
+### 📈 Read bonding curve state
+
+> **RPC calls require your own Solana RPC endpoint.** Get a free key from [Helius](https://helius.dev), [QuickNode](https://quicknode.com), or use the public endpoint (rate-limited).
+
+```python
+import asyncio
+from pumpfun import fetch_bonding_curve_state
+
+async def main():
+    state = await fetch_bonding_curve_state(
+        rpc_url="https://api.mainnet-beta.solana.com",
+        token_mint="YourTokenMintAddress",
+    )
+    print(f"Reserves: {state.virtual_sol_reserves} SOL, {state.virtual_token_reserves} tokens")
+    print(f"Complete (graduated): {state.complete}")
+    print(f"Creator: {state.creator}")
+
+asyncio.run(main())
+```
+
+### 🔨 Build a buy instruction
+
+```python
+from solders.pubkey import Pubkey
+from pumpfun import build_buy_instruction, get_bonding_curve_pda
+
+user = Pubkey.from_string("YourWalletAddress")
+token_mint = Pubkey.from_string("TokenMintAddress")
+bonding_curve = get_bonding_curve_pda(token_mint)
+
+ix = build_buy_instruction(
+    user=user,
+    token_mint=token_mint,
+    bonding_curve=bonding_curve,
+    sol_amount_lamports=100_000_000,  # 0.1 SOL max
+    min_tokens_out=950_000,           # slippage protection
+    creator=Pubkey.from_string("CreatorAddress"),
+    fee_recipient=Pubkey.from_string("62qc2CNXwrYqQScmEdiZFFAnJR262PxWEuNQtxfafNgV"),
+)
+# Add `ix` to your transaction
+```
+
+### 🏊 PumpSwap AMM swap
+
+```python
+from pumpfun import calculate_swap_output, build_swap_instruction, fetch_pool_state
+
+# Read pool state
+pool = await fetch_pool_state(rpc_url, "PoolAddress")
+
+# Calculate output
+amount_out, fee = calculate_swap_output(
+    amount_in=100_000_000,  # 0.1 SOL
+    reserve_in=5_000_000_000,
+    reserve_out=1_000_000_000_000,
+    lp_fee_bps=pool.lp_fee_basis_points,
+    protocol_fee_bps=pool.protocol_fee_basis_points,
+)
+```
+
+---
+
+## API Reference
+
+### Bonding Curve (pre-graduation)
+
+| Function | Description |
+|---|---|
+| `calculate_buy_amount()` | Tokens received for SOL input (1% fee) |
+| `calculate_sell_amount()` | SOL received for token input (1% fee) |
+| `build_buy_instruction()` | Build PumpFun v2 BUY ix (16 accounts) |
+| `build_sell_instruction()` | Build PumpFun v2 SELL ix (14 accounts) |
+| `fetch_bonding_curve_state()` | Read reserves, creator, completion from chain |
+| `fetch_fee_recipient()` | Read fee recipient from Global account |
+
+### PumpSwap AMM (post-graduation)
+
+| Function | Description |
+|---|---|
+| `calculate_swap_output()` | Output amount for constant-product swap |
+| `build_swap_instruction()` | Build PumpSwap swap ix (13 accounts) |
+| `fetch_pool_state()` | Read pool vaults, mints, fees from chain |
+
+### PDA Helpers
+
+| Function | Description |
+|---|---|
+| `get_bonding_curve_pda()` | Derive bonding curve PDA for a mint |
+| `get_associated_token_address()` | Derive ATA (SPL Token or Token-2022) |
+
+### Constants
+
+All program IDs are exported: `PUMP_FUN_PROGRAM`, `PUMP_SWAP_PROGRAM`, `PUMP_AMM_PROGRAM`, plus system programs, discriminators, and fee accounts.
+
+---
+
+## Account Layout Notes
+
+**BUY instruction** uses 16 accounts + 1 remaining account (bonding-curve-v2 PDA).
+
+**SELL instruction** uses 14 accounts + 1 remaining — but **creator_vault [8] and token_program [9] are SWAPPED** relative to buy. This is an undocumented PumpFun quirk that causes failed transactions if you copy the buy layout.
+
+**Pump AMM pools** (pAMMBay program) can have **reversed base/quote** — base_mint=SOL, quote_mint=TOKEN. The `PoolState.base_is_sol` flag indicates this.
+
+---
+
+## Also by JinUltimate1995
+
+- **[jupiter-swap-python](https://github.com/JinUltimate1995/jupiter-swap-python)** — Jupiter swap client for Python. Async. Typed.
+- **[solana-rpc-resilient](https://github.com/JinUltimate1995/solana-rpc-resilient)** — Fault-tolerant Solana RPC with automatic failover.
+- **[dexscreener-python](https://github.com/JinUltimate1995/dexscreener-python)** — DexScreener API client for Python.
+
+---
+
+## License
+
+MIT

pumpfun_python-0.1.0/pumpfun/__init__.py

@@ -0,0 +1,53 @@
+"""
+pumpfun-python — buy and sell on PumpFun bonding curves + PumpSwap AMM.
+Directly from Python. No Jupiter needed.
+"""
+
+from .bonding_curve import (
+    BondingCurveState,
+    build_buy_instruction,
+    build_sell_instruction,
+    calculate_buy_amount,
+    calculate_sell_amount,
+    fetch_bonding_curve_state,
+)
+from .constants import (
+    PUMP_AMM_PROGRAM,
+    PUMP_FUN_PROGRAM,
+    PUMP_SWAP_PROGRAM,
+)
+from .pda import (
+    get_associated_token_address,
+    get_bonding_curve_pda,
+)
+from .pumpswap import (
+    PoolState,
+    build_swap_instruction,
+    calculate_swap_output,
+    fetch_pool_state,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Bonding curve (pre-graduation)
+    "BondingCurveState",
+    "build_buy_instruction",
+    "build_sell_instruction",
+    "calculate_buy_amount",
+    "calculate_sell_amount",
+    "fetch_bonding_curve_state",
+    # PumpSwap AMM (post-graduation)
+    "PoolState",
+    "build_swap_instruction",
+    "calculate_swap_output",
+    "fetch_pool_state",
+    # PDA helpers
+    "get_associated_token_address",
+    "get_bonding_curve_pda",
+    # Program IDs
+    "PUMP_FUN_PROGRAM",
+    "PUMP_SWAP_PROGRAM",
+    "PUMP_AMM_PROGRAM",
+    "__version__",
+]