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 [email protected] --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

• Getting started
• Contents
• ubank CLI
• ubank API
• Example web application
• How to set up a development environment
• How to test
• How to publish a new release
• Changelog

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 [email protected]: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/[email protected]/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

• Passkey encrypted with ubank password
• Add API client Api
• Add marimo notebook

2.0.0

• Implement passkey registration and authentication (fixes #6).
• Automate releases.
• Support Python 3.9+.
• Migrate from Poetry to uv.

1.1.0

• Set x-api-version to fix #4 (thanks @jakepronger!)

1.0.0

• Drop Playwright requirement.
• Re-implement with simpler and lightweight httpx libary.
• Easier access to full ubank API.

0.1.2

• Automate ubank access using Playwright headless browser.