Skip to main content

SDK Overview

The official Vluna SDKs are the default integration path when you want to call Vluna directly from your own backend or application code.

Use the SDKs when you want:

  • a typed client for Vluna APIs
  • built-in request signing and request-context handling
  • a direct integration path without adopting a framework-specific adapter

Available SDKs​

  • Python: vlunaai
  • TypeScript: @vlunaai/sdk

Install​

Python​

pip install vlunaai
  • Package: vlunaai
  • Runtime: Python >= 3.8
  • Registry: PyPI

TypeScript​

npm install @vlunaai/sdk
  • Package: @vlunaai/sdk
  • Runtime: modern browsers and Node.js >= 18
  • Registry: npm

When to use the SDK directly​

The SDK is usually the right choice when:

  • your backend calls Vluna as part of normal application flows
  • you want a direct authorize -> commit/cancel integration
  • you do not need a framework-specific runtime wrapper

When to use adapters instead​

Use the adapter pages when your integration lives inside an LLM or agent runtime such as:

  • OpenAI SDK
  • OpenAI Agents SDK
  • Google ADK
  • LangGraph

Those pages focus on runtime-specific wiring patterns. The SDK page is for the base client libraries themselves.

Choose a language​

  • Python
    • Package: vlunaai
    • Best for Python backends and Python-based agent systems
  • TypeScript
    • Package: @vlunaai/sdk
    • Best for Node.js services, TypeScript backends, and browser-capable integrations

What the SDK gives you​

  • typed request and response models
  • service-to-service and bearer-auth integration paths
  • request-context handling for Realm, principal, user, and account/payor identity
  • a direct client-library path when you do not need a framework-specific adapter

Core concepts​

  • realm_id / realmId
    • Identifies the Realm and is sent on every request.
  • principal_id / principalId
    • Your business identifier for the paying customer, account owner, team, or workspace.
  • user_id / userId
    • Your runtime user identifier under that principal. Runtime gate, wallet, events, limits, and self-report calls require it with principal_id.
  • billing_account_id / billingAccountId
    • Required for account-scoped operations.
  • billing_user_id / billingUserId
    • Internal/admin identifier for the resolved runtime user. It can appear in admin APIs and token issue responses, but it is not the public runtime SDK input.
  • If you are comparing SDK vs runtime-wrapped integration, read: LLM integration guide
  • If you already know your runtime, choose one of the framework pages from: Adapters index