hcb 1.0.0

Python wrapper for the HCB v3 API

hcb

hcb is a Python 3.10+ wrapper library for the Hack Club Bank v3 API. It provides typed access to organizations, transactions, cards, donations, and other financial data with both synchronous and asynchronous support.

• Installation
• Usage
  • Basic example
  • Expanding nested objects
  • Asynchronous usage
  • API reference
• License

Installation

hcb is available on PyPI and can be installed with any package manager:

pip install hcb
# or
poetry add hcb
# or
uv add hcb

You can also install it from source:

pip install git+https://github.com/trag1c/hcb.git

Usage

Basic example

import hcb

for txn in hcb.get_organization_transactions("hq"):  # Hack Club HQ
    print(txn.memo, txn.amount_cents)

# or
hq = hcb.get_organization("hq")

for txn in hq.get_transactions():
    print(txn.memo, txn.amount_cents)

Expanding nested objects

By default, related objects like donations, cards, and users are returned as None. Use the expand parameter to fetch them:

# Without expand, nested objects have very little data:
txn = hq.get_transactions()[0]
print(txn.card_charge.date)  # None

# With expand, a lot more donation data is included:
txn = hq.get_transactions(expand="card_charge")[0]
print(txn.card_charge.date)  # 2026-03-22 00:00:00


# Multiple objects can be expanded by separating them with commas:
txn = hq.get_transactions(expand="donation,user,organization")[0]

Asynchronous usage

All functions have async equivalents prefixed with async_:

import asyncio
import hcb


async def main() -> None:
    ghostty = await hcb.async_get_organization("ghostty")
    transactions = await ghostty.async_get_transactions(expand="donation")
    for txn in transactions:
        if donation := txn.donation:
            print(f"Donation: ${donation.amount_cents / 100:.2f}")


asyncio.run(main())

API reference

See core.py.

License

hcb is licensed under the MIT License. © trag1c, 2026