pumpfun-python 0.1.0__py3-none-any.whl

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__",
+]

pumpfun/bonding_curve.py

@@ -0,0 +1,364 @@
+"""
+PumpFun bonding curve v2 — buy/sell instructions and on-chain state reading.
+
+Program: 6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P
+
+BUY:  16 accounts
+SELL: 14 accounts (creator_vault and token_program are SWAPPED vs buy)
+"""
+
+from __future__ import annotations
+
+import base64
+import struct
+from dataclasses import dataclass, field
+
+import httpx
+from solders.instruction import AccountMeta, Instruction  # type: ignore[import-untyped]
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+from .constants import (
+    PUMP_BUY_DISCRIMINATOR,
+    PUMP_FEE_PROGRAM,
+    PUMP_FUN_EVENT_AUTHORITY,
+    PUMP_FUN_GLOBAL,
+    PUMP_FUN_PROGRAM,
+    PUMP_SELL_DISCRIMINATOR,
+    SYSTEM_PROGRAM,
+    TOKEN_PROGRAM,
+)
+from .pda import (
+    get_associated_token_address,
+    get_bonding_curve_pda,
+    get_bonding_curve_v2_pda,
+    get_creator_vault_pda,
+    get_fee_config_pda,
+    get_global_volume_accumulator_pda,
+    get_user_volume_accumulator_pda,
+)
+
+
+class PumpFunError(Exception):
+    """Raised when a PumpFun operation fails."""
+
+
+@dataclass(slots=True)
+class BondingCurveState:
+    """Parsed on-chain bonding curve account state."""
+
+    virtual_token_reserves: int
+    virtual_sol_reserves: int
+    real_token_reserves: int
+    real_sol_reserves: int
+    token_total_supply: int
+    complete: bool
+    creator: Pubkey
+    is_mayhem_mode: bool = False
+    is_cashback_coin: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Price calculations (pure functions — no RPC needed)
+# ---------------------------------------------------------------------------
+
+
+def calculate_buy_amount(
+    sol_amount_lamports: int,
+    virtual_sol_reserves: int,
+    virtual_token_reserves: int,
+) -> int:
+    """
+    Calculate tokens received for a given SOL input.
+
+    Uses PumpFun's constant-product formula with 1% fee on SOL input.
+
+    Args:
+        sol_amount_lamports: SOL amount in lamports.
+        virtual_sol_reserves: Virtual SOL reserves from bonding curve state.
+        virtual_token_reserves: Virtual token reserves from bonding curve state.
+
+    Returns:
+        Number of tokens received.
+    """
+    fee = sol_amount_lamports // 100
+    sol_after_fee = sol_amount_lamports - fee
+    tokens_out = (virtual_token_reserves * sol_after_fee) // (virtual_sol_reserves + sol_after_fee)
+    return tokens_out
+
+
+def calculate_sell_amount(
+    token_amount: int,
+    virtual_sol_reserves: int,
+    virtual_token_reserves: int,
+) -> int:
+    """
+    Calculate SOL received for selling tokens.
+
+    Uses PumpFun's constant-product formula with 1% fee on SOL output.
+
+    Args:
+        token_amount: Number of tokens to sell.
+        virtual_sol_reserves: Virtual SOL reserves from bonding curve state.
+        virtual_token_reserves: Virtual token reserves from bonding curve state.
+
+    Returns:
+        SOL output in lamports (after fee).
+    """
+    if virtual_token_reserves + token_amount == 0:
+        return 0
+    sol_out_raw = (virtual_sol_reserves * token_amount) // (virtual_token_reserves + token_amount)
+    fee = sol_out_raw // 100
+    return sol_out_raw - fee
+
+
+# ---------------------------------------------------------------------------
+# On-chain state reading
+# ---------------------------------------------------------------------------
+
+
+async def fetch_bonding_curve_state(
+    rpc_url: str,
+    token_mint: str | Pubkey,
+    *,
+    http_client: httpx.AsyncClient | None = None,
+) -> BondingCurveState:
+    """
+    Fetch the PumpFun bonding curve state from on-chain.
+
+    Args:
+        rpc_url: Solana RPC endpoint URL.
+        token_mint: Token mint address (string or Pubkey).
+        http_client: Optional httpx client (creates one if not provided).
+
+    Returns:
+        BondingCurveState with reserves, creator, completion status.
+
+    Raises:
+        PumpFunError: If the account can't be read or parsed.
+    """
+    if isinstance(token_mint, str):
+        token_mint = Pubkey.from_string(token_mint)
+
+    bonding_curve = get_bonding_curve_pda(token_mint)
+
+    should_close = http_client is None
+    client = http_client or httpx.AsyncClient(timeout=httpx.Timeout(15.0))
+
+    try:
+        resp = await client.post(rpc_url, json={
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "getAccountInfo",
+            "params": [str(bonding_curve), {"encoding": "base64"}],
+        })
+        resp.raise_for_status()
+        data = resp.json()
+    finally:
+        if should_close:
+            await client.aclose()
+
+    result = data.get("result", {})
+    value = result.get("value")
+    if not value:
+        raise PumpFunError(f"Bonding curve account {bonding_curve} not found")
+
+    raw_data = value.get("data", [])
+    if not isinstance(raw_data, list) or not raw_data:
+        raise PumpFunError("Cannot decode bonding curve account data")
+
+    account_bytes = base64.b64decode(raw_data[0])
+
+    if len(account_bytes) < 81:
+        raise PumpFunError(f"Bonding curve data too short: {len(account_bytes)} bytes")
+
+    off = 8  # skip Anchor discriminator
+    virtual_token_reserves = struct.unpack_from("<Q", account_bytes, off)[0]; off += 8
+    virtual_sol_reserves = struct.unpack_from("<Q", account_bytes, off)[0]; off += 8
+    real_token_reserves = struct.unpack_from("<Q", account_bytes, off)[0]; off += 8
+    real_sol_reserves = struct.unpack_from("<Q", account_bytes, off)[0]; off += 8
+    token_total_supply = struct.unpack_from("<Q", account_bytes, off)[0]; off += 8
+    complete = account_bytes[off] != 0; off += 1
+    creator = Pubkey.from_bytes(account_bytes[off: off + 32]); off += 32
+
+    is_mayhem_mode = len(account_bytes) >= 82 and account_bytes[81] != 0
+    is_cashback_coin = len(account_bytes) >= 83 and account_bytes[82] != 0
+
+    return BondingCurveState(
+        virtual_token_reserves=virtual_token_reserves,
+        virtual_sol_reserves=virtual_sol_reserves,
+        real_token_reserves=real_token_reserves,
+        real_sol_reserves=real_sol_reserves,
+        token_total_supply=token_total_supply,
+        complete=complete,
+        creator=creator,
+        is_mayhem_mode=is_mayhem_mode,
+        is_cashback_coin=is_cashback_coin,
+    )
+
+
+async def fetch_fee_recipient(
+    rpc_url: str,
+    *,
+    http_client: httpx.AsyncClient | None = None,
+) -> Pubkey:
+    """
+    Read the fee_recipient from the PumpFun Global account.
+
+    Falls back to default on failure.
+    """
+    default = Pubkey.from_string("62qc2CNXwrYqQScmEdiZFFAnJR262PxWEuNQtxfafNgV")
+
+    should_close = http_client is None
+    client = http_client or httpx.AsyncClient(timeout=httpx.Timeout(15.0))
+
+    try:
+        resp = await client.post(rpc_url, json={
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "getAccountInfo",
+            "params": [str(PUMP_FUN_GLOBAL), {"encoding": "base64"}],
+        })
+        resp.raise_for_status()
+        data = resp.json()
+        value = data.get("result", {}).get("value")
+        if value:
+            raw = value.get("data", [])
+            if isinstance(raw, list) and raw:
+                buf = base64.b64decode(raw[0])
+                if len(buf) >= 73:
+                    return Pubkey.from_bytes(buf[41:73])
+    except Exception:
+        pass
+    finally:
+        if should_close:
+            await client.aclose()
+
+    return default
+
+
+# ---------------------------------------------------------------------------
+# Instruction builders (pure functions)
+# ---------------------------------------------------------------------------
+
+
+def build_buy_instruction(
+    user: Pubkey,
+    token_mint: Pubkey,
+    bonding_curve: Pubkey,
+    sol_amount_lamports: int,
+    min_tokens_out: int,
+    creator: Pubkey,
+    fee_recipient: Pubkey,
+    token_program: Pubkey = TOKEN_PROGRAM,
+) -> Instruction:
+    """
+    Build the PumpFun v2 BUY instruction (16 accounts).
+
+    Args:
+        user: Buyer's wallet (signer).
+        token_mint: Token mint address.
+        bonding_curve: Bonding curve PDA (from get_bonding_curve_pda).
+        sol_amount_lamports: Max SOL to spend (lamports).
+        min_tokens_out: Minimum tokens expected (slippage protection).
+        creator: Token creator from bonding curve state.
+        fee_recipient: Fee recipient (from fetch_fee_recipient or default).
+        token_program: TOKEN_PROGRAM or TOKEN_2022_PROGRAM.
+
+    Returns:
+        Solders Instruction ready to add to a transaction.
+    """
+    associated_user = get_associated_token_address(user, token_mint, token_program)
+    associated_bonding_curve = get_associated_token_address(bonding_curve, token_mint, token_program)
+    creator_vault = get_creator_vault_pda(creator)
+    global_vol = get_global_volume_accumulator_pda()
+    user_vol = get_user_volume_accumulator_pda(user)
+    fee_config = get_fee_config_pda()
+
+    data = (
+        PUMP_BUY_DISCRIMINATOR
+        + struct.pack("<Q", min_tokens_out)
+        + struct.pack("<Q", sol_amount_lamports)
+        + b"\x01"  # track_volume = Some(true)
+    )
+
+    accounts = [
+        AccountMeta(PUMP_FUN_GLOBAL, is_signer=False, is_writable=False),
+        AccountMeta(fee_recipient, is_signer=False, is_writable=True),
+        AccountMeta(token_mint, is_signer=False, is_writable=False),
+        AccountMeta(bonding_curve, is_signer=False, is_writable=True),
+        AccountMeta(associated_bonding_curve, is_signer=False, is_writable=True),
+        AccountMeta(associated_user, is_signer=False, is_writable=True),
+        AccountMeta(user, is_signer=True, is_writable=True),
+        AccountMeta(SYSTEM_PROGRAM, is_signer=False, is_writable=False),
+        AccountMeta(token_program, is_signer=False, is_writable=False),
+        AccountMeta(creator_vault, is_signer=False, is_writable=True),
+        AccountMeta(PUMP_FUN_EVENT_AUTHORITY, is_signer=False, is_writable=False),
+        AccountMeta(PUMP_FUN_PROGRAM, is_signer=False, is_writable=False),
+        AccountMeta(global_vol, is_signer=False, is_writable=True),
+        AccountMeta(user_vol, is_signer=False, is_writable=True),
+        AccountMeta(fee_config, is_signer=False, is_writable=False),
+        AccountMeta(PUMP_FEE_PROGRAM, is_signer=False, is_writable=False),
+        AccountMeta(get_bonding_curve_v2_pda(token_mint), is_signer=False, is_writable=False),
+    ]
+
+    return Instruction(PUMP_FUN_PROGRAM, data, accounts)
+
+
+def build_sell_instruction(
+    user: Pubkey,
+    token_mint: Pubkey,
+    bonding_curve: Pubkey,
+    token_amount: int,
+    min_sol_output: int,
+    creator: Pubkey,
+    fee_recipient: Pubkey,
+    token_program: Pubkey = TOKEN_PROGRAM,
+) -> Instruction:
+    """
+    Build the PumpFun v2 SELL instruction (14 accounts).
+
+    NOTE: creator_vault [8] and token_program [9] are SWAPPED vs buy!
+
+    Args:
+        user: Seller's wallet (signer).
+        token_mint: Token mint address.
+        bonding_curve: Bonding curve PDA.
+        token_amount: Number of tokens to sell.
+        min_sol_output: Minimum SOL output (lamports, slippage protection).
+        creator: Token creator from bonding curve state.
+        fee_recipient: Fee recipient.
+        token_program: TOKEN_PROGRAM or TOKEN_2022_PROGRAM.
+
+    Returns:
+        Solders Instruction.
+    """
+    associated_user = get_associated_token_address(user, token_mint, token_program)
+    associated_bonding_curve = get_associated_token_address(bonding_curve, token_mint, token_program)
+    creator_vault = get_creator_vault_pda(creator)
+    fee_config = get_fee_config_pda()
+
+    data = (
+        PUMP_SELL_DISCRIMINATOR
+        + struct.pack("<Q", token_amount)
+        + struct.pack("<Q", min_sol_output)
+    )
+
+    accounts = [
+        AccountMeta(PUMP_FUN_GLOBAL, is_signer=False, is_writable=False),
+        AccountMeta(fee_recipient, is_signer=False, is_writable=True),
+        AccountMeta(token_mint, is_signer=False, is_writable=False),
+        AccountMeta(bonding_curve, is_signer=False, is_writable=True),
+        AccountMeta(associated_bonding_curve, is_signer=False, is_writable=True),
+        AccountMeta(associated_user, is_signer=False, is_writable=True),
+        AccountMeta(user, is_signer=True, is_writable=True),
+        AccountMeta(SYSTEM_PROGRAM, is_signer=False, is_writable=False),
+        AccountMeta(creator_vault, is_signer=False, is_writable=True),   # [8] SWAPPED
+        AccountMeta(token_program, is_signer=False, is_writable=False),  # [9] SWAPPED
+        AccountMeta(PUMP_FUN_EVENT_AUTHORITY, is_signer=False, is_writable=False),
+        AccountMeta(PUMP_FUN_PROGRAM, is_signer=False, is_writable=False),
+        AccountMeta(fee_config, is_signer=False, is_writable=False),
+        AccountMeta(PUMP_FEE_PROGRAM, is_signer=False, is_writable=False),
+        AccountMeta(get_bonding_curve_v2_pda(token_mint), is_signer=False, is_writable=False),
+    ]
+
+    return Instruction(PUMP_FUN_PROGRAM, data, accounts)

pumpfun/constants.py

@@ -0,0 +1,43 @@
+"""
+Solana program IDs and instruction discriminators for PumpFun and PumpSwap.
+"""
+
+import hashlib
+
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+# ── PumpFun bonding curve program ──────────────────────────────────────────
+PUMP_FUN_PROGRAM = Pubkey.from_string("6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P")
+PUMP_FUN_GLOBAL = Pubkey.from_string("4wTV1YmiEkRvAtNtsSGPtUrqRYQMe5SKy2uB4Jjaxnjf")
+PUMP_FUN_EVENT_AUTHORITY = Pubkey.from_string("Ce6TQqeHC9p8KetsN6JsjHK7UTZk7nasjjnr7XxXp9F1")
+
+# ── PumpSwap AMM — legacy program ─────────────────────────────────────────
+PUMP_SWAP_PROGRAM = Pubkey.from_string("PSwapMdSai8tjrEXcxFeQth87xC4rRsa4VA5mhGhXkP")
+
+# ── Pump AMM — current production program (pAMMBay) ───────────────────────
+PUMP_AMM_PROGRAM = Pubkey.from_string("pAMMBay6oceH9fJKBRHGP5D4bD4sWpmSwMn52FMfXEA")
+PUMP_AMM_GLOBAL_CONFIG = Pubkey.from_string("ADyA8hdefvWN2dbGGWFotbzWxrAvLW83WG6QCVXvJKqw")
+PUMP_AMM_EVENT_AUTHORITY = Pubkey.from_string("GS4CU59F31iL7aR2Q8zVS8DRrcRnXX1yjQ66TqNVQnaR")
+
+# ── Pump Fee program ──────────────────────────────────────────────────────
+PUMP_FEE_PROGRAM = Pubkey.from_string("pfeeUxB6jkeY1Hxd7CsFCAjcbHA9rWtchMGdZ6VojVZ")
+
+# ── PumpSwap fee accounts ─────────────────────────────────────────────────
+PUMP_SWAP_GLOBAL_CONFIG = Pubkey.from_string("ADyA8hdefbpth3kCbkbEVuNyGPfbmSYdoMjMCuKLxMJo")
+PUMP_SWAP_FEE_RECIPIENT = Pubkey.from_string("62qc2CNXwrYqQScmEdiZFFAnJR262PxWEuNQtxfafNgV")
+PUMP_SWAP_EVENT_AUTHORITY = Pubkey.from_string("GS4CU59F31iL7aR2Q8xmZRbmMfXdK4cqeLGSBDmkXSWm")
+
+# ── System / Token Programs ───────────────────────────────────────────────
+TOKEN_PROGRAM = Pubkey.from_string("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")
+TOKEN_2022_PROGRAM = Pubkey.from_string("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb")
+ASSOCIATED_TOKEN_PROGRAM = Pubkey.from_string("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL")
+SYSTEM_PROGRAM = Pubkey.from_string("11111111111111111111111111111111")
+SOL_MINT = Pubkey.from_string("So11111111111111111111111111111111111111112")
+
+LAMPORTS_PER_SOL = 1_000_000_000
+
+# ── Instruction discriminators ─────────────────────────────────────────────
+# Anchor convention: sha256("global:<instruction_name>")[:8]
+PUMP_BUY_DISCRIMINATOR = bytes([102, 6, 61, 18, 1, 218, 235, 234])
+PUMP_SELL_DISCRIMINATOR = bytes([51, 230, 133, 164, 1, 127, 131, 173])
+PUMPSWAP_SWAP_DISCRIMINATOR = hashlib.sha256(b"global:swap").digest()[:8]

pumpfun/pda.py

@@ -0,0 +1,65 @@
+"""
+PDA derivation helpers for PumpFun and PumpSwap.
+"""
+
+from __future__ import annotations
+
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+from .constants import (
+    ASSOCIATED_TOKEN_PROGRAM,
+    PUMP_FEE_PROGRAM,
+    PUMP_FUN_PROGRAM,
+    TOKEN_PROGRAM,
+)
+
+
+def _find_pda(seeds: list[bytes], program_id: Pubkey) -> Pubkey:
+    """Derive a Program Derived Address."""
+    pubkey, _bump = Pubkey.find_program_address(seeds, program_id)
+    return pubkey
+
+
+def get_bonding_curve_pda(token_mint: Pubkey) -> Pubkey:
+    """Derive the PumpFun bonding curve PDA for a token mint."""
+    return _find_pda([b"bonding-curve", bytes(token_mint)], PUMP_FUN_PROGRAM)
+
+
+def get_associated_token_address(
+    owner: Pubkey,
+    mint: Pubkey,
+    token_program: Pubkey = TOKEN_PROGRAM,
+) -> Pubkey:
+    """Derive the Associated Token Account (ATA) address."""
+    return _find_pda(
+        [bytes(owner), bytes(token_program), bytes(mint)],
+        ASSOCIATED_TOKEN_PROGRAM,
+    )
+
+
+def get_creator_vault_pda(creator: Pubkey) -> Pubkey:
+    """PDA["creator-vault", creator] on the PumpFun program."""
+    return _find_pda([b"creator-vault", bytes(creator)], PUMP_FUN_PROGRAM)
+
+
+def get_bonding_curve_v2_pda(token_mint: Pubkey) -> Pubkey:
+    """PDA["bonding-curve-v2", mint] — required remaining account for v2."""
+    return _find_pda([b"bonding-curve-v2", bytes(token_mint)], PUMP_FUN_PROGRAM)
+
+
+def get_global_volume_accumulator_pda() -> Pubkey:
+    """PDA["global_volume_accumulator"] on the PumpFun program."""
+    return _find_pda([b"global_volume_accumulator"], PUMP_FUN_PROGRAM)
+
+
+def get_user_volume_accumulator_pda(user: Pubkey) -> Pubkey:
+    """PDA["user_volume_accumulator", user] on the PumpFun program."""
+    return _find_pda([b"user_volume_accumulator", bytes(user)], PUMP_FUN_PROGRAM)
+
+
+def get_fee_config_pda() -> Pubkey:
+    """PDA["fee_config", pump_program] on the fee program."""
+    return _find_pda(
+        [b"fee_config", bytes(PUMP_FUN_PROGRAM)],
+        PUMP_FEE_PROGRAM,
+    )

pumpfun/pumpswap.py

@@ -0,0 +1,262 @@
+"""
+PumpSwap AMM — constant-product pool swap instructions and on-chain state.
+
+Supports both legacy PumpSwap (PSwapMdSai...) and Pump AMM (pAMMBay...) pools.
+"""
+
+from __future__ import annotations
+
+import base64
+import struct
+from dataclasses import dataclass
+
+import httpx
+from solders.instruction import AccountMeta, Instruction  # type: ignore[import-untyped]
+from solders.pubkey import Pubkey  # type: ignore[import-untyped]
+
+from .constants import (
+    PUMP_AMM_PROGRAM,
+    PUMP_SWAP_EVENT_AUTHORITY,
+    PUMP_SWAP_FEE_RECIPIENT,
+    PUMP_SWAP_GLOBAL_CONFIG,
+    PUMP_SWAP_PROGRAM,
+    PUMPSWAP_SWAP_DISCRIMINATOR,
+    SOL_MINT,
+    TOKEN_PROGRAM,
+)
+from .pda import get_associated_token_address
+
+
+class PumpSwapError(Exception):
+    """Raised when a PumpSwap operation fails."""
+
+
+@dataclass(slots=True)
+class PoolState:
+    """Parsed on-chain PumpSwap/Pump AMM pool state."""
+
+    pool_bump: int
+    index: int
+    creator: Pubkey
+    coin_creator: Pubkey
+    base_mint: Pubkey
+    quote_mint: Pubkey
+    lp_mint: Pubkey
+    pool_base_token_account: Pubkey
+    pool_quote_token_account: Pubkey
+    lp_fee_basis_points: int
+    protocol_fee_basis_points: int
+    is_pump_amm: bool = False
+    base_is_sol: bool = False
+
+
+# ---------------------------------------------------------------------------
+# Swap math (pure functions — no RPC needed)
+# ---------------------------------------------------------------------------
+
+
+def calculate_swap_output(
+    amount_in: int,
+    reserve_in: int,
+    reserve_out: int,
+    lp_fee_bps: int,
+    protocol_fee_bps: int,
+) -> tuple[int, int]:
+    """
+    Calculate output for a constant-product AMM swap.
+
+    Fee is deducted from the input amount before computing swap.
+
+    Args:
+        amount_in: Input token amount.
+        reserve_in: Reserve of the input token in the pool.
+        reserve_out: Reserve of the output token in the pool.
+        lp_fee_bps: LP fee in basis points.
+        protocol_fee_bps: Protocol fee in basis points.
+
+    Returns:
+        Tuple of (amount_out, total_fee).
+    """
+    total_fee_bps = lp_fee_bps + protocol_fee_bps
+    fee = (amount_in * total_fee_bps) // 10_000
+    amount_in_after_fee = amount_in - fee
+
+    if reserve_in + amount_in_after_fee == 0:
+        return 0, fee
+
+    amount_out = (reserve_out * amount_in_after_fee) // (reserve_in + amount_in_after_fee)
+    return amount_out, fee
+
+
+# ---------------------------------------------------------------------------
+# On-chain state reading
+# ---------------------------------------------------------------------------
+
+
+async def fetch_pool_state(
+    rpc_url: str,
+    pool_address: str,
+    *,
+    http_client: httpx.AsyncClient | None = None,
+) -> PoolState:
+    """
+    Read a PumpSwap/Pump AMM pool account from on-chain.
+
+    Layout (after 8-byte Anchor discriminator):
+      - offset  8: pool_bump (u8)
+      - offset  9: index (u16 LE)
+      - offset 11: creator (Pubkey, 32B)
+      - offset 43: base_mint (Pubkey, 32B)
+      - offset 75: quote_mint (Pubkey, 32B)
+      - offset 107: lp_mint (Pubkey, 32B)
+      - offset 139: pool_base_token_account (Pubkey, 32B)
+      - offset 171: pool_quote_token_account (Pubkey, 32B)
+      - offset 203: lp_fee_basis_points (u64 LE) — legacy only
+      - offset 211: protocol_fee_basis_points (u64 LE) — legacy only
+
+    Args:
+        rpc_url: Solana RPC endpoint URL.
+        pool_address: Pool account address.
+        http_client: Optional httpx client.
+
+    Returns:
+        PoolState with reserves, mints, and vault addresses.
+
+    Raises:
+        PumpSwapError: If the account can't be read or parsed.
+    """
+    should_close = http_client is None
+    client = http_client or httpx.AsyncClient(timeout=httpx.Timeout(15.0))
+
+    try:
+        resp = await client.post(rpc_url, json={
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "getAccountInfo",
+            "params": [pool_address, {"encoding": "base64"}],
+        })
+        resp.raise_for_status()
+        data = resp.json()
+    finally:
+        if should_close:
+            await client.aclose()
+
+    result = data.get("result", {})
+    value = result.get("value")
+    if not value:
+        raise PumpSwapError(f"Pool account {pool_address} not found")
+
+    raw_data = value.get("data", [])
+    if not isinstance(raw_data, list) or not raw_data:
+        raise PumpSwapError("Cannot decode pool account data")
+
+    account_bytes = base64.b64decode(raw_data[0])
+    if len(account_bytes) < 219:
+        raise PumpSwapError(f"Pool data too short: {len(account_bytes)} bytes (need >= 219)")
+
+    owner = value.get("owner", "")
+    valid_owners = {str(PUMP_SWAP_PROGRAM), str(PUMP_AMM_PROGRAM)}
+    if owner and owner not in valid_owners:
+        raise PumpSwapError(f"Account owned by {owner}, not PumpSwap/PumpAMM program")
+
+    is_pump_amm = owner == str(PUMP_AMM_PROGRAM)
+
+    def _pubkey_at(offset: int) -> Pubkey:
+        return Pubkey.from_bytes(account_bytes[offset: offset + 32])
+
+    off = 8
+    pool_bump = account_bytes[off]; off += 1
+    index = struct.unpack_from("<H", account_bytes, off)[0]; off += 2
+    creator = _pubkey_at(off); off += 32
+    base_mint = _pubkey_at(off); off += 32
+    quote_mint = _pubkey_at(off); off += 32
+    lp_mint = _pubkey_at(off); off += 32
+    pool_base_token_account = _pubkey_at(off); off += 32
+    pool_quote_token_account = _pubkey_at(off); off += 32
+
+    if is_pump_amm:
+        lp_fee_basis_points = 200
+        protocol_fee_basis_points = 100
+        coin_creator = Pubkey.default()
+        if len(account_bytes) >= 243:
+            coin_creator = _pubkey_at(211)
+    else:
+        lp_fee_basis_points = struct.unpack_from("<Q", account_bytes, off)[0]; off += 8
+        protocol_fee_basis_points = struct.unpack_from("<Q", account_bytes, off)[0]; off += 8
+        coin_creator = creator
+
+    base_is_sol = is_pump_amm and str(base_mint) == str(SOL_MINT)
+
+    return PoolState(
+        pool_bump=pool_bump,
+        index=index,
+        creator=creator,
+        coin_creator=coin_creator,
+        base_mint=base_mint,
+        quote_mint=quote_mint,
+        lp_mint=lp_mint,
+        pool_base_token_account=pool_base_token_account,
+        pool_quote_token_account=pool_quote_token_account,
+        lp_fee_basis_points=lp_fee_basis_points,
+        protocol_fee_basis_points=protocol_fee_basis_points,
+        is_pump_amm=is_pump_amm,
+        base_is_sol=base_is_sol,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Instruction builder
+# ---------------------------------------------------------------------------
+
+
+def build_swap_instruction(
+    pool: Pubkey,
+    user: Pubkey,
+    user_base_token_account: Pubkey,
+    user_quote_token_account: Pubkey,
+    pool_base_token_account: Pubkey,
+    pool_quote_token_account: Pubkey,
+    protocol_fee_token_account: Pubkey,
+    base_in: bool,
+    amount_in: int,
+    min_amount_out: int,
+    base_token_program: Pubkey = TOKEN_PROGRAM,
+) -> Instruction:
+    """
+    Build the PumpSwap swap instruction.
+
+    Args:
+        pool: Pool account address.
+        user: Trader's wallet (signer).
+        user_base_token_account: User's ATA for the base (meme) token.
+        user_quote_token_account: User's ATA for the quote token (WSOL).
+        pool_base_token_account: Pool's base token vault.
+        pool_quote_token_account: Pool's quote token vault.
+        protocol_fee_token_account: Protocol fee recipient's quote ATA.
+        base_in: True = sell base for quote, False = buy base with quote.
+        amount_in: Input amount (base units / lamports).
+        min_amount_out: Minimum output (slippage protection).
+        base_token_program: Token program for base token (SPL or Token-2022).
+
+    Returns:
+        Solders Instruction ready to add to a transaction.
+    """
+    data = PUMPSWAP_SWAP_DISCRIMINATOR + struct.pack("<BQQ", int(base_in), amount_in, min_amount_out)
+
+    accounts = [
+        AccountMeta(PUMP_SWAP_GLOBAL_CONFIG, is_signer=False, is_writable=False),
+        AccountMeta(PUMP_SWAP_FEE_RECIPIENT, is_signer=False, is_writable=True),
+        AccountMeta(pool, is_signer=False, is_writable=True),
+        AccountMeta(user, is_signer=True, is_writable=True),
+        AccountMeta(user_base_token_account, is_signer=False, is_writable=True),
+        AccountMeta(user_quote_token_account, is_signer=False, is_writable=True),
+        AccountMeta(pool_base_token_account, is_signer=False, is_writable=True),
+        AccountMeta(pool_quote_token_account, is_signer=False, is_writable=True),
+        AccountMeta(protocol_fee_token_account, is_signer=False, is_writable=True),
+        AccountMeta(base_token_program, is_signer=False, is_writable=False),
+        AccountMeta(TOKEN_PROGRAM, is_signer=False, is_writable=False),
+        AccountMeta(PUMP_SWAP_EVENT_AUTHORITY, is_signer=False, is_writable=False),
+        AccountMeta(PUMP_SWAP_PROGRAM, is_signer=False, is_writable=False),
+    ]
+
+    return Instruction(PUMP_SWAP_PROGRAM, data, accounts)

pumpfun_python-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,10 @@
+pumpfun/__init__.py,sha256=Sbnl2OdOjn4PfX_OMrxgdBO5gFutHkBse1k4GDi5FhQ,1190
+pumpfun/bonding_curve.py,sha256=1_bVU5KfHkmoux4GHXf772hmGjJaIK2fOAxlkJj6gkQ,12797
+pumpfun/constants.py,sha256=XP0PHH9EuQW5kYsPY1RrEz37_4jotvb4nybsHSbnjOs,3055
+pumpfun/pda.py,sha256=7FfwymxsPQjxpKoQdMNG6Osn8cvzuc2dwl0wWJN1iVA,2018
+pumpfun/pumpswap.py,sha256=cpvFPOLbBpjZlVSt1c3OGihDNc5-lToA75gP4iRRsMc,8990
+pumpfun/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pumpfun_python-0.1.0.dist-info/METADATA,sha256=fwssk43-kbP0qiO4QlXrW9hj0B8wSafqCVxfK5ll1-0,7072
+pumpfun_python-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pumpfun_python-0.1.0.dist-info/licenses/LICENSE,sha256=D7y6S1R0LcQMuzvEM3af4NM2zASwS0H82DKH-3g_FDE,1072
+pumpfun_python-0.1.0.dist-info/RECORD,,

pumpfun_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pumpfun_python-0.1.0.dist-info/licenses/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.