onstoa 0.2.1

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 stoa import Stoa, InsufficientBalanceError

# Reads STOA_API_KEY and STOA_APP_ID from environment
stoa = Stoa()

# 1. Register or reuse the member from your backend
stoa.register_member(
    registration_secret=STOA_REGISTRATION_SECRET,
    user_id="user_123",
    email="[e-mail]",
)

# 2. Use your app's own 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 InsufficientBalanceError as e:
    print(f"Please top up: {e.topup_url}")

Typical flow:

1. call stoa.register_member(...) at one reliable server-side onboarding point for the user
2. keep using your own app user_id in SDK billing calls
3. send the user to e.topup_url if they need funds

If you already have users who predate your Stoa integration, you can also add a one-time lazy fallback 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.

User onboards via your app

From your backend, call the SDK once with your registration secret and the user's verified app identity:

from stoa import Stoa

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

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 its own user_id.

Optional: open a hosted top-up page

If you want an explicit "Add funds" action in your product:

topup_url = stoa.get_topup_url(user_id=user.id)

This returns a hosted Stoa payment page for that app user.

User installs via Stoa marketplace

Marketplace installs use the install flow below.

Install callback

Add a callback endpoint that verifies the Stoa install token and activates the membership for your app user. Both flows should converge on the same stored membership binding in your app.

from stoa import Stoa

stoa = Stoa()


def stoa_callback(token: str):
    claims = stoa.verify_install_callback(token=token)

    user = find_or_create_user(
        email=claims["email"],
        name=claims["name"],
    )

    install = stoa.exchange_install_token(
        token=token,
        user_id=user.id,
    )

    persist_membership_binding(
        user_id=user.id,
        membership_id=install.membership_id,
    )
    return create_session_and_redirect(user)

The SDK fetches Stoa's public key for you and keeps the server-side activation step in place, so the secure flow does not become app boilerplate.

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"}]
)

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_APP_ID	No	-	Your Stoa application ID (required for member registration unless passed explicitly)
STOA_BASE_URL	No	https://api.onstoa.com	Stoa API base URL (for self-hosted or testing)
STOA_REGISTRATION_SECRET	No	-	Registration signing secret for onboarding users from your app

Example .env file

# Required
STOA_API_KEY=stoa_app_xxx
STOA_APP_ID=app_xxx
STOA_REGISTRATION_SECRET=stoa_reg_xxx

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

Documentation

See docs.onstoa.com for full documentation.