BunqL — AI-Powered bunq Banking Automation

A full-stack hackathon project that lets you automate bunq banking operations using natural language (Claude AI) and a custom rules language called BunQL.

Stack

Layer	Technology
Frontend	React 18 + TypeScript + Vite + Tailwind CSS
Backend	FastAPI + Python 3.12
Database	PostgreSQL 16
AI	Anthropic Claude (Sonnet 4.6)
Banking	bunq sandbox API
Parser	BunQL — custom DSL built with Lark

---

Prerequisites

• Docker + Docker Compose
• A bunq sandbox API key
• An Anthropic API key
• AWS credentials (for audio transcription — optional)

---

Setup

cd Hackathon7
cp .env.example .env

Edit .env and fill in:

ANTHROPIC_API_KEY=sk-ant-...
BUNQ_API_KEY=sandbox_...
DATABASE_URL=postgresql://bunq:bunqpass@localhost:5432/bunqapp

# Optional — only needed for voice input
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_DEFAULT_REGION=eu-central-1

---

Run with Docker (recommended)

docker-compose up --build

Service	URL
Frontend	http://localhost:5173
Backend API	http://localhost:8000
PostgreSQL	localhost:5433

To stop:

docker-compose down

---

Run Locally (without Docker)

Backend

cd Hackathon7

python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r backend/requirements.txt

cd backend
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

You still need PostgreSQL running. The quickest way is to start just the DB via Docker:

docker-compose up postgres

Frontend

cd Hackathon7/frontend

npm install
npm run dev

Available at http://localhost:5173.

---

Seed Test Accounts

Adds EUR 500 to sandbox test accounts:

cd Hackathon7
python seed_both_users.py

---

Learning the bunq API

Standalone tutorial scripts are in api_examples/hackathon_toolkit/:

cd api_examples/hackathon_toolkit
pip install -r requirements.txt

python 01_authentication.py
python 02_create_monetary_account.py
python 03_make_payment.py
python 04_request_money.py
python 05_create_bunqme_link.py
python 06_list_transactions.py
python 07_setup_callbacks.py

---

Features

• Chat interface — Talk to Claude to trigger bunq actions in natural language
• BunQL scripts — Write constraint/action rules that run automatically against your accounts
• Script registry — Save, edit, and run BunQL scripts from the UI
• Voice input — Record audio commands transcribed via AWS Transcribe
• Sandbox safe — All transactions use the bunq sandbox; no real money involved