> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started with Midaz
> Run Midaz locally, create your first organization, Ledger, accounts, and process your first transaction in under 10 minutes.
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](https://go.dev/dl/) | 1.24+ | `go version` |
| [Docker](https://docs.docker.com/get-docker/) | 24+ | `docker --version` |
| [Docker Compose](https://docs.docker.com/compose/install/) | 2.20+ | `docker compose version` |
| [Make](https://www.gnu.org/software/make/) | 3.81+ | `make --version` |
| [Git](https://git-scm.com/) | 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.
```bash Terminal theme={null}
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:
```bash Terminal theme={null}
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.
```bash Terminal theme={null}
make infra
```
Wait until all containers report a healthy status. You can verify this with:
```bash Terminal theme={null}
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 runs the Onboarding and Transaction services in a single process. This is the simplest option for development and local testing.
```bash Terminal theme={null}
make up UNIFIED=true
```
All APIs are available on **port 3002**.
If you prefer to run each service independently:
```bash Terminal theme={null}
make up
```
| Service | Port |
| ----------- | ---- |
| Onboarding | 3000 |
| Transaction | 3001 |
Verify that the services are running:
```bash Terminal theme={null}
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](/en/reference/midaz/create-an-organization).
```bash Terminal theme={null}
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](/en/reference/midaz/create-a-ledger).
```bash Terminal theme={null}
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](/en/reference/midaz/create-an-asset).
```bash Terminal theme={null}
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](/en/reference/midaz/create-an-account).
Create a source account:
```bash Terminal theme={null}
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:
```bash Terminal theme={null}
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](/en/reference/midaz/create-a-transaction-using-json).
```bash Terminal theme={null}
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](/en/reference/midaz/retrieve-a-balance-by-account-alias).
```bash Terminal theme={null}
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:
```bash Terminal theme={null}
make down
```
To remove containers and volumes and start from a clean environment:
```bash Terminal theme={null}
make clean-docker
```
## Next steps
***
New to Midaz? Start with [Midaz entities](/en/midaz/core-entities) to understand organizations, ledgers, accounts, and transactions.
Learn the different ways to create transactions, including JSON, inflow, and outflow, and when to use each.
Deploy Midaz to Kubernetes using the official Helm chart.
Manage holders and alias accounts to connect real-world identities to your Midaz accounts.
Add Fees Engine, Pix, and other capabilities to your Midaz deployment.