Skip to main content

oasis-privana

Python SDK for Privana - manage deposits, withdrawals, locks, and transfers on the accounting module.

Installation

pip install oasis-privana

Quick Start

import asyncio
from oasis_privana import PrivanaClient, DepositCheckRequest

async def main():
    async with PrivanaClient(base_url="https://api.example.com") as client:
        # Get per-user deposit address
        addr = await client.get_deposit_address()
        print(f"Deposit to: {addr.deposit_address}")

        # After sending tokens to the deposit address, verify the deposit
        result = await client.check_deposit(
            DepositCheckRequest(
                chain_id=84532,
                tx_hash="0xYourTxHash",
                amount=1000000,
            )
        )
        print(f"Deposit status: {result.status}")

asyncio.run(main())

Direct SIWE Private Reads

Private read endpoints such as balances, history, and locked funds use the backend's direct SIWE flow. The Python SDK exposes the raw helpers and token setters rather than a hosted auth-code wrapper. get_history(offset=-1, limit=50) returns one page; non-negative offsets count pages from the oldest entries, negative offsets count from the end, each page is oldest-to-newest, and limit must be between 0 and 100. History entries include lock-lifecycle kinds (modifyLock, unlockLock) and directional transfer kinds (transferFromLockOut/transferFromLockIn, transferBalanceOut/transferBalanceIn). On the outbound (Out) kinds counterparty is the recipient, and on the inbound (In) kinds it is the sender.

import asyncio
from oasis_privana import PrivanaClient

async def main():
    async with PrivanaClient(base_url="https://api.example.com") as client:
        domains = await client.get_siwe_domain()
        nonce = await client.get_siwe_nonce("0xYourAddress")

        # Build and sign the SIWE message in your app, then submit it here.
        login = await client.authenticate_private_reads(
            siwe_message="your signed-in message",
            signature="0xYourSignature",
        )

        balance = await client.get_balance("0xTokenId")
        history = await client.get_history()
        print(domains.domains, nonce.nonce, login.address, balance.balance, history.total)

asyncio.run(main())

EIP-712 Signing

from eth_account import Account
from oasis_privana import (
    sign_lock_message,
    LockNonceResponse,
    SignLockParams,
    LockMessage,
    get_accounting_contract,
    create_lock_expiry,
)

account = Account.from_key("0xYourPrivateKey")

signature = sign_lock_message(
    SignLockParams(
        account=account,
        network="testnet",
        verifying_contract=get_accounting_contract("testnet"),
        message=LockMessage(
            service_address="0xServiceAddress",
            token_id="0xTokenId",
            amount=1000000,
            expiry=create_lock_expiry(60),
            nonce=0,
        ),
    )
)

API Reference

Client

  • PrivanaClient(base_url, timeout=30.0, headers=None) - Main API client
    • get_deposit_address(request=None) - Get per-user deposit address
    • check_deposit(request) - Verify a deposit and trigger credit
    • get_balance(token_id) - Get token balance for the authenticated user
    • get_batch_balances(request) - Get multiple token balances
    • get_history(offset=-1, limit=50) - Get one authenticated history page
    • get_token_info(token_id) - Get token information
    • lock_funds(request) - Lock funds for a service
    • get_lock_nonce(user_address) - Get next create-lock nonce
    • get_modify_lock_nonce(user_address) - Get next modify-lock nonce
    • modify_lock(request) - Modify an existing lock (add funds and/or extend expiry)
    • unlock_funds(request) - Unlock specific lock
    • unlock_all_expired(request) - Unlock all expired locks
    • get_locked_funds(service_address=None) - Get locked funds for the authenticated user
    • get_total_locked_balance(token_id) - Get total locked balance for the authenticated user
    • get_expired_locks() - Get expired locks for the authenticated user
    • transfer_funds(request) - Transfer tokens (requires nonce)
    • get_transfer_nonce(user_address) - Get next transfer nonce
    • transfer_locked_funds(request) - Transfer locked tokens
    • get_transfer_locked_nonce(service_address) - Get next transfer-from-lock nonce
    • request_withdrawal(request) - Request withdrawal
    • get_withdrawal_nonce(user_address) - Get next withdrawal nonce
    • get_pending_withdrawals(user_address) - Get pending withdrawals
    • get_withdrawal_info(index) - Get withdrawal info
    • get_siwe_domain() - Get the SIWE auth domain allow-list
    • get_siwe_nonce(user_address) - Get a SIWE login nonce
    • login_with_siwe(siwe_message, signature) - Exchange a signed SIWE message for tokens
    • authenticate_private_reads(siwe_message, signature) - Login and store X-SIWE-Token
    • set_private_read_token(token) / clear_private_read_token() - Manage X-SIWE-Token
    • set_bearer_token(token) / clear_bearer_token() - Manage bearer auth headers

Signing

  • sign_lock_message(params) - Sign lock message
  • sign_modify_lock_message(params) - Sign modify lock message
  • sign_transfer_message(params) - Sign transfer message
  • sign_transfer_locked_message(params) - Sign transfer locked message
  • sign_withdraw_message(params) - Sign withdrawal message
  • create_lock_expiry(minutes_from_now=60) - Create expiry timestamp

Utilities

  • format_token_amount(amount, decimals=18) - Format wei to human-readable
  • parse_token_amount(amount, decimals=18) - Parse human-readable to wei
  • shorten_address(address, chars=4) - Shorten Ethereum address
  • format_timestamp(timestamp) - Format Unix timestamp to readable string
  • is_expired(expiry) - Check if timestamp is expired
  • format_time_remaining(expiry_timestamp) - Format time remaining
  • format_relative_time(timestamp) - Format relative time (e.g., "5m ago")

License

Apache-2.0

Metadata

Release files for oasis-privana 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for oasis-privana 0.4.0
File Size Uploaded Provenance Actions
oasis_privana-0.4.0.tar.gz 111.4 kB Without provenance Details for oasis_privana-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for oasis-privana 0.4.0
File Interpreter ABI Platform Actions
oasis_privana-0.4.0-py3-none-any.whl Python 3 none any Details for oasis_privana-0.4.0-py3-none-any.whl

Total release size: 140.3 kB

Release files / oasis_privana-0.4.0.tar.gz

Download URL oasis_privana-0.4.0.tar.gz
Size 111.4 kB
Tags Source
SHA-256 checksum
How to use checksums
0c6733382edcbfbd0999a15b414257ecc73e9913ec448f089a5e0f2d07e31f0f
BLAKE2b-256 checksum
How to use checksums
eba9ee96bc542822ba27ea29083e8c69c18fbc094b24dba9a08cc21918d29819
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / oasis_privana-0.4.0-py3-none-any.whl

Download URL oasis_privana-0.4.0-py3-none-any.whl
Size 28.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eafb96656ae2e202e38b013ab90f71cb689e90fae61cc97cf550a01f2de61156
BLAKE2b-256 checksum
How to use checksums
13e6b3309c400f5ebab46cd35f5e3804fa50b2235eaafcadc69f461b175838b4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.15 {"installer":{"name":"uv","version":"0.12.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for oasis-privana 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page