Getting started with Midaz

In this guide, you will set up a working Midaz environment and go through the core workflow behind any financial application built on the platform: creating an organization, defining a ledger, setting up accounts, and processing your first transaction. By the end, you will have a running ledger system ready to support your use case, whether that is payments, lending, marketplace settlement, or internal treasury management.

Prerequisites

Before you begin, make sure the following tools are installed:

Tool	Minimum version	Check command
Go	1.24+	`go version`
Docker	24+	`docker --version`
Docker Compose	2.20+	`docker compose version`
Make	3.81+	`make --version`
Git	2.30+	`git --version`

Midaz has been tested on macOS (Apple Silicon and Intel) and Linux (amd64). Windows users should run it through WSL2.

Step 1 — Clone the repository

Clone the Midaz repository and move into the project directory.

git clone https://github.com/LerianStudio/midaz.git
cd midaz

Step 2 — Set up environment files

Midaz uses .env files to configure each component. Generate them from the provided examples:

make set-env

This command copies .env.example to .env in each component directory. The default values are ready for local development, so no changes are required.

Step 3 — Start the infrastructure

Start the supporting services required by Midaz: PostgreSQL, MongoDB, Valkey, RabbitMQ, and OpenTelemetry.

make infra

Wait until all containers report a healthy status. You can verify this with:

docker compose -f components/infra/docker-compose.yml ps

Infrastructure services use the following default ports:

Service	Port
PostgreSQL Primary	5701
PostgreSQL Replica	5702
MongoDB	5703
Valkey (Redis)	5704
Grafana (OTEL)	3100
RabbitMQ Management	3003
RabbitMQ AMQP	3004

Step 4 — Start Midaz

You can run Midaz in two modes:

Unified mode (recommended)

Unified mode runs the Onboarding and Transaction services in a single process. This is the simplest option for development and local testing.

make up UNIFIED=true

All APIs are available on port 3002.

Separate services

If you prefer to run each service independently:

make up

Service	Port
Onboarding	3000
Transaction	3001

Verify that the services are running:

curl http://localhost:3002/health

You should receive a 200 OK response.

Step 5 — Create an organization

An organization represents the business entity behind the financial operation: your company, a client, or a regulated institution. In production, this maps to the legal entity under which ledgers, accounts, and transactions are managed.

For the complete endpoint specification, see Create an Organization.

curl -X POST http://localhost:3002/v1/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Acme Corp",
    "legalDocument": "12345678000100",
    "status": {
      "code": "ACTIVE"
    },
    "address": {
      "country": "BR"
    }
  }'

Save the id returned in the response. You will use it in the next steps as {organization_id}.

Step 6 — Create a ledger

A ledger is an isolated book of records within an organization. You can create separate ledgers for different financial domains, such as payments, fee collection, or settlement, each with its own accounts and transaction history.

For the complete endpoint specification, see Create a Ledger.

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary Ledger",
    "status": {
      "code": "ACTIVE"
    }
  }'

Save the returned id as {ledger_id}.

Step 7 — Create an asset

An asset defines the unit of value tracked in the ledger. This can be a fiat currency like BRL or USD, but also loyalty points, crypto tokens, securities, or any custom unit your business needs to move and track. You must create at least one asset before creating accounts.

For the complete endpoint specification, see Create an Asset.

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/assets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brazilian Real",
    "type": "currency",
    "code": "BRL",
    "status": {
      "code": "ACTIVE"
    }
  }'

Step 8 — Create accounts

Accounts represent the participants or buckets in your financial flow: a customer wallet, a revenue pool, a merchant settlement account, or an internal reserve. Each account is linked to a single asset and follows double-entry accounting rules. You need at least two accounts to process a transaction: one to debit (source) and one to credit (destination).

For the complete endpoint specification, see Create an Account.

Create a source account:

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Revenue Account",
    "assetCode": "BRL",
    "type": "deposit",
    "status": {
      "code": "ACTIVE"
    },
    "alias": "@revenue"
  }'

Create a destination account:

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Account",
    "assetCode": "BRL",
    "type": "deposit",
    "status": {
      "code": "ACTIVE"
    },
    "alias": "@customer-001"
  }'

Step 9 — Process your first transaction

This is the core action: moving value between accounts with full traceability. Midaz records every transaction as a balanced operation, debiting the source and crediting the destination so your books stay consistent by design.

For the complete endpoint specification, see Create a Transaction using JSON.

curl -X POST http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/json \
  -H "Content-Type: application/json" \
  -d '{
    "description": "First transaction",
    "send": {
      "asset": "BRL",
      "value": "1000",
      "source": {
        "from": [
          {
            "accountAlias": "@revenue",
            "amount": {
              "asset": "BRL",
              "value": "1000"
            }
          }
        ]
      },
      "distribute": {
        "to": [
          {
            "accountAlias": "@customer-001",
            "amount": {
              "asset": "BRL",
              "value": "1000"
            }
          }
        ]
      }
    }
  }'

This transaction sends R$ 10.00 from @revenue to @customer-001. The value "1000" represents 10.00 in BRL’s smallest unit, cents.Midaz uses integer values to avoid floating-point precision issues, which is a standard practice in financial systems.

Step 10 — Verify the balance

Confirm the transaction was processed by checking the destination account balance.

For the complete endpoint specification, see Retrieve a Balance by Account Alias.

curl http://localhost:3002/v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/alias/@customer-001/balances

The returned balance should reflect the credited amount. At this point, you have a working ledger processing real transactions.

Explore the API

Midaz includes built-in Swagger documentation. Once the services are running, access it at:

Unified mode: http://localhost:3002/swagger/index.html
Onboarding: http://localhost:3000/swagger/index.html
Transaction: http://localhost:3001/swagger/index.html

Observability

Midaz ships with a preconfigured Grafana instance integrated with OpenTelemetry.

Grafana dashboard: http://localhost:3100
Default credentials: midaz / lerian

From Grafana, you can explore logs, traces, and metrics across all Midaz services.

Stopping Midaz

To stop all services:

make down

To remove containers and volumes and start from a clean environment:

make clean-docker

Next steps

Core concepts

Understand the domain model behind organizations, ledgers, accounts, and transactions.

Creating transactions

Learn the different ways to create transactions, including JSON, inflow, and outflow, and when to use each.

Deploy to production

Deploy Midaz to Kubernetes using the official Helm chart.

Extend with plugins

Add CRM, Fees Engine, Pix, and other capabilities to your Midaz deployment.

Getting started

Understanding Midaz

Installing & deploying

Working with Midaz

Best practices

SDKs & libs

Help & support

Getting started with Midaz

Prerequisites

Step 1 — Clone the repository

Step 2 — Set up environment files

Step 3 — Start the infrastructure

Step 4 — Start Midaz

Step 5 — Create an organization

Step 6 — Create a ledger

Step 7 — Create an asset

Step 8 — Create accounts

Step 9 — Process your first transaction

Step 10 — Verify the balance

Explore the API

Observability

Stopping Midaz

Next steps

Core concepts

Creating transactions

Deploy to production

Extend with plugins

Getting started

Understanding Midaz

Installing & deploying

Working with Midaz

Best practices

SDKs & libs

Help & support

​Prerequisites

​Step 1 — Clone the repository

​Step 2 — Set up environment files

​Step 3 — Start the infrastructure

​Step 4 — Start Midaz

​Step 5 — Create an organization

​Step 6 — Create a ledger

​Step 7 — Create an asset

​Step 8 — Create accounts

​Step 9 — Process your first transaction

​Step 10 — Verify the balance

​Explore the API

​Observability

​Stopping Midaz

​Next steps

Core concepts

Creating transactions

Deploy to production

Extend with plugins

Prerequisites

Step 1 — Clone the repository

Step 2 — Set up environment files

Step 3 — Start the infrastructure

Step 4 — Start Midaz

Step 5 — Create an organization

Step 6 — Create a ledger

Step 7 — Create an asset

Step 8 — Create accounts

Step 9 — Process your first transaction

Step 10 — Verify the balance

Explore the API

Observability

Stopping Midaz

Next steps