Quickstart

Start building with Monzoh in under 5 minutes

Installation

First, install Monzoh using your preferred package manager:

pip

pip install monzoh

uv add monzoh

poetry add monzoh

Authentication Setup

Before using Monzoh, you’ll need to set up OAuth2 authentication with Monzo.

1. Create a Monzo Developer Account

1. Visit the Monzo Developer Portal
2. Sign up or log in with your Monzo account
3. Create a new OAuth2 application

2. Configure Your Credentials

Create a .env file in your project root:

MONZO_CLIENT_ID=your_client_id_here
MONZO_CLIENT_SECRET=your_client_secret_here
MONZO_REDIRECT_URI=http://localhost:8080/callback

3. Initial Authentication

Run the authentication command to complete the OAuth2 flow:

monzoh-auth

This will:

1. Open your browser to the Monzo authorization page
2. Start a local server to handle the OAuth2 callback
3. Save your access tokens securely

Access tokens are automatically saved to your system’s cache directory and will be reused for future requests.

Your First API Call

Now you’re ready to make your first API call:

from monzoh import MonzoClient

# Initialize the client
client = MonzoClient()

# Check authentication
whoami = client.whoami()
print(f"Authenticated as: {whoami.user_id}")

# List your accounts
accounts = client.accounts.list()
print(f"Found {len(accounts)} accounts:")

for account in accounts:
    print(f"  {account.description}: {account.id}")

Basic Operations

Get Account Balance

# Get the first account
account = accounts[0]

# Get current balance using OO-style method
balance = account.get_balance()
print(f"Balance: £{balance.balance:.2f}")
print(f"Spend today: £{balance.spend_today:.2f}")

List Recent Transactions

# Get recent transactions using OO-style method
transactions = account.list_transactions(limit=10)

print("Recent transactions:")
for transaction in transactions:
    amount = transaction.amount
    print(f"  {transaction.description}: £{amount:.2f}")

Manage Pots

# List savings pots using OO-style method
pots = account.list_pots()
print(f"Found {len(pots)} pots:")

for pot in pots:
    balance = pot.balance
    print(f"  {pot.name}: £{balance:.2f}")

# Deposit money into a pot using OO-style method
if pots:
    pot = pots[0]
    pot.deposit(10.00)  # £10.00
    print(f"Deposited £10.00 into {pot.name}")

Error Handling

Monzoh provides specific exception types for different error conditions:

from monzoh import (
    MonzoClient,
    MonzoAuthenticationError,
    MonzoRateLimitError,
    MonzoNotFoundError
)

client = MonzoClient()

try:
    accounts = client.accounts.list()
    # Use OO-style methods on account objects
    account = accounts[0]
    balance = account.get_balance()
    transactions = account.list_transactions(limit=5)
except MonzoAuthenticationError:
    print("Authentication failed - please run 'monzoh-auth'")
except MonzoRateLimitError:
    print("Rate limit exceeded - please wait before retrying")
except MonzoNotFoundError:
    print("Resource not found")

Mock Mode for Testing

You can use mock mode for testing without making real API calls:

# Use "test" as the access token to enable mock mode
client = MonzoClient(access_token="test")

# This will return mock data instead of making API calls
accounts = client.accounts.list()
print(f"Mock accounts: {len(accounts)}")

Next Steps

Authentication Guide

Learn about OAuth2 setup and token management

API Reference

Explore all available endpoints and methods

Error Handling

Handle API errors gracefully in your application

Mock Mode

Test your application without real API calls

You’re now ready to build amazing applications with the Monzo API! Check out the API Reference for detailed documentation on all available methods.