pumpswap-python-sdk 1.0.0__tar.gz

pumpswap_python_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pump.fun
+
+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.

pumpswap_python_sdk-1.0.0/MANIFEST.in

@@ -0,0 +1,16 @@
+include README.md
+include LICENSE
+include requirements.txt
+include requirements-dev.txt
+include pyproject.toml
+
+recursive-include pump_swap_sdk *.py
+recursive-include tests *.py
+recursive-include docs *.md *.rst
+recursive-include examples *.py *.md
+
+global-exclude *.pyc
+global-exclude __pycache__
+global-exclude .DS_Store
+global-exclude *.so
+global-exclude .git*

pumpswap_python_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,399 @@
+Metadata-Version: 2.4
+Name: pumpswap-python-sdk
+Version: 1.0.0
+Summary: Python SDK for interacting with Pump Swap AMM protocol on Solana
+Home-page: https://github.com/pump-fun/pump-swap-sdk-python
+Author: PumpSwap Python SDK Contributors
+Author-email: PumpSwap Python SDK Contributors <dev@pump.fun>
+Maintainer-email: PumpSwap Team <dev@pump.fun>
+License: MIT
+Project-URL: Documentation, https://docs.pump.fun/sdk/python
+Project-URL: Repository, https://github.com/pump-fun/pump-swap-sdk-python
+Project-URL: Issues, https://github.com/pump-fun/pump-swap-sdk-python/issues
+Project-URL: Homepage, https://pump.fun
+Keywords: solana,blockchain,defi,amm,swap,liquidity,pump,cryptocurrency,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: System :: Networking
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: solders>=0.20.0
+Requires-Dist: solana>=0.32.0
+Requires-Dist: construct>=2.10.0
+Requires-Dist: typing-extensions>=4.0.0; python_version < "3.10"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=6.0.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
+Requires-Dist: myst-parser>=1.0.0; extra == "docs"
+Provides-Extra: testing
+Requires-Dist: pytest>=7.0.0; extra == "testing"
+Requires-Dist: pytest-cov>=4.0.0; extra == "testing"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "testing"
+Requires-Dist: responses>=0.23.0; extra == "testing"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# PumpSwap SDK Python
+
+A complete Python SDK for interacting with the Pump Swap AMM protocol on Solana. This SDK provides both high-level and low-level interfaces for creating pools, performing swaps, managing liquidity, and collecting fees.
+
+## Features
+
+- 🔄 **Token Swaps**: Buy and sell tokens using constant product AMM formula
+- 💧 **Liquidity Management**: Add and remove liquidity from pools
+- 🏭 **Pool Creation**: Create new AMM pools with custom parameters
+- 💰 **Fee Collection**: Collect protocol and creator fees
+- 🎁 **Token Incentives**: Claim trading rewards and incentives
+- 📊 **Real-time Data**: Fetch live pool data and user balances
+- 🔧 **Admin Functions**: Protocol administration and configuration
+- ✅ **Full Validation**: Comprehensive input validation and error handling
+
+## Installation
+
+```bash
+pip install pumpswap-python-sdk
+```
+
+For development:
+
+```bash
+pip install pumpswap-python-sdk[dev]
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from pump_swap_sdk import PumpAmmSdk, OnlinePumpAmmSdk
+from solana.rpc.api import Client
+from solders.pubkey import Pubkey
+
+# Initialize SDK with blockchain connection
+connection = Client("https://api.mainnet-beta.solana.com")
+sdk = OnlinePumpAmmSdk(connection=connection)
+
+# Get pool state for swaps
+pool_address = Pubkey.from_string("YOUR_POOL_ADDRESS")
+user_address = Pubkey.from_string("YOUR_WALLET_ADDRESS")
+
+swap_state = sdk.swap_solana_state(pool_address, user_address)
+
+# Calculate swap amounts
+result = sdk.buy_base_input(
+    swap_state=swap_state,
+    base=1_000_000,  # 1 token (6 decimals)
+    slippage=100     # 1% slippage
+)
+
+print(f"Quote needed: {result.ui_quote}")
+print(f"Max quote with slippage: {result.max_quote}")
+```
+
+### Creating a Pool
+
+```python
+from pump_swap_sdk import OnlinePumpAmmSdk
+from solders.keypair import Keypair
+
+# Initialize with your keypair
+creator_keypair = Keypair.from_secret_key(your_secret_key)
+sdk = OnlinePumpAmmSdk(connection=connection)
+
+# Create pool state
+create_state = sdk.create_pool_solana_state(
+    index=0,
+    creator=creator_keypair.pubkey(),
+    base_mint=Pubkey.from_string("BASE_TOKEN_MINT"),
+    quote_mint=Pubkey.from_string("QUOTE_TOKEN_MINT")
+)
+
+# Build creation instructions
+instructions = sdk.create_pool_instructions(
+    create_pool_state=create_state,
+    base_in=1_000_000_000,    # Initial base tokens
+    quote_in=1_000_000_000    # Initial quote tokens
+)
+```
+
+### Managing Liquidity
+
+```python
+# Get liquidity state
+liquidity_state = sdk.liquidity_solana_state(pool_address, user_address)
+
+# Add liquidity with base token amount
+deposit_result = sdk.deposit_base_input(
+    liquidity_state=liquidity_state,
+    base=1_000_000,  # Base token amount
+    slippage=100     # 1% slippage
+)
+
+print(f"Quote needed: {deposit_result.quote}")
+print(f"LP tokens to receive: {deposit_result.lp_token}")
+
+# Remove liquidity
+withdraw_result = sdk.withdraw_inputs(
+    liquidity_state=liquidity_state,
+    lp_amount=500_000,  # LP tokens to burn
+    slippage=100        # 1% slippage
+)
+
+print(f"Base tokens to receive: {withdraw_result.base}")
+print(f"Quote tokens to receive: {withdraw_result.quote}")
+```
+
+## Advanced Usage
+
+### Offline SDK (No Blockchain Connection)
+
+```python
+from pump_swap_sdk import PumpAmmSdk
+
+# Use offline SDK for calculations without network calls
+offline_sdk = PumpAmmSdk()
+
+# You'll need to provide the state data manually
+from pump_swap_sdk.types import SwapSolanaState, Pool, GlobalConfig
+
+# Build state with your data
+swap_state = SwapSolanaState(
+    pool=your_pool_data,
+    global_config=your_global_config,
+    pool_base_amount=base_reserve,
+    pool_quote_amount=quote_reserve,
+    # ... other required fields
+)
+
+# Perform calculations
+result = offline_sdk.buy_base_input(swap_state, 1_000_000, 100)
+```
+
+### Fee Calculations
+
+```python
+from pump_swap_sdk.sdk.fees import compute_fees_bps
+
+# Calculate current fee rates
+fees = compute_fees_bps(
+    global_config=global_config,
+    fee_config=fee_config,
+    market_cap=current_market_cap
+)
+
+print(f"LP Fee: {fees.lp_fee_bps} bps")
+print(f"Protocol Fee: {fees.protocol_fee_bps} bps")
+print(f"Creator Fee: {fees.creator_fee_bps} bps")
+print(f"Total Fee: {fees.total_fee_bps} bps")
+```
+
+### Token Incentives
+
+```python
+# Check unclaimed rewards
+unclaimed = sdk.get_total_unclaimed_tokens(user_address)
+print(f"Unclaimed tokens: {unclaimed}")
+
+# Check today's earned rewards
+today_rewards = sdk.get_current_day_tokens(user_address)
+print(f"Today's rewards: {today_rewards}")
+```
+
+## SDK Architecture
+
+### Core Classes
+
+- **`PumpAmmSdk`**: High-level offline SDK for calculations
+- **`OnlinePumpAmmSdk`**: Online SDK with blockchain connectivity
+- **`PumpAmmAdminSdk`**: Admin SDK for protocol management
+
+### Key Modules
+
+- **`swap_operations`**: Buy/sell token calculations
+- **`liquidity_operations`**: Deposit/withdraw liquidity calculations
+- **`fees`**: Fee calculation utilities
+- **`token_incentives`**: Trading reward calculations
+- **`pda`**: Program Derived Address utilities
+- **`utils`**: Mathematical and utility functions
+
+## Mathematical Formulas
+
+The SDK implements a **constant product AMM** using the formula `x * y = k`:
+
+### Swap Calculations
+
+**Buy tokens (base input)**:
+```
+quote_needed = ceil_div(quote_reserve * base_amount, base_reserve - base_amount)
+```
+
+**Sell tokens (base input)**:
+```
+quote_received = floor_div(quote_reserve * base_amount, base_reserve + base_amount)
+```
+
+### Liquidity Calculations
+
+**LP tokens for deposit**:
+```
+lp_tokens = min(
+    base_amount * total_lp_supply / base_reserve,
+    quote_amount * total_lp_supply / quote_reserve
+)
+```
+
+**Tokens from LP withdrawal**:
+```
+base_amount = lp_amount * base_reserve / total_lp_supply
+quote_amount = lp_amount * quote_reserve / total_lp_supply
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling:
+
+```python
+from pump_swap_sdk.exceptions import (
+    InsufficientLiquidityError,
+    SlippageExceededError,
+    ValidationError
+)
+
+try:
+    result = sdk.buy_base_input(swap_state, amount, slippage)
+except InsufficientLiquidityError:
+    print("Not enough liquidity for this trade")
+except SlippageExceededError:
+    print("Price moved beyond slippage tolerance")
+except ValidationError as e:
+    print(f"Invalid input: {e}")
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Solana RPC endpoint
+SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+
+# Program ID (optional, defaults to mainnet)
+PUMP_AMM_PROGRAM_ID=6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P
+```
+
+### Custom Configuration
+
+```python
+from pump_swap_sdk import OnlinePumpAmmSdk
+from solders.pubkey import Pubkey
+
+# Use custom program ID
+custom_program_id = Pubkey.from_string("YOUR_PROGRAM_ID")
+sdk = OnlinePumpAmmSdk(
+    connection=connection,
+    program_id=custom_program_id
+)
+```
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Install development dependencies
+pip install -e .[dev]
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=pump_swap_sdk --cov-report=html
+
+# Run specific test categories
+pytest -m unit        # Unit tests only
+pytest -m integration # Integration tests only
+```
+
+## Examples
+
+Check out the `examples/` directory for complete working examples:
+
+- **`basic_swap.py`**: Simple token swap
+- **`liquidity_management.py`**: Add/remove liquidity
+- **`pool_creation.py`**: Create a new AMM pool
+- **`fee_calculation.py`**: Calculate trading fees
+- **`admin_operations.py`**: Protocol administration
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/pump-fun/pump-swap-sdk-python.git
+cd pump-swap-sdk-python
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# or
+venv\\Scripts\\activate  # Windows
+
+# Install in development mode
+pip install -e .[dev]
+
+# Install pre-commit hooks
+pre-commit install
+
+# Run tests
+pytest
+```
+
+## Documentation
+
+- [Full API Documentation](https://docs.pump.fun/sdk/python)
+- [Protocol Documentation](https://docs.pump.fun)
+- [Examples](./examples/)
+
+## Support
+
+- [GitHub Issues](https://github.com/pump-fun/pump-swap-sdk-python/issues)
+- [Discord Community](https://discord.gg/pump)
+- [Documentation](https://docs.pump.fun)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Related Projects
+
+- [Pump Swap TypeScript SDK](https://github.com/pump-fun/pump-swap-sdk)
+- [Pump.fun Frontend](https://pump.fun)
+- [Solana Program](https://github.com/pump-fun/pump-swap-program)
+
+---
+
+Built with ❤️ by the Pump.fun team