Metadata-Version: 2.4
Name: openlibx402-fastapi
Version: 0.1.0
Summary: FastAPI middleware and decorators for X402 payment protocol
Project-URL: Homepage, https://github.com/openlibx402/openlibx402
Project-URL: Documentation, https://docs.openlibx402.org
Project-URL: Repository, https://github.com/openlibx402/openlibx402
Author-email: OpenLibx402 Contributors <hello@openlibx402.org>
License: MIT License
        
        Copyright (c) 2025 OpenLibx402 Contributors
        
        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.
License-File: LICENSE
Keywords: fastapi,middleware,openlibx402,payments,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.8
Requires-Dist: fastapi>=0.100.0
Requires-Dist: openlibx402-core<0.2.0,>=0.1.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: uvicorn>=0.23.0; extra == 'dev'
Description-Content-Type: text/markdown

# openlibx402-fastapi

FastAPI middleware and decorators for adding X402 payment requirements to API endpoints.

## Overview

The `openlibx402-fastapi` package makes it easy to add payment requirements to your FastAPI endpoints. Simply decorate endpoints with payment requirements, and the middleware handles payment verification automatically.

## Features

- Easy-to-use decorators for payment-required endpoints
- Dependency injection support for accessing payment details
- Automatic 402 Payment Required response generation
- Configurable payment amounts and descriptions
- Seamless integration with existing FastAPI applications

## Installation

```bash
pip install openlibx402-fastapi
```

## Quick Start

### 1. Initialize X402 Configuration

```python
from fastapi import FastAPI
from openlibx402_fastapi import X402Config, init_x402
import os

# Initialize X402 configuration
config = X402Config(
    payment_address=os.getenv("PAYMENT_WALLET_ADDRESS"),
    token_mint=os.getenv("USDC_MINT_ADDRESS"),
    network="solana-devnet",
    rpc_url=os.getenv("SOLANA_RPC_URL", "https://api.devnet.solana.com"),
)
init_x402(config)

app = FastAPI()
```

### 2. Add Payment Requirements with Decorator

```python
from fastapi import Request
from openlibx402_fastapi import payment_required

@app.get("/premium-data")
@payment_required(
    amount="0.10",
    description="Access to premium market data"
)
async def get_premium_data(request: Request):
    """Endpoint requires 0.10 USDC payment"""
    return {
        "data": "This is premium content",
        "market_data": {"price": 100.50, "volume": 1_000_000}
    }
```

### 3. Access Payment Details with Dependency Injection

```python
from fastapi import Depends
from openlibx402_fastapi import verify_payment_factory
from openlibx402_core import PaymentAuthorization

@app.get("/expensive-data")
async def get_expensive_data(
    payment: PaymentAuthorization = Depends(
        verify_payment_factory(
            amount="1.00",
            description="Access to expensive AI model inference"
        )
    )
):
    """Access payment details in your endpoint"""
    return {
        "data": "AI-generated content",
        "payment_id": payment.payment_id,
        "amount_paid": payment.actual_amount,
        "transaction_hash": payment.transaction_hash,
    }
```

## Usage Patterns

### Pattern 1: Simple Decorator (Recommended)

Best for endpoints that don't need to access payment details:

```python
@app.get("/data")
@payment_required(amount="0.05", description="Data access")
async def get_data(request: Request):
    return {"data": "content"}
```

### Pattern 2: Dependency Injection

Best when you need to access payment details (transaction hash, amount, etc.):

```python
@app.get("/data")
async def get_data(
    payment: PaymentAuthorization = Depends(
        verify_payment_factory(amount="0.05", description="Data access")
    )
):
    return {
        "data": "content",
        "payment_id": payment.payment_id,
        "tx_hash": payment.transaction_hash,
    }
```

### Pattern 3: Dynamic Pricing

Adjust payment requirements based on parameters:

```python
@app.get("/tiered-data/{tier}")
@payment_required(amount="0.05", description="Tiered data access")
async def get_tiered_data(request: Request, tier: str):
    """Payment required regardless of tier"""
    tier_data = {
        "basic": {"quality": "720p"},
        "premium": {"quality": "4K"},
    }
    return {"tier": tier, "data": tier_data.get(tier)}
```

## Complete Example

```python
from fastapi import FastAPI, Depends, Request
from openlibx402_fastapi import (
    payment_required,
    verify_payment_factory,
    X402Config,
    init_x402
)
from openlibx402_core import PaymentAuthorization
import os

# Initialize X402
config = X402Config(
    payment_address=os.getenv("PAYMENT_WALLET_ADDRESS"),
    token_mint=os.getenv("USDC_MINT_ADDRESS"),
    network="solana-devnet",
)
init_x402(config)

app = FastAPI()

@app.get("/")
async def root():
    """Public endpoint - no payment required"""
    return {"message": "Welcome to the API"}

@app.get("/premium")
@payment_required(amount="0.10", description="Premium data")
async def premium(request: Request):
    """Protected endpoint - payment required"""
    return {"data": "premium content"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

## Configuration

### X402Config Options

- `payment_address`: Your Solana wallet address for receiving payments
- `token_mint`: Token mint address (e.g., USDC on Solana)
- `network`: Network name (e.g., "solana-devnet", "solana-mainnet")
- `rpc_url`: Solana RPC endpoint URL

## Documentation

For complete API reference and guides, see:
- [Documentation](https://docs.openlibx402.org)
- [GitHub Repository](https://github.com/openlibx402/openlibx402)
- [Full Example](https://github.com/openlibx402/openlibx402/tree/main/examples/python/fastapi-server)

## Testing

```bash
pytest tests/
```

## License

MIT License - See [LICENSE](LICENSE) file for details.
