cinderwright-server 1.0.0

Add x402 payment gating to any Python API -- list it in the Cinderwright index in minutes

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 where AI agents can discover and pay for it.

---

Install

pip install cinderwright-server

---

Quickstart

1. Register your service

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.

export CW_SERVICE_SECRET=ss_...

2. Add the decorator

Flask:

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:

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

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

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:

export CW_DEV_MODE=1
python app.py

Or pass it to the decorator:

@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

# 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
• Consumer SDK (call services)
• Source