opensettle 0.1.0

Official Python SDK for the OpenSettle API. Stablecoin billing on Base, Ethereum, Polygon, Arbitrum, Solana, and Tron.

opensettle

Official Python SDK for the OpenSettle API.

Non-custodial stablecoin billing on Base, Ethereum, Polygon, Arbitrum, Solana and Tron. Typed end-to-end, sync and async, signed-webhook verifier included, idempotent writes by default.

Install

pip install opensettle

Requires Python 3.9+.

Quickstart

from opensettle import OpenSettle

os = OpenSettle(
    api_key="sk_test_…",         # or os.environ["OPENSETTLE_KEY"]
    workspace_id="ws_…",         # or os.environ["OPENSETTLE_WORKSPACE"]
)

customer = os.customers.create(email="[e-mail]")
invoice = os.invoices.create(
    customer_id=customer["id"],
    amount_minor=19_900,
    currency="USD",
    chain="base",
    token="USDC",
    line_items=[
        {"description": "Pro plan", "quantity": 1, "unit_amount_minor": 19_900}
    ],
)
os.invoices.send(invoice["id"])

Async

import asyncio
from opensettle import AsyncOpenSettle

async def main() -> None:
    async with AsyncOpenSettle(api_key="sk_test_…", workspace_id="ws_…") as os:
        customer = await os.customers.create(email="[e-mail]")
        print(customer["id"])

asyncio.run(main())

Webhooks

from opensettle import verify_webhook, WebhookVerificationError

@app.post("/webhooks/opensettle")
async def handler(request):
    raw = await request.body()
    try:
        event = verify_webhook(
            raw_body=raw,
            signature_header=request.headers.get("x-opensettle-signature"),
            secret=os.environ["WHSEC"],
        )
    except WebhookVerificationError as e:
        return Response(status=400, content=f"bad signature: {e.reason}")
    # event.data is the decoded JSON; event.timestamp is the signed epoch
    return Response(status=200)

Error handling

from opensettle import (
    OpenSettle,
    RateLimitError,
    SettlementError,
)

try:
    os.checkouts.create(...)
except RateLimitError as e:
    time.sleep(e.retry_after or 1)
    retry()
except SettlementError as e:
    if e.code == "insufficient_confirmations":
        wait_and_retry()

The full error hierarchy:

OpenSettleError
├── InvalidRequestError
├── InvalidStateTransitionError
├── AuthenticationError
├── ForbiddenError
├── NotFoundError
├── ConflictError
├── RateLimitError              # carries `retry_after: float | None`
├── SettlementError             # chain_reverted | insufficient_confirmations | signing_required
├── StepUpRequiredError         # aal_required
├── APIError                    # internal_error or forward-compat unknown codes
└── NetworkError                # transport-layer / timeout

Every error carries code, status, request_id, and param so you can quote the request ID in support tickets.

Configuration

os = OpenSettle(
    api_key="sk_test_…",
    workspace_id="ws_…",
    base_url="https://api.opensettle.io",   # default; override for self-host
    test_mode=None,                          # None | True | False env-assertion gate
    timeout=30.0,                            # seconds; default 30s
    max_network_retries=3,                   # 0 to disable retries
)

test_mode=True refuses sk_live_… keys; test_mode=False refuses sk_test_…. Leave None to accept either and let the API decide.

Resources

Resource	Methods
customers	list, retrieve, create, update, delete
products	list, retrieve, create, update, list_prices, create_price, delete, delete_price
invoices	list, retrieve, create, send, remind, void
payments	list, retrieve, refund, refund_broadcast
subscriptions	list, retrieve, create, pause, resume, cancel, change_plan
checkouts	create, retrieve
webhook_endpoints	list, retrieve, create, update, delete, rotate_secret, test

License

MIT — see LICENSE.