Hanzo Treasury

Overview

Why Hanzo Treasury?

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

Tech Stack

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

OSS Base

When to use

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

Hard requirements

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

Quick reference

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

Service Versions (from Earthfile)

Event System

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

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

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

OpenAPI Specification

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

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

Feedback
hanzo/payments - Payment routing layer (upstream source of payment connectors)
Feedback
hanzo/commerce - Order settlement and storefront
Feedback
lux/treasury - On-chain treasury operations, MPC wallet management
Feedback
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

Related Skills

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