> ## 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 in about ten minutes: clone the repo, start infrastructure, create your first Organization, Ledger, Accounts, and process a first transaction.
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](https://go.dev/dl/) | 1.26.4+ | `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 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.
```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 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.
```bash Terminal theme={null}
make infra COMMAND=up
```
Wait until all containers report a healthy status. Check their status 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 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:
```bash Terminal theme={null}
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:
```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, it maps to the legal entity that holds your ledgers, accounts, and transactions.
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 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](/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. 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](/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 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](/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: 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](/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 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](/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 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:
```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.