Skip to main content

mojowallet

Python SDK for MojoWallet — digital wallet operations, sessions, balance management, and financial ledger tools.

Installation

pip install mojowallet

Requirements: Python 3.10+ | Dependencies: httpx, pyobjict

Quick Start

import mojowallet

client = mojowallet.Client("your-api-key", base_url="https://api.example.com")

wallet = client.Wallet.get(42)
wallet.add_funds(1000, "SC_REAL", source="CREDIT_CARD")
print(wallet.balance("SC_REAL"))

Each Client carries its own credentials, so one process can serve multiple tenants by holding one Client per group.

Since 2.8.0 the client shares ONE pooled keep-alive httpx.Client per Client across threads (bounded: 20 max connections / 10 kept alive), so connections survive across the fresh threads an ASGI server spins up per request. Timeouts split as Client(..., connect_timeout=3, timeout=30) (connect / read). A connect-phase failure OR a reused-connection death is retried exactly once for GET/DELETE and for POSTs whose payload carries a reference_id; read timeouts are never retried. Set the MOJOWALLET_DISABLE_POOL env var to revert to a one-shot per-call request, call client.close() to dispose the pool, and pass on_request_metrics=callable to observe one event per call.

Since 2.6.0 that event carries a stable op label and path_template, both timing views (elapsed_ms = final attempt, total_ms = caller-perceived, including a failed connect), attempts, session_new, the terminal exception's class name, and the server's own Server-Timing breakdown — so one log line on your side splits a slow call into network vs. server work. Wrap calls in mojowallet.correlation(request_id) to tie both halves together. See Request Timing.

Since 2.5.0 a bet/game spend is one call — the server resolves the customer's wallet, checks funds and your cap against the same holdings it draws from, and returns the complete post-spend family snapshot:

data = client.Wallet.spend_by_customer(
    "cust-abc123", 10000, "SC", "bet-round-42", cap_units=25000)
data.replayed, data.split, data.balances

Retrying a committed reference_id returns the original result with replayed=True and moves no money. See Wallet Operations.

All responses support both dict-style (resp["id"]) and attribute-style (resp.id) access.

Core Concepts

Concept Description
Wallet OO wrapper — get a wallet, call actions on it
Sessions Concurrency control for withdrawals (context manager)
Error Handling Exception hierarchy with domain-specific errors

Usage Examples

# Funds (wallet obtained via client.Wallet.get / get_by_customer)
wallet.add_funds(1000, "SC_REAL", source="CREDIT_CARD", category="deposited")
wallet.purchase(500, "SC_REAL", merchant="Coffee Shop")
wallet.cashout(800, "SC_REAL", reference_id="cashout-001")

# Sessions (context manager for safety)
with wallet.session("game-xyz", expires_in_seconds=3600) as session:
    session.withdraw(500, "SC_REAL", reference_id="bet-001")
    session.extend(1800)

# Balances
balance = wallet.balance("SC_REAL")
summary = wallet.balance_summary()

# Reserve flow
wallet.reserve(2500, "SC_REAL", "SC_HOLD", reference_id="payout-001")
wallet.confirm_reservation("payout-001")

# Lock/unlock
wallet.lock(reason="Chargeback")
wallet.unlock(reason="Investigation cleared")

Spending across a currency family

# Walk the SC family in priority order and debit across holdings as needed.
wallet.spend(750, root_code="SC", reference_id="game-bet-001", merchant="Casino")

Balance reads

balance_summary() returns balances grouped by root currency family (root_code), with per-currency totals exposed separately:

s = wallet.balance_summary()
s.balances.SC.available          # 200000
s.balances.SC.by_code.SC_REAL    # {quantity: 150000, formatted: "$1500.00"}
s.total_by_currency.SC_REAL      # per-currency rollup, unchanged from 2.2.x

For per-holding detail or a single family lookup:

holdings   = wallet.get_holdings(root_code="SC")
sc_balance = wallet.get_root_balance("SC")

A whole group's totals by currency and family, with distinct wallet and customer counts, in one read (2.9.0, API 1.0.360+):

data = client.Wallet.holdings_total_by_group(42, expires_within_days="7,30")
data.currencies["SC_REAL"]["total"], data.wallet_count, data.as_of

See docs/wallet.md.

⚠ Breaking change in 2.3.0: balance_summary().balances is now keyed by root_code (was currency_code). Callers reading s.balances["SC_REAL"] must switch to s.total_by_currency["SC_REAL"] or s.balances["SC"].by_code["SC_REAL"].

Error Handling

from mojowallet.exceptions import InsufficientBalanceError, SessionConflictError

try:
    wallet.cashout(10000, "SC_REAL", reference_id="cashout-002")
except InsufficientBalanceError as e:
    print(f"Not enough funds: {e.message}")
except SessionConflictError:
    print("Another session is already active")

Error codes

Wallet errors carry a numeric code (5000-block) and an HTTP status from the table below. The SDK raises a matching subclass whenever the response body includes a code in this range — the dispatch is authoritative regardless of HTTP status.

Code HTTP Class
5001 500 WalletInvariantError
5002 402 InsufficientBalanceError
5003 423 WalletLockedError
5004 423 WalletSuspendedError
5005 423 WalletInactiveError
5006 400 InvalidReferenceError
5007 409 IdempotentReplayError
5008 422 SpendCapExceededError

WalletInvariantError deliberately surfaces only a generic "please retry" message — never the server's diff text — so safety-critical balance-check failures don't leak internal state.

SpendCapExceededError (2.5.0) is not a subclass of InsufficientBalanceError — the wallet could afford the spend and the caller's own cap_units rejected it, so the two need different handling.

Documentation

Development

pip install poetry
poetry install --with dev

# Run all tests (unit tests only — no API key needed)
pytest -v

# With sandbox credentials
cp .env.example .env
# Edit .env with your sandbox API key
pytest -v

License

MIT

Metadata

Release files for mojowallet 2.9.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 mojowallet 2.9.0
File Size Uploaded Provenance Actions
mojowallet-2.9.0.tar.gz 29.1 kB Without provenance Details for mojowallet-2.9.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mojowallet 2.9.0
File Interpreter ABI Platform Actions
mojowallet-2.9.0-py3-none-any.whl Python 3 none any Details for mojowallet-2.9.0-py3-none-any.whl

Total release size: 60.2 kB

Release files / mojowallet-2.9.0.tar.gz

Download URL mojowallet-2.9.0.tar.gz
Size 29.1 kB
Tags Source
SHA-256 checksum
How to use checksums
cee5f9d8fc382f98d2aba6f9bef65ba1730006a530db564f3717b7c1ffb7a20a
BLAKE2b-256 checksum
How to use checksums
57a9d48c222ebdea05a088042e58c873d170339211d254d98460939592dc0f73
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / mojowallet-2.9.0-py3-none-any.whl

Download URL mojowallet-2.9.0-py3-none-any.whl
Size 31.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
407b288dbdebd27ad635d39de425232829b75d1e72c0c91996eccd6c9d0f2090
BLAKE2b-256 checksum
How to use checksums
38ac8bd4163736b256bd76ae1bbc558ac8bad051945b93a4dc7e0b6ea91c7786
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for mojowallet 2.9.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