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.

Create a script named balances.py:

from getpass import getpass

from ubank import Client, 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 Client(passkey) as client:
    for account in client.get_linked_banks().linkedBanks[0].accounts:
        print(
            f"{account.label} ({account.type}): {account.balance.available:.2f} {account.balance.currency}"
        )

Run the script to print your account balances:

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

Contents

• Getting started
• Contents
• ubank CLI
• ubank API client
• 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 client

Create an instance of ubank.Client to access ubank's API with typed requests and responses:

from datetime import date
from getpass import getpass

from ubank import Client, Filter, Passkey

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

with Client(passkey) as client:
    client.summarise_transactions(
        body=Filter(fromDate=date(2025, 1, 1), toDate=date(2025, 2, 1))
    )
    bank = client.get_linked_banks().linkedBanks[0]
    client.search_account_transactions(
        account_id=bank.accounts[0].id,
        bank_id=bank.bankId,
        customerId=client.get_customer_details().customerId,
    )
    client.get_cards()
    client.get_devices(deviceUuid=passkey.device_id)
    client.get_contacts()

Use ubank.HttpClient to make arbitrary requests not defined in Client methods. Client.client refers to its underlying HttpClient instance.

If instantiated manually, .authenticate(passkey) must be called:

from ubank import HttpClient

with HttpClient() as http_client:
    # call authenticate with passkey
    http_client.authenticate(passkey)
    response = http_client.get("/api/transactions/transactions", params=dict(limit=5))
    print(response)
    print(response.json())

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

3.0.0

• Rewrite using wre-client-akamai
• Use browser api paths, not mobile
• Upgrade dependencies

2.2.5

• Update dependencies to support Python 3.14

2.2.4

• Generate x-device-meta with dynamic versions (thanks @gdarby70!)

2.2.3

• Define additional Filter fields (thanks @CactiNotch!)

2.2.2

• Fix potentially optional Transaction fields (thanks @CactiNotch!)

2.2.1

• get_linked_banks() returns linked external bank accounts (thanks @CactiNotch!)

2.2.0

• Rework API method and model names to have more meaning

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.