ubank

Access ubank’s API using Python.

Getting started

Install ubank using pip:

pip install ubank

The ubank package provides a script to register a new passkey with ubank:

$ ubank name@domain.com --output passkey.txt
Enter ubank password:
Enter security code sent to 04xxxxx789: 123456

This saves a new passkey to passkey.txt (encrypted with your ubank password). You’ll be prompted for your ubank username and SMS security code interactively.

[!CAUTION] Your passkey grants access to your bank account. It is your responsibility to keep it safe!

Create a script named balances.py:

from getpass import getpass

from ubank import Api, Passkey

# Load passkey from file.
with open("passkey.txt", "rb") as f:
    passkey = Passkey.load(f, password=getpass("Enter ubank password: "))

# Print account balances.
with Api(passkey) as api:
    for account in api.get_accounts().linkedBanks[0].accounts:
        print(
            f"{account.label} ({account.type}): {account.balance.available} {account.balance.currency}"
        )

Run the script to print your account balances:

$ python balances.py
Enter ubank password:
Spend account (TRANSACTION): 765.48 AUD
Savings account (SAVINGS): 1577.17 AUD

Contents

ubank CLI

The ubank module provides a CLI for registering a new passkey:

$ ubank --help
usage: ubank [-h] [-o FILE] [-n PASSKEY_NAME] [-v] username

Returns a new passkey registered with ubank.

positional arguments:
  username              ubank username

options:
  -h, --help            show this help message and exit
  -o, --output FILE     writes encrypted passkey to file (default: write to stdout)
  -n, --passkey-name PASSKEY_NAME
                        sets passkey name (default: ubank.py)
  -v, --verbose         displays httpx INFO logs

You will be asked for your ubank password and secret code interactively. The passkey is encrypted with your ubank password.

ubank API

The ubank.Api class provides a number of methods for accessing ubank’s API:

from datetime import date
from getpass import getpass

from ubank import Api, Passkey, TransactionsSearchBody

with open("passkey.txt", "rb") as f:
    passkey = Passkey.load(f, password=getpass("Enter ubank password: "))

with Api(passkey) as api:
    api.post_accounts_transactions_search(
        body=TransactionsSearchBody(fromDate=date(2025, 1, 1), toDate=date(2025, 2, 1))
    )
    bank = api.get_accounts().linkedBanks[0]
    api.get_account_transactions(
        account_id=bank.accounts[0].id,
        bank_id=bank.bankId,
        customerId=api.get_customer_details().customerId,
    )
    api.get_cards()
    api.get_devices(deviceUuid=passkey.device_id)
    api.get_contacts()

Example web application

notebook.py is a marimo notebook. It demonstrates usage of the API client class to explore ubank’s API.

Open notebook.py in the marimo editor:

uv run marimo edit notebook.py

Run the notebook as a web application:

uv run marimo edit notebook.py

How to set up a development environment

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone this repository:

git clone git@github.com:eidorb/ubank.git
cd ubank

uv ensures Python dependencies compatible with those defined in pyproject.toml are automatically installed:

$ uv run python -c 'import ubank; print(ubank.__version__)'
Using CPython 3.13.2 interpreter at: /opt/homebrew/opt/python@3.13/bin/python3.13
Creating virtual environment at: .venv
Installed 17 packages in 22ms
2.0.0

How to test

Run all tests:

uv run -m pytest -v

How to publish a new release

Bump project version with hatch:

$ uvx hatch version release
Old: 2.0.0rc2
New: 2.0.0

Update test_version test.

Create version tag and push to GitHub:

git tag "v$(uvx hatch version)"
git push origin "v$(uvx hatch version)"

Open new release form for tag:

open "https://github.com/eidorb/ubank/releases/new?tag=v$(uvx hatch version)"

Publishing a release triggers this workflow which builds and publishes the package to PyPI.

If you screw up – delete local and remote tags and have another go:

git tag -d "v$(uvx hatch version)"
git push origin --delete "v$(uvx hatch version)"

Changelog

2.1.0

2.0.0

1.1.0

1.0.0

0.1.2

This site is open source. Improve this page.