hanzo-treasury

Hanzo Treasury is a programmable financial infrastructure stack providing a double-entry ledger, payment connectors, virtual wallets, reconciliation, and workflow orchestration.

Hanzo Treasury - Programmable Financial Infrastructure

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-payments.md, hanzo/hanzo-commerce.md, hanzo/hanzo-ledger.md

Overview

Hanzo Treasury is a programmable financial infrastructure stack providing a double-entry ledger, payment connectors, virtual wallets, reconciliation, and workflow orchestration. Go monorepo (forked from Formance Stack). Uses Earthly for builds. License: MIT.

Why Hanzo Treasury?

Double-entry ledger: Immutable, programmable source of truth for all financial transactions
Numscript DSL: Domain-specific language for modeling complex monetary flows
50+ payment connectors: Unified API for payment processing across providers
Virtual wallets: Multi-currency with hold/release mechanics
Reconciliation: Auto-match ledger entries against payment provider data
Workflow orchestration: Composable payment and treasury operation flows
Event-driven: JSON Schema-validated events across all services

Tech Stack

Language: Go (module: github.com/formancehq/stack, Go 1.22)
Build: Earthly (v0.8)
Events: Go + Node.js (JSON Schema validation with gojsonschema)
API: OpenAPI 3.0.3 (merged spec from all sub-services)

OSS Base

Repo: hanzoai/treasury (Formance Stack fork). Default branch: main.

When to use

Recording financial transactions with double-entry accounting
Payment routing across multiple providers
Multi-currency virtual wallet management
Reconciling ledger data against external payment sources
Orchestrating multi-step payment workflows
Modeling complex fee splits and fund distributions with Numscript

Hard requirements

Go 1.22+ for building
Earthly for the build system
PostgreSQL for ledger and payment data storage
Docker for running the full stack locally

Quick reference

| Item | Value | |------|-------| | Ledger API | POST /v2/ledger/{name}/transactions | | Accounts API | GET /v2/ledger/{name}/accounts | | Payments API | POST /v2/payments | | Wallets API | POST /v2/wallets | | Reconciliation API | POST /v2/reconciliation/policies | | Local Port | 3068 (ledger) | | License | MIT | | Repo | github.com/hanzoai/treasury |

One-file quickstart

Start local stack

docker compose up -d

Create a ledger transaction

curl -X POST http://localhost:3068/v2/ledger/demo/transactions \
 -H "Content-Type: application/json" \
 -d '{
 "postings": [{
 "source": "world",
 "destination": "users:001",
 "amount": 10000,
 "asset": "USD/2"
 }]
 }'

Numscript example

// Transfer with multi-party fee split
send [USD/2 10000] (
 source = @users:001
 destination = {
 90% to @merchants:042
 10% to {
 50% to @platform:fees
 50% to @platform:reserve
 }
 }
)

Core Concepts

Architecture

hanzo/commerce Storefront, catalog, orders
 |
hanzo/payments Payment routing (50+ processors)
 |
hanzo/treasury Ledger, reconciliation, wallets, flows <-- this repo
 |
lux/treasury On-chain treasury, MPC/KMS wallets

Components

| Component | Description | |-----------|-------------| | Ledger | Programmable double-entry, immutable source of truth | | Payments | Unified API and data layer for payment processing | | Numscript | DSL for modeling monetary computations and flows | | Wallets | Multi-currency virtual wallets with hold/release | | Reconciliation | Auto-match ledger vs. payment provider data | | Flows | Workflow orchestration (via orchestration service) | | Webhooks | Event delivery for financial state changes | | Auth | Authentication and authorization for treasury APIs | | Search | Full-text search across treasury data | | Gateway | API gateway for all treasury services |

Service Versions (from Earthfile)

| Service | Version | |---------|---------| | Ledger | v2.3.1 | | Payments | v3.0.18 | | Wallets | v2.1.5 | | Webhooks | v2.2.0 | | Auth | v2.4.0 | | Search | v2.1.0 | | Orchestration | v2.4.0 | | Reconciliation | v2.2.1 | | Gateway | v2.1.0 |

Event System

Events are JSON Schema-validated. The events/ directory contains:

base.yaml - Common event envelope (type, app, payload)
services/ledger/ - Ledger events (e.g., SAVED_TRANSACTION)
services/payments/ - Payment events (e.g., SAVED_PAYMENT)
services/orchestration/ - Workflow events

Event validation in Go:

import "github.com/formancehq/stack/events"

err := events.Check(data, "payments", "SAVED_PAYMENT")

OpenAPI Specification

The releases/ directory merges OpenAPI specs from all sub-services into a unified API spec:

Auth: /api/auth/*
Ledger: /api/ledger/*
Payments: /api/payments/*
Wallets: /api/wallets/*
Webhooks: /api/webhooks/*
Search: /api/search/*
Orchestration: /api/orchestration/*
Reconciliation: /api/reconciliation/*
Gateway: top-level

Authentication: OAuth2 client credentials (/api/auth/oauth/token).

Directory Structure

treasury/
 README.md # Project overview
 LLM.md # AI agent documentation
 LICENSE # MIT
 go.mod # Root Go module (github.com/formancehq/stack)
 Earthfile # Earthly build (downloads + merges OpenAPI specs)
 base.Dockerfile # Base Docker image
 events/
 base.yaml # Common event envelope schema
 events.go # Go event validation library
 services/
 ledger/ # Ledger event schemas
 payments/ # Payment event schemas
 orchestration/ # Orchestration event schemas
 generated/ # Auto-generated event code
 libs/
 events/
 generated/ # Generated event library
 releases/
 base.yaml # OpenAPI 3.0.3 base spec
 openapi-merge.json # Config for merging all service specs
 openapi-overlay.json # Spec overlays

Integration with Hanzo Stack

hanzo/payments - Payment routing layer (upstream source of payment connectors)
hanzo/commerce - Order settlement and storefront
lux/treasury - On-chain treasury operations, MPC wallet management
hanzo/kms - Secrets and key management

Building

# Build all (OpenAPI spec + events)
earthly +build

# Build just the merged OpenAPI spec
earthly +build-final-spec

# Go tests
go test ./...

Troubleshooting

| Issue | Cause | Solution | |-------|-------|----------| | Earthly build fails | Missing Earthly CLI | Install with brew install earthly | | Event validation fails | Schema version mismatch | Check events/services/ for latest version dir | | API 401 | Missing OAuth token | Get token from /api/auth/oauth/token | | Ledger balance error | Insufficient funds in source | Check account balances via GET /v2/ledger/{name}/accounts |

Related Skills

hanzo/hanzo-payments.md - Payment routing
hanzo/hanzo-commerce.md - E-commerce platform
hanzo/hanzo-ledger.md - Ledger details
hanzo/hanzo-kms.md - Secret management
hanzo/hanzo-sql.md - PostgreSQL backend

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: treasury, ledger, payments, wallets, reconciliation, numscript, fintech Prerequisites: Go 1.22+, Earthly, Docker, PostgreSQL