onstoa 0.2.10

Usage-based billing SDK for AI applications

Stoa SDK

Usage-based billing SDK for AI applications. Wrap your AI provider calls to automatically meter usage and bill your users.

Installation

pip install onstoa

Quick Start

from fastapi.responses import RedirectResponse

from stoa import Stoa, StoaChargeRequiredError

# Reads STOA_API_KEY from environment
stoa = Stoa()

# Use your app's user ID for billing calls
client = stoa.openai(user_id="user_123")

try:
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except StoaChargeRequiredError:
    payment = stoa.create_payment_session(
        user_id="user_123",
        email="[e-mail]",
        return_url="https://app.example.com/billing/stoa-return",
    )
    if not payment.checkout_url:
        raise RuntimeError("Stoa did not return a checkout URL")
    raise RedirectResponse(payment.checkout_url, status_code=303)

Typical flow:

1. call stoa.create_payment_session(...) when you want to start a payment flow
2. keep using your app user_id in SDK billing calls
3. if a metered call raises StoaChargeRequiredError, call stoa.create_payment_session(...)

For existing users who predate your Stoa integration, call stoa.create_payment_session(...) before their first billable AI request. The operation is idempotent.

Onboard Users

Stoa can stay invisible to the customer while still owning the canonical user and membership records.

Explicitly bootstrap a member

register_member(...) is still available if you want to bootstrap a user eagerly during signup.

from stoa import Stoa

stoa = Stoa(api_key=STOA_API_KEY, base_url=STOA_BASE_URL)

result = stoa.register_member(
    registration_secret=STOA_REGISTRATION_SECRET,
    user_id=user.id,
    email=user.email,
    name=user.name,
    avatar_url=user.avatar_url,
)

# Optional: store the membership ID for debugging or richer account UX.
persist_membership_binding(
    user_id=user.id,
    membership_id=result.membership_id,
)

Stoa registers the user for billing in your app. Your app can continue billing that user with their user_id.

Start a payment flow

If you want an explicit pay or add-funds action in your product:

payment = stoa.create_payment_session(
    user_id=user.id,
    email=user.email,
    return_url="https://app.example.com/billing/stoa-return",
)

Send the user to payment.checkout_url. The response also carries the payment ID.

Recover from StoaChargeRequiredError

If a metered call fails because the user is not yet chargeable in Stoa, start a payment flow explicitly with create_payment_session(...):

from fastapi.responses import RedirectResponse

from stoa import StoaChargeRequiredError

client = stoa.openai(user_id=user.id)

try:
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except StoaChargeRequiredError:
    payment = stoa.create_payment_session(
        user_id=user.id,
        email=user.email,
        return_url="https://app.example.com/billing/stoa-return",
    )
    if not payment.checkout_url:
        raise RuntimeError("Stoa did not return a checkout URL")
    raise RedirectResponse(payment.checkout_url, status_code=303)

Supported Providers

OpenAI

client = stoa.openai(user_id="user_123")

# Chat completions
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Explain quantum computing"}]
)

# Embeddings
embeddings = client.embeddings.create(
    model="text-embedding-3-small",
    input="Hello world"
)

Anthropic

client = stoa.anthropic(user_id="user_123")

response = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a haiku about Python"}]
)

Claude Agent SDK

from claude_agent_sdk import query

stream = stoa.wrap_claude_agent_query(
    query(prompt="Write a haiku about Python"),
    user_id="user_123",
)

async for message in stream:
    handle_agent_message(message)

You can also wrap a ClaudeSDKClient instance:

from claude_agent_sdk import ClaudeSDKClient

client = stoa.wrap_claude_agent_client(
    ClaudeSDKClient(),
    user_id="user_123",
)

async for message in client.receive_response():
    handle_agent_message(message)

Stoa yields the original Claude Agent SDK messages unchanged and emits anthropic.messages usage after the stream finishes. Billing uses Stoa's Anthropic rate card from token quantities, not Claude's estimated total_cost_usd. Cache writes default to the Anthropic 5 minute cache tier until Claude Agent SDK exposes a reliable cache TTL split.

OpenRouter

Access 100+ models through a single API:

client = stoa.openrouter(user_id="user_123")

# Use any model available on OpenRouter
response = client.chat.completions.create(
    model="meta-llama/llama-3.1-70b-instruct",
    messages=[{"role": "user", "content": "Hello!"}]
)

ElevenLabs

client = stoa.elevenlabs(user_id="user_123")

audio = client.text_to_speech.convert(
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    text="Hello, welcome to our application!"
)

Environment Variables

Variable	Required	Default	Description
STOA_API_KEY	Yes	-	Your Stoa application API key
STOA_REGISTRATION_SECRET	No	-	Registration signing secret for onboarding users from your app

Example .env file

# Required
STOA_API_KEY=stoa_app_xxx
STOA_REGISTRATION_SECRET=stoa_reg_xxx

# Optional - override API endpoint
STOA_BASE_URL=https://www.onstoa.com/api

Documentation

See docs.onstoa.com for full documentation.