caelum0x a27d00519c fix(sdk-python): x402 api-mode verifier called a route that was never registered
X402Verifier("api") — the only production-safe x402 verification mode, since
"accept" trusts any proof blindly — POSTed to /v1/x402/verify. That route is
never mounted in apps/api (only /v1/paid and /v1/x402/{networks,research,...}
exist). Every call 404'd and was swallowed by `except SettleKitError: return
False`, so every real payment proof verified via the SDK's documented
production path was silently rejected, forever.

Rewire _verify_via_api to POST /v1/payments/observe, the endpoint that
actually does what the docstring promised: independently re-verify the
txHash on-chain (recipient, asset, amount) and record a confirmed payment
credited to the caller's org, idempotent on txHash.

Add the Python SDK's first tests (sdks/python/tests/ did not exist despite
pytest being declared as a dev dependency): one asserts the real endpoint and
body shape are used (fails against the pre-fix code), one asserts a non-2xx
response is treated as a failed verification.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-20 17:49:08 +03:00
..
2026-06-17 02:09:36 +03:00
2026-06-17 02:09:36 +03:00
2026-06-17 02:09:36 +03:00

settlekit (Python SDK)

The official SettleKit Python SDK — sell software, private repos, SaaS, APIs, and AI tools in USDC, and guard your own paid APIs with x402 pay-per-call.

Works against the SettleKit HTTP API. Python 3.10+.

Install

pip install -e sdks/python          # from this repo
# or, once published:  pip install settlekit

Quick start

from settlekit import SettleKit

sk = SettleKit(api_key="sk_live_...", base_url="http://localhost:8787")
# or rely on env: SETTLEKIT_API_KEY / SETTLEKIT_API_URL

product = sk.products.create(
    merchant_id="mch_1",
    organization_id="org_1",
    name="Pro Repo Access",
    type="github_repo_access",
    delivery_mode="github_invite",
)
sk.prices.create(product["id"], amount="25.00", interval="monthly")

for p in sk.products.list():
    print(p["id"], p["name"])

The client unwraps the { "data": ... } envelope and raises a typed SettleKitError(code, message, status) on any { "error": ... } response.

Async

import asyncio
from settlekit import AsyncSettleKit

async def main():
    async with AsyncSettleKit() as sk:
        listings = await sk.marketplace.search(tag="saas", sort="top")
        print(listings)

asyncio.run(main())

Verifying access

Gate your own app on SettleKit entitlements / keys:

from settlekit import verify_license, verify_api_key, verify_entitlement

if not verify_license(license_key, product_id="prod_cli", machine_id=machine_fp):
    raise SystemExit("Invalid license")

if not verify_api_key(presented_key, required_scopes=["read"]):
    raise PermissionError("Bad API key")

if not verify_entitlement(customer_id="cus_1", feature="ai_export"):
    raise PermissionError("Upgrade required")

Selling a paid API with x402

Charge humans and AI agents per call. require_payment returns HTTP 402 with the payment requirements when no valid X-PAYMENT proof is supplied, and lets the request through once the buyer has paid:

from fastapi import FastAPI, Depends
from settlekit.x402 import require_payment

app = FastAPI()

@app.get("/research")
def research(_payment=Depends(require_payment(price="0.005", network="arc",
                                              pay_to="0xMerchantWallet",
                                              resource="/research"))):
    return {"answer": "Paid research result"}

A runnable example lives in examples/paid_api.py:

pip install -e sdks/python fastapi uvicorn
uvicorn examples.paid_api:app --reload
curl -i localhost:8000/research      # -> 402 Payment Required + requirements

Package layout

settlekit/
  client.py          SettleKit + AsyncSettleKit clients (envelope-aware)
  _transport.py      httpx transport + retries
  errors.py          SettleKitError and subtypes
  verify.py          license / api-key / entitlement verification helpers
  x402.py            FastAPI/Starlette require_payment middleware + 402 flow
  resources/         products, prices, customers, checkout, payments,
                     entitlements, license_keys, api_keys, coupons, invoices,
                     refunds, payouts, agent_services, marketplace
examples/paid_api.py runnable x402-guarded FastAPI app