Metadata-Version: 2.4
Name: django-solana-payments
Version: 0.2.2
Summary: A plug-and-play Django library for accepting online payments via the Solana blockchain
License: MIT
License-File: LICENSE
Keywords: payments,solana,e-commerce
Author: Artemooon
Author-email: artiom.logachiov@gmail.com
Requires-Python: >=3.10
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
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 :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: drf
Requires-Dist: Django (>=4.2)
Requires-Dist: cryptography (>=46.0.3,<47.0.0)
Requires-Dist: djangorestframework (>=3.14) ; extra == "drf"
Requires-Dist: httpx (>=0.24.0)
Requires-Dist: myst-parser (>=2.0) ; extra == "docs"
Requires-Dist: pre-commit (>=4.0.0) ; extra == "dev"
Requires-Dist: pytest (>=9.0.2,<10.0.0) ; extra == "dev"
Requires-Dist: pytest-cov (>=5.0.0) ; extra == "dev"
Requires-Dist: pytest-django (>=4.11.1,<5.0.0) ; extra == "dev"
Requires-Dist: solana (>=0.36.10)
Requires-Dist: solders (>=0.18.0)
Requires-Dist: sphinx (>=7.0) ; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints (>=2.0) ; extra == "docs"
Requires-Dist: sphinx-rtd-theme (>=2.0) ; extra == "docs"
Requires-Dist: stamina (>=23.1.0)
Project-URL: Documentation, https://django-solana-payments.readthedocs.io/
Project-URL: Homepage, https://github.com/Artemooon/django-solana-payments
Project-URL: issues, https://github.com/Artemooon/django-solana-payments/issues
Description-Content-Type: text/markdown

# Django Solana Payments

![Documentation Status](https://app.readthedocs.org/projects/django-solana-payments/badge/?version=latest)
[![Coverage Status](https://coveralls.io/repos/github/Artemooon/django-solana-payments/badge.svg?branch=main)](https://coveralls.io/github/Artemooon/django-solana-payments?branch=main)
[![PyPI version](https://badge.fury.io/py/django-solana-payments.svg)](https://badge.fury.io/py/django-solana-payments)
[![Python versions](https://img.shields.io/pypi/pyversions/django-solana-payments.svg)]( https://pypi.python.org/pypi/django-solana-payments)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Artemooon/django-solana-payments/blob/main/LICENSE)

A Django library for integrating Solana payments into your project. This library provides a flexible and customizable way to accept Solana payments with support for customizable models, an easy-to-use API, and management commands for processing online payments using the Solana blockchain.

## Key Features

-   **Transaction verification and automatic payment confirmation**: Monitors the Solana blockchain, verifies incoming transactions, and automatically confirms payments when the expected amount is received.
-   **Multi-token support (SOL and SPL tokens)**: Configure a list of active payment tokens (for example, SOL and USDC) and the library will use them for pricing and verification flows.
-   **Flexibility and customization**: Use your own custom models for payments and tokens to fit your project's needs. Add custom logic using signals or callabacks.
-   **Ease of integration**: Provides ready-to-use endpoints that can be used in existing DRF applications, or ready-to-use methods for Django applications that are not part of DRF.
-   **Security and encryption**: Provides an out-of-the-box encryption mechanism that helps keep one-time payment wallets secure.
-   **Management commands**: Includes management commands for handling expired payments and sending funds from one-time wallets.

## Documentation

See the full documentation at https://django-solana-payments.readthedocs.io/

## Installation

1.  **Install the package**
    ```bash
    pip install django-solana-payments
    ```

    For DRF support, which provides API endpoints for creating and managing payments, install the `drf` extra:
    ```bash
    pip install "django-solana-payments[drf]"
    ```
    This provides ready-to-use API endpoints for creating and managing payments.

2.  **Configure `settings.py`**
    ```python
    INSTALLED_APPS = [
        ...,
        'django_solana_payments',
    ]

    SOLANA_PAYMENTS = {
        "RPC_URL": "https://api.mainnet-beta.solana.com",
        "RECEIVER_ADDRESS": "YOUR_WALLET_ADDRESS", # Wallet that receives funds
        "FEE_PAYER_KEYPAIR": "WALLET_KEYPAIR", # Wallet keypair that pays network fees (address will be derived from the keypair)
        # FEE_PAYER_ADDRESS is derived from FEE_PAYER_KEYPAIR; you don't normally need to set it separately.
        "ONE_TIME_WALLETS_ENCRYPTION_ENABLED": True, # Enables encryption for one-time payments wallets
        "ONE_TIME_WALLETS_ENCRYPTION_KEY": "ONE_TIME_WALLETS_ENCRYPTION_KEY", # Generate with the Fernet.generate_key()
        "SOLANA_PAYMENT_MODEL": "payments.CustomSolanaPayment", # Custom model for solana payment
        "PAYMENT_CRYPTO_TOKEN_MODEL": "payments.CustomPaymentToken", # Custom model for solana payment token
        "RPC_COMMITMENT": "Confirmed", # RPC Commitment
        "PAYMENT_ACCEPTANCE_COMMITMENT": "Confirmed", # Commitment for payment acceptance
        "MAX_ATAS_PER_TX": 8, # Max associated token accounts to create/close per transaction (needed for oen time wallets creation)
        "PAYMENT_VALIDITY_SECONDS": 30 * 60, # Payment validity window in seconds (default: 30 minutes)
    }
    ```

3.  **Migrate and Route**
```bash
python manage.py migrate
```

```python
# Add this to your urls.py
urlpatterns = [
    path('solana-payments/', include('django_solana_payments.urls')),
]
```

4. **Open the admin panel and create payment token records, specifying the correct mint addresses for SPL tokens.**

## Integration in 3 simple steps

Start accepting Solana payments with a fast, production-ready flow designed for real checkout UX.

### Integration flow

Typical API flow:

1. Call `POST /solana-payments/initiate/` to create a payment and receive `payment_address`.
2. Show that address/QR code to the payer, then the payer sends funds to the `payment_address`.
3. Poll `GET /solana-payments/verify-transfer/{payment_address}?token_type=...` until status becomes `confirmed` or `finalized`.

Common UI examples:

- Connect crypto wallet -> show payment summary in the wallet extension -> user signs and sends transaction -> app checks payment status.
- Open wallet app (Phantom/Solflare/mobile wallet) -> scan the QR code -> send expected amount -> return to your app -> app payment checks status.

Optionally call `GET /solana-payments/payments/{payment_address}/` for details.

## Demo 

[![Postman demo](./docs/assets/postman-demo.gif)](./docs/assets/postman-demo.gif)

## Running the Example Project

The included example project provides a demonstration of how to use the library and what it can do. To run it:

1.  **Navigate to the example project directory**
    ```bash
    cd examples/demo_project
    ```

2.  **Install dependencies**
    ```bash
    pip install -r requirements.txt
    ```

3.  **Run migrations**
    ```bash
    python mange.py makemigrations
    python manage.py migrate
    ```

4.  **Start the development server**
    ```bash
    ./dev_server.sh
    ```

## Running Tests

To run the tests for the library:

1.  **Install test dependencies**
    ```bash
    pip install pytest pytest-django
    ```

2.  **Run the tests**
    ```bash
    pytest
    ```

## License 

This package is licensed under the MIT License. See the LICENSE file for more details.

## Contributing

Contributions are welcome. Please read [CONTRIBUTING.md](./CONTRIBUTING.md) for setup instructions, testing, feature proposals, and pull request guidelines.

If you find this project useful, consider giving it a star to support its development!

## Developer Guide

### Local setup

1. Clone the repository and create a virtual environment:

   ```bash
   git clone https://github.com/Artemooon/django-solana-payments.git
   cd django-solana-payments
   python -m venv .venv
   source .venv/bin/activate
   ```

2. Install development dependencies:

   ```bash
   pip install -e ".[dev,docs,drf]"
   ```

3. Run tests:

   ```bash
   pytest
   ```

### Install pre-commit

Install and enable git hooks:

```bash
pip install pre-commit # (if not installed)
pre-commit install
```

### Release process

1. Bump version in `pyproject.toml`.
2. Commit and tag:

   ```bash
   git add -A
   git commit -m "Release x.y.z"
   git tag vx.y.z
   git push origin main --tags
   ```

The GitHub `Release` workflow publish automatically on pushed tags.

