Getting started with Midaz

Run your first Midaz workflow: check your ledger, create your first Organization, Ledger, and Accounts, and process a first transaction.

In this guide, you check a running Midaz ledger. 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 Midaz. Midaz ships as public container images on Docker Hub. See Installing Midaz.

This guide calls the ledger at http://localhost:3002, where 3002 is the default SERVER_PORT. If your ledger runs at another address, use that address instead.

Step 1: Check that Midaz responds

---

Terminal

curl http://localhost:3002/health

You should receive a 200 OK response.

Step 2: 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.

Terminal

curl -X POST http://localhost:3002/v2/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 3: 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.

Terminal

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

Save the returned id as {ledger_id}.

Step 4: 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.

Terminal

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

Step 5: 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.

Midaz created the source account @external/BRL when you created the BRL asset. Create a destination account:

Terminal

curl -X POST http://localhost:3002/v2/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 6: Process your first transaction

---

A transaction 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 the v2 direct model.

Terminal

curl -X POST http://localhost:3002/v2/transactions/direct \
  -H "Content-Type: application/json" \
  -d '{
    "description": "First transaction",
    "asset": "BRL",
    "amount": "1000",
    "debits": [
      {
        "alias": "@external/BRL",
        "organizationId": "{organization_id}",
        "ledgerId": "{ledger_id}",
        "amount": "1000"
      }
    ],
    "credits": [
      {
        "alias": "@customer-001",
        "organizationId": "{organization_id}",
        "ledgerId": "{ledger_id}",
        "amount": "1000"
      }
    ]
  }'

This transaction sends "1000" from @external/BRL to @customer-001. Midaz stores monetary values as decimal strings and does not apply an asset-specific scale.

Your integration defines the display and rounding rules for BRL amounts. Do not parse monetary values as binary floating point.

Step 7: Verify the balance

---

Check the destination account balance to confirm the transaction.

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

Terminal

curl http://localhost:3002/v2/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 on the ledger and restart it. Then access:

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

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 Pix and other capabilities to your Midaz deployment.