Getting started with Midaz

In this guide, you set up a working Midaz environment. You then run the core workflow behind any financial application on the platform. You create an organization, a ledger, and accounts, and then process your first transaction. By the end, you have a running ledger ready for your use case. This can be payments, lending, marketplace settlement, or internal treasury.

Prerequisites

Before you begin, install these tools:

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

Midaz runs on macOS (Apple Silicon and Intel) and Linux (amd64). On Windows, 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 work for local development. You do not need to change them.

Docker must already be running for this step: make set-env also generates the LCRYPTO_* CRM keys through a Docker one-shot container, and fails if Docker is unavailable.

Step 3 — Start the infrastructure

Start the supporting services that Midaz needs: PostgreSQL, MongoDB, Valkey, RabbitMQ, Redpanda, and OpenTelemetry.

make infra COMMAND=up

Wait until all containers report a healthy status. Check their status 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 AMQP	3003
RabbitMQ Management	3004
Redpanda (Kafka API)	19092

Step 4 — Start Midaz

Midaz runs as a single Ledger service that includes the onboarding and transaction domains. Start it with:

make up

This command starts the infrastructure, if needed, runs the ledger migration container, and then starts the Midaz services — the ledger and Tracer. All ledger APIs are available on port 3002. Check that Midaz responds:

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, it maps to the legal entity that holds your ledgers, accounts, and transactions.

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 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 ledger has 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. It can also be loyalty points, crypto tokens, securities, or any custom unit your business tracks. You must create at least one asset before you create 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 account, or an internal reserve. Each account links 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: it moves value between accounts with full traceability. Midaz records every transaction as a balanced operation. It debits the source and credits 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 errors. This is standard practice in financial systems.

Step 10 — Verify the balance

Check the destination account balance to confirm the transaction.

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 that processes real transactions.

Explore the API

Midaz can serve its OpenAPI 3.1 spec and interactive API documentation. The docs surface is off by default. To enable it, set OPENAPI_DOCS_ENABLED=true in components/ledger/.env and restart Midaz. Then access:

API docs: http://localhost:3002/v1/docs
OpenAPI spec: http://localhost:3002/v1/openapi.json (or /v1/openapi.yaml)

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

New to Midaz? Start with Midaz entities to understand 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.

Setting up CRM

Manage holders and alias accounts to connect real-world identities to your Midaz accounts.

Extend with plugins

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

​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

Creating transactions

Deploy to production

Setting up CRM

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