cyclos-sdk-py
Production-grade Python SDK for the Cyclos 4.16 REST API.
Published on PyPI as cyclos-sdk-py, imported as angstrom_cyclos.
Installation
pip install cyclos-sdk-py
For development:
git clone https://github.com/Angstrom-Technologies/cyclos-sdk-py.git
cd cyclos-sdk-py
pip install -e ".[dev]"
Configuration
Set environment variables or pass a CyclosConfig object:
from angstrom_cyclos import CyclosClient, CyclosConfig
config = CyclosConfig(
base_url="https://wallet.angstrom-technologies.ug/uwallet/api",
username="service_client",
password="...",
)
client = CyclosClient(config)
Environment variables
CYCLOS_BASE_URL=https://wallet.angstrom-technologies.ug/uwallet/api
# Preferred for API integrations: token returned by POST /clients/activate
CYCLOS_ACCESS_CLIENT_TOKEN=...
# Used for interactive login, initial access-client activation, or direct
# HTTP Basic authentication when no access-client token is configured.
CYCLOS_USERNAME=service_client
CYCLOS_PASSWORD=...
CYCLOS_TIMEOUT=30
CYCLOS_VERIFY_SSL=true
CYCLOS_MAX_RETRIES=3
CYCLOS_RETRY_BACKOFF=0.5
Authentication
For server-to-server integrations, configure the access-client token returned by
Cyclos POST /clients/activate. The SDK sends it as Access-Client-Token and
does not require a client ID or client secret:
from pydantic import SecretStr
from angstrom_cyclos import CyclosClient, CyclosConfig
config = CyclosConfig(
base_url="https://wallet.angstrom-technologies.ug/uwallet/api",
access_client_token=SecretStr("your-activated-access-client-token"),
)
client = CyclosClient(config)
To activate a client initially, authenticate the user, then exchange the manual activation code. If a prefix is supplied, the SDK prepends it to the returned token before storing and using it:
client.auth.login("customer", "password")
result = client.webservices.activate_client(code="123456", prefix="stable-app-prefix")
# Subsequent requests use the full token in Access-Client-Token.
Session login remains available for interactive workflows:
config = CyclosConfig.from_env()
client = CyclosClient(config)
client.auth.login("customer", "password")
print(client.auth.is_authenticated())
client.auth.logout()
Using Basic authentication directly
If you configure username and password but do not set an
access_client_token, the SDK sends HTTP Basic authentication on every
request automatically. This is useful for admin/service accounts that call
endpoints such as POST /users or POST /system/payments without a
separate login step:
config = CyclosConfig(
base_url="https://wallet.angstrom-technologies.ug/uwallet/api",
username="service_client",
password=SecretStr("..."),
)
client = CyclosClient(config)
# All subsequent requests include Basic auth.
accounts = client.accounts.list("angstromUg")
Creating members
Individual
customer = client.members.create_individual(
username="256772123456",
first_name="John",
last_name="Doe",
email="john@example.com",
mobile="256772123456",
custom_fields={"kycStatus": "VERIFIED"},
)
Merchant
merchant = client.members.create_merchant(
username="merchant001",
name="Merchant One",
email="merchant@example.com",
mobile="256772123456",
group="merchant",
)
Organization
organization = client.organizations.create(
group="corporate",
username="abc_limited",
name="ABC Limited",
custom_fields={"businessRegistrationNumber": "800200012345"},
)
Operators
operator = client.operators.create(
organization_id=organization.user.id,
username="operator001",
first_name="Jane",
last_name="Doe",
)
client.operators.assign_permissions(
organization_id=organization.user.id,
operator_id=operator.user.id,
permissions=["VIEW_MEMBER", "PERFORM_TRANSFER"],
)
Web service client
client.webservices.send_activation_code(
{"mobilePhone": "256772123456"}
)
ws_client = client.webservices.create_client(
name="Angstrom Wallet API",
activation_code="123456",
)
Accounts and balances
accounts = client.accounts.list(member_id="alice")
account = client.accounts.get(member_id="alice", account_type="mobileWallet")
balance = client.accounts.get_balance(member_id="alice", account_type="mobileWallet")
print(balance.balance)
Transfers
from decimal import Decimal
transfer = client.transfers.create(
transfer_type="walletTransfer",
from_account="alice",
to_account="bob",
amount=Decimal("50000"),
currency="UGX",
description="P2P transfer",
idempotency_key="TXN-20260909-000001",
)
Transfer history
history = client.transfers.history(
member_id="alice",
account_type="mobileWallet",
page=0,
page_size=50,
)
Transaction lookup
transaction = client.transactions.get("transaction-id")
Error handling
from angstrom_cyclos import CyclosAuthenticationError, CyclosValidationError, CyclosNotFoundError
try:
client.auth.login("user", "wrong")
except CyclosAuthenticationError as exc:
print(exc.status_code)
except CyclosValidationError as exc:
print(exc.property_errors)
except CyclosNotFoundError as exc:
print(exc.endpoint)
Async usage
import asyncio
from angstrom_cyclos import AsyncCyclosClient, CyclosConfig
async def main() -> None:
config = CyclosConfig.from_env()
async with AsyncCyclosClient(config) as client:
await client.auth.login("user", "pass")
member = await client.members.get("alice")
print(member)
asyncio.run(main())
CLI
cyclos --help
cyclos members get <id>
cyclos members search <query>
cyclos accounts balance <member>
cyclos transfers get <id>
cyclos transfers history <member>
Architecture
Mobile App
|
Web App
|
SMS / USSD
|
Wallet API
|
Angstrom Cyclos SDK <-- this package
|
Cyclos
|
PostgreSQL
This SDK is only an API client. Mobile money integrations (MTN/Airtel) belong in the wallet middleware, not in this package.
Testing
pytest
mypy src
ruff check src
ruff format src
License
MIT License - see LICENSE.
Metadata
Release files for cyclos-sdk-py 0.2.1
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 |
|---|---|---|---|---|
| cyclos_sdk_py-0.2.1.tar.gz | 340.3 kB | With provenance | Details for cyclos_sdk_py-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cyclos_sdk_py-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for cyclos_sdk_py-0.2.1-py3-none-any.whl |
Total release size: 396.8 kB
Release files / cyclos_sdk_py-0.2.1.tar.gz
| Download URL | cyclos_sdk_py-0.2.1.tar.gz |
|---|---|
| Size | 340.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
071a782a7a11482cd5c9f82b03206bdeb6ca5783e0d11177a106e30bef568b73
|
|
BLAKE2b-256 checksum How to use checksums |
f4f490660fc2667d604a59011c642e57f0f1477181b9e6eaf51ad0beff72b939
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / cyclos_sdk_py-0.2.1-py3-none-any.whl
| Download URL | cyclos_sdk_py-0.2.1-py3-none-any.whl |
|---|---|
| Size | 56.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9290f28df9725e8d2894d5f14291e661fb998ddf85673d3cd05eba5db9ff2476
|
|
BLAKE2b-256 checksum How to use checksums |
0b1eafbbd9d536ff372b229b9d301f302c55a7bc3f73383ef558cbc007acdc12
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logSecurity for cyclos-sdk-py 0.2.1
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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for cyclos_sdk_py-0.2.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logA 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.