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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.