Metadata-Version: 2.4
Name: cinderwright-server
Version: 1.0.0
Summary: Add x402 payment gating to any Python API -- list it in the Cinderwright index in minutes
License: MIT
Project-URL: Homepage, https://api.ideafactorylab.org
Project-URL: Repository, https://github.com/cinderwright-ai/cinderwright-api
Keywords: x402,l402,payments,api,monetize,bitcoin,lightning,usdc,flask,fastapi,ai,agents,micropayments
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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 :: Internet :: WWW/HTTP
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: flask
Requires-Dist: flask>=2.0.0; extra == "flask"
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == "fastapi"
Provides-Extra: all
Requires-Dist: flask>=2.0.0; extra == "all"
Requires-Dist: fastapi>=0.100.0; extra == "all"

# cinderwright-server

[![PyPI](https://img.shields.io/pypi/v/cinderwright-server)](https://pypi.org/project/cinderwright-server/)

**Monetize any Python API in minutes.** Add x402 payment gating to a Flask or FastAPI endpoint with one decorator. Your service is automatically listed in the [Cinderwright index](https://api.ideafactorylab.org) where AI agents can discover and pay for it.

---

## Install

```bash
pip install cinderwright-server
```

---

## Quickstart

**1. Register your service**

```bash
cinderwright-server register \
    --name "My Weather API" \
    --url https://myapi.com \
    --key sk_cw_... \
    --wallet 0xYourBaseWallet \
    --price 0.01 \
    --description "Real-time weather for any city"
```

You'll receive a `service_key` and `service_secret`. Store the secret as an environment variable.

```bash
export CW_SERVICE_SECRET=ss_...
```

**2. Add the decorator**

Flask:

```python
from flask import Flask, jsonify, request
from cinderwright_server import x402
import os

app = Flask(__name__)

@app.route('/weather')
@x402(
    price=0.01,
    service_key="svc_cw_...",
    service_secret=os.environ['CW_SERVICE_SECRET'],
    description="Real-time weather for any city",
)
def weather():
    city = request.args.get('city', 'London')
    return jsonify({'weather': get_weather(city), 'city': city})

if __name__ == '__main__':
    app.run(port=5000)
```

FastAPI:

```python
from fastapi import FastAPI, Request
from cinderwright_server import x402
import os

app = FastAPI()

@app.get('/weather')
@x402(
    price=0.01,
    service_key="svc_cw_...",
    service_secret=os.environ['CW_SERVICE_SECRET'],
)
async def weather(request: Request, city: str = 'London'):
    return {'weather': get_weather(city), 'city': city}
```

**3. Test it**

```bash
cinderwright-server test --url https://myapi.com/weather
```

Output:
```
✓ Returns 402 Payment Required
✓ payment-required header present
✓ x402Version: 1
✓ price: $0.01
✓ service_key: svc_cw_...
```

**4. Check earnings**

```bash
cinderwright-server earnings
```

---

## How it works

When an AI agent calls your service without payment:
- Your endpoint returns `402 Payment Required` with the price and routing info
- The agent's Cinderwright proxy pays on their behalf
- The proxy retries with an `X-CW-Verify` header
- Your decorator verifies the HMAC token (no blockchain calls needed)
- Request passes through, you earn per call

**Earnings:** You receive the price you set minus a $0.003 infrastructure fee. Earnings accumulate as Cinderwright credits, redeemable against API calls or future withdrawal.

---

## Local development

Set `CW_DEV_MODE=1` to skip payment verification during local development:

```bash
export CW_DEV_MODE=1
python app.py
```

Or pass it to the decorator:

```python
@x402(price=0.01, service_key="...", service_secret="...", dev_mode=True)
def handler():
    ...
```

---

## Pricing model

You set the price. We take $0.003 per verified call. You keep the rest.

| Your price | You receive | Our fee |
|---|---|---|
| $0.01/call | $0.007 | $0.003 |
| $0.005/call | $0.002 | $0.003 |
| $0.05/call | $0.047 | $0.003 |

Minimum price: $0.005 (must exceed our fee).

---

## Discovery

Once registered, your service appears in the Cinderwright index at:
`https://api.ideafactorylab.org/discover?q=your+service+name`

AI agents using `pip install cinderwright` or the MCP server will automatically discover and call it.

---

## CLI reference

```bash
# Register a new service
cinderwright-server register --name NAME --url URL --key CW_KEY --wallet WALLET [--price 0.01] [--description DESC]

# Check earnings
cinderwright-server earnings [--key svc_cw_...] [--secret ss_...]

# Test endpoint returns proper 402
cinderwright-server test --url https://myapi.com/endpoint
```

---

## Links

- [Cinderwright index](https://api.ideafactorylab.org)
- [Consumer SDK (call services)](https://pypi.org/project/cinderwright/)
- [Source](https://github.com/cinderwright-ai/cinderwright-api)
