Skip to main content

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.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 cyclos-sdk-py 0.2.0
File Size Uploaded Provenance Actions
cyclos_sdk_py-0.2.0.tar.gz 340.1 kB With provenance Details for cyclos_sdk_py-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cyclos-sdk-py 0.2.0
File Interpreter ABI Platform Actions
cyclos_sdk_py-0.2.0-py3-none-any.whl Python 3 none any Details for cyclos_sdk_py-0.2.0-py3-none-any.whl

Total release size: 396.6 kB

Release files / cyclos_sdk_py-0.2.0.tar.gz

Download URL cyclos_sdk_py-0.2.0.tar.gz
Size 340.1 kB
Tags Source
SHA-256 checksum
How to use checksums
3195ccfb390efc46c9b6a159ca8fbbacdf5e4263d2b61008963a1a7d73a412c0
BLAKE2b-256 checksum
How to use checksums
71f500afcc49cd03b009e4e7af71ff4ca8bbabe07e3684007c22fa7dfb569c7b
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 log

Release files / cyclos_sdk_py-0.2.0-py3-none-any.whl

Download URL cyclos_sdk_py-0.2.0-py3-none-any.whl
Size 56.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5e3783ade698e2fb61bc2b46232997f1d6425865a92f8eedfc02747f102830d1
BLAKE2b-256 checksum
How to use checksums
6e4b644bbcc3a8ed933d149b37f0137fc5a03e7a2c1b25f4f82440e18630dd71
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 log

Security for cyclos-sdk-py 0.2.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for cyclos_sdk_py-0.2.0.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 log

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