Midaz SDK for Go

The Midaz SDK for Go is the idiomatic v4 client for the Midaz financial-ledger APIs. It gives you typed access to every service — Organizations, Ledgers, Accounts, Transactions, and more — with a single surface for authentication, pagination, errors, logging, and observability. It handles the boilerplate so your code stays focused on business logic.

Coming from v2? v4 is a clean major version with breaking changes across authentication, pagination, errors, and service access. There is no deprecation window — you swap your import from /v2 to /v4 and migrate at the same time.See Migrating from v2 before you upgrade.

Getting started

Step 1 – Install Go

Before using the SDK, you must install Go on your machine. v4 declares Go 1.26 in go.mod. The public API also uses iter.Seq2 and log/slog.

Go to the official Go website.

Download the installer for your OS (Windows, macOS, or Linux).

Follow the installation instructions.

Step 2 – Create or use an existing Go project

Create a Go project: To create a Go project, use the following command:

mkdir my-midaz-app
cd my-midaz-app
go mod init my-midaz-app

Use an existing Go project: If you’re working in an existing project, make sure there’s a go.mod file in the root. If not, run the following command to create one:

go mod init your-module-name

Step 3 – Add the Midaz SDK

Inside your project directory, run the following command to pull the v4 SDK and add it to your go.mod and go.sum files:

The module path requires the /v4 suffix. If you omit it, Go will resolve a stale pre-v4 release that is missing every change shipped in this version. Always import github.com/LerianStudio/midaz-sdk-golang/v4.

go get github.com/LerianStudio/midaz-sdk-golang/v4

Using VS Code or GoLand? Your IDE may automatically run go get when you import a new package.

Step 4 – Import the SDK

Create or open a main.go file and add the following content. The example below builds a client against your local Midaz stack with anonymous authentication, lists organizations, then creates a new one.

The example below targets a local Midaz stack with auth disabled. If you don’t have one running yet, see Getting started with Midaz to spin one up before running the snippet.

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/LerianStudio/midaz-sdk-golang/v4"
	"github.com/LerianStudio/midaz-sdk-golang/v4/models"
)

func main() {
	// Build a client. v4 requires exactly one auth source — use
	// midaz.WithAnonymous() for a local stack, or midaz.WithAccessManager(...)
	// for a development or production environment.
	c, err := midaz.New(
		midaz.WithEnvironment(midaz.EnvironmentLocal),
		midaz.WithAnonymous(),
	)
	if err != nil {
		log.Fatalf("midaz.New: %v", err)
	}
	defer c.Shutdown(context.Background())

	ctx := context.Background()

	// List the first 5 organizations using a typed list-opts struct.
	page, err := c.Organizations.ListOrganizations(ctx, models.OrganizationsListOpts{
		PageListOpts: models.PageListOpts{Limit: 5},
	})
	if err != nil {
		log.Fatalf("ListOrganizations: %v", err)
	}

	for _, org := range page.Items {
		fmt.Printf("- %s (%s)\n", org.LegalName, org.ID)
	}

	// Create a new organization. Notice that midaz.CreateOrganizationInput is
	// the same type as models.CreateOrganizationInput — re-exported on the
	// midaz package so most user code only needs one import.
	dba := "Example Inc."
	org, err := c.Organizations.CreateOrganization(ctx, &midaz.CreateOrganizationInput{
		LegalName:       "Example Corporation",
		LegalDocument:   "123456789",
		DoingBusinessAs: &dba, // optional fields are *string — use &local for short literals
		Address: midaz.Address{
			Line1:   "123 Main St",
			City:    "New York",
			State:   "NY",
			ZipCode: "10001",
			Country: "US",
		},
	})
	if err != nil {
		log.Fatalf("CreateOrganization: %v", err)
	}

	fmt.Printf("Organization created: %s\n", org.ID)
}

This gives you access to:

The Midaz client for calling every API service.
Built-in data models (like CreateOrganizationInput).
Auth via Access Manager (production) or Anonymous (local development).
A typed configuration system that fails fast at construction time.

Want to learn more about authentication? Jump to the Authentication section for the full setup.

Step 5 – Run the project

Run the following command:

go run main.go

SDK architecture

The Midaz SDK for Go is built around clarity and predictability. Every service is reachable directly on the client. Every list method follows the same trio shape. Every error is structured. Every option fails fast at construction time.

Layered design

Layer	What it handles
Client	The main entry point — `midaz.New(...)` wires authentication, retries, and observability.
Services	High-level access to each Midaz domain, exposed as promoted fields on the client.
Models	The core data structures that mirror Midaz’s domain logic, re-exported on the `midaz` package.
Utility packages	Modular helpers for config, errors, observability, retries, idempotency, and more.

Services are reached directly on the client — c.Accounts, c.Transactions, c.Organizations. You may still see an embedded Entity field in autocomplete, but new code should use the direct service fields shown in this guide.

Want to dive deeper? Check the architecture guide for the full story behind the rewrite.

Services

The Services layer is your access point to every Midaz domain. Each service handles one resource family and ships every method as part of its single interface — no UseAllAPIs() toggle, no service registration step. Every service is ready to use the moment midaz.New() returns.

Available services

Service	What it does
`c.Organizations`	Manage organizations.
`c.Ledgers`	Create and retrieve ledgers.
`c.Assets`	Define and manage assets.
`c.AssetRates`	Set up and fetch asset exchange rates.
`c.Accounts`	Manage accounts and check balances.
`c.AccountTypes`	Manage account type definitions.
`c.Portfolios`	Group accounts under portfolios.
`c.Segments`	Categorize accounts using segments.
`c.Transactions`	Create and search financial transactions.
`c.TransactionRoutes`	Define and manage transaction routing rules.
`c.Operations`	Drill into the atomic operations inside a transaction.
`c.OperationRoutes`	Define and manage operation routing rules.
`c.Balances`	Get real-time account balances.
`c.Holders`	Manage CRM account holders.
`c.Aliases`	Manage CRM aliases for accounts and entities.
`c.MetadataIndexes`	Manage searchable metadata indexes.

Models

Models reflect how Midaz thinks about finance, with each type tied closely to a real-world business concept. You’ll use them across every service call — from onboarding accounts to recording multi-leg transactions. In v4, the most common model types are re-exported on the midaz package itself. That means midaz.Account and models.Account are the same type, and most code only needs one import.

Common model types

Model	What it represents
`midaz.Organization`	A business entity that owns ledgers and accounts.
`midaz.Ledger`	A collection of accounts and transactions.
`midaz.Asset`	A unit of value (currency, token, etc.) that can be stored or moved.
`midaz.Account`	An account for tracking assets and balances.
`midaz.Portfolio`	A collection of accounts for grouping and management.
`midaz.Segment`	A categorization unit for granular organization.
`midaz.Transaction`	A financial event composed of multiple operations.
`midaz.Operation`	An individual debit or credit entry within a transaction.
`midaz.Balance`	The current state of an account’s holdings.

Need a builder, an internal request shape, or a deprecated type? Import github.com/LerianStudio/midaz-sdk-golang/v4/models directly — every type lives there, and the midaz aliases preserve type identity, so the two import paths interoperate cleanly.

Utility packages

Inside the pkg folder of the SDK, you’ll find utility packages for common dev challenges — config handling, retry policies, and security primitives. They split into two groups. Core packages power cross-cutting SDK concerns. Helper packages provide domain-specific or low-level utilities.

Core packages

Package	What it solves
`auth`	Access Manager OAuth and token lifecycle. Replaces the v2 `access-manager` package.
`config`	Centralized config handling, env overrides, and custom service URLs.
`concurrent`	Tools for batching, rate-limiting, and worker pools.
`errors`	Structured error types, classifiers, and the canonical `Retryable()` predicate.
`observability`	Tracing, metrics, and logs through one OpenTelemetry provider.
`retry`	Retry policy options with exponential backoff and jitter.
`sdkctx`	Per-request context flags — idempotency keys, soft vs hard delete, include-deleted.
`validation`	Input validation with clear, structured error messages.

Helper packages

Package	What it solves
`accounts`	Account-specific helpers and convenience functions.
`conversion`	Type conversion helpers between models and external formats.
`data`	Data utilities and faker helpers for testing and demos.
`format`	Utilities for formatting data the Midaz way (dates, times, etc.).
`generator`	Demo and mass-data generation for end-to-end scenarios.
`integrity`	Checksum and integrity verification utilities.
`performance`	Helpers for tuning bulk operations and high-throughput tasks.
`security`	Security utilities, including SSRF protection and TLS validation.
`stats`	Processing statistics and metrics aggregation.
`transaction`	Transaction-building helpers and fluent builders.
`utils`	General-purpose helpers used across the SDK.
`version`	SDK version metadata and identification.

The v2 pkg/access-manager package has moved to pkg/auth (so the directory matches the package name). The v2 pkg/pagination package was removed — its surface lives in models and on each service today.

Authentication

In v4, the SDK requires exactly one authentication source at construction time. Calling midaz.New(...) with neither returns a typed configuration error — no more silent 401 cascades on the first API call. You have two choices:

midaz.WithAccessManager(...) — production-shape OAuth via the Lerian Access Manager. Recommended for any non-local stack.
midaz.WithAnonymous() — opt out of authentication entirely. Suitable only for a local Midaz stack with auth disabled.

The two options are mutually exclusive.

Production: Access Manager

Plug your Access Manager credentials into midaz.WithAccessManager. The SDK eagerly fetches an initial token at construction time, so misconfigurations surface as configuration errors instead of cascading 401s.

Replace the values in the // Configure Access Manager block with your own credentials before running.

package main

import (
	"context"
	"log"
	"os"

	"github.com/LerianStudio/midaz-sdk-golang/v4"
)

func main() {
	// Configure Access Manager. ClientID and ClientSecret are typically
	// loaded from environment variables — never hardcoded.
	c, err := midaz.New(
		midaz.WithEnvironment(midaz.EnvironmentProduction),
		midaz.WithAccessManager(midaz.AccessManager{
			Address:      "https://auth.midaz.io",
			ClientID:     os.Getenv("MIDAZ_CLIENT_ID"),
			ClientSecret: os.Getenv("MIDAZ_CLIENT_SECRET"),
		}),
	)
	if err != nil {
		log.Fatalf("midaz.New: %v", err)
	}
	defer c.Shutdown(context.Background())

	// Use c.Organizations, c.Ledgers, c.Accounts, ... as usual.
}

The SDK requests a token from your Access Manager, attaches it to every API call, and refreshes it automatically when it expires.

Local development: Anonymous

For a local Midaz stack with auth disabled, opt out explicitly:

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentLocal),
    midaz.WithAnonymous(),
)

Configure via environment variables

You can also point the SDK at your Access Manager via environment variables. Export them in your shell or your process manager:

export PLUGIN_AUTH_ENABLED=true
export PLUGIN_AUTH_ADDRESS=https://your-auth-service.com
export MIDAZ_CLIENT_ID=your-client-id
export MIDAZ_CLIENT_SECRET=your-client-secret

config.FromEnvironment() reads the process environment, not a .env file. If you keep variables in a .env file during development, load them with a library like godotenv before calling config.NewConfig(config.FromEnvironment()).

Then opt in to environment loading at config time:

import "github.com/LerianStudio/midaz-sdk-golang/v4/pkg/config"

cfg, err := config.NewConfig(config.FromEnvironment())
if err != nil {
    log.Fatalf("config: %v", err)
}

c, err := midaz.New(midaz.WithConfig(cfg))

Environment loading is explicit in v4 — config.FromEnvironment() must be in the option chain. The SDK no longer reads env vars implicitly during construction.

Want the full auth walkthrough? Check the Authentication guide in the SDK repo.

Multi-tenancy

Tenant scope comes from the Access Manager / JWT claims used to obtain the token. The SDK applies tenant identity automatically from those claims — no extra configuration on the client side. To run calls under a different tenant scope, use a separate set of Access Manager credentials — or build a second client with its own token context.

Listing and iteration

Every list endpoint in v4 ships in three flavors. Pick the one that matches your use case — they’re consistent across every service.

Method	Returns	Use when
`ListXxx`	`*models.ListResponse[T]` (one page)	You want exactly one page and decide when to advance.
`ListXxxAll`	`iter.Seq2[T, error]`	You want every item; the SDK handles paging internally.
`ListXxxPages`	`iter.Seq2[*ListResponse[T], error]`	You need page-level metadata for checkpointing or batching.

Typed list options

Each list method takes a typed opts struct that embeds one of two base structs depending on how the endpoint paginates:

Pagination shape	Endpoints	Base struct
Page-based	Organizations, Ledgers, Assets, Portfolios, Segments, Accounts, AccountTypes, Balances, Holders, Aliases	`models.PageListOpts{Limit, Page, SortDirection, StartDate, EndDate}`
Cursor-based	Transactions, Operations, OperationRoutes, TransactionRoutes, AssetRates	`models.CursorListOpts{Limit, Cursor, SortDirection, StartDate, EndDate}`

Each endpoint also exposes a typed Filters sub-struct with only the fields that endpoint actually honors. Setting a field on the wrong shape — for example, Page on a cursor endpoint — fails at compile time, not silently at runtime.

Iterate every item with `ListAll`

The most idiomatic shape: a range loop over every item across every page. The SDK advances cursors and fetches pages internally.

import (
    "github.com/LerianStudio/midaz-sdk-golang/v4"
    "github.com/LerianStudio/midaz-sdk-golang/v4/models"
)

opts := models.AccountsListOpts{
    PageListOpts: models.PageListOpts{Limit: 100},
    Filters: models.AccountsFilters{
        Status:    "ACTIVE",
        AssetCode: "USD",
    },
}

for account, err := range c.Accounts.ListAccountsAll(ctx, orgID, ledgerID, opts) {
    if err != nil {
        return fmt.Errorf("list accounts: %w", err)
    }
    process(account)
}

Iterate page envelopes with `ListPages`

When you need page-level metadata — for checkpointing, batching, or stopping mid-page — iterate over ListXxxPages instead. Every entry is a *ListResponse[T] with the full Pagination block attached.

opts := models.TransactionsListOpts{
    CursorListOpts: models.CursorListOpts{Limit: 50},
    Filters:        models.TransactionsFilters{Status: "APPROVED"},
}

for page, err := range c.Transactions.ListTransactionsPages(ctx, orgID, ledgerID, opts) {
    if err != nil {
        return fmt.Errorf("page iter: %w", err)
    }
    log.Printf("page=%d items=%d next_cursor=%q",
        page.Pagination.Page, len(page.Items), page.Pagination.NextCursor)

    for _, tx := range page.Items {
        process(tx)
    }

    if shouldStop(page) {
        break // The SDK aborts in-flight paging cleanly.
    }
}

See the Pagination guide in the SDK repo for HasMore() semantics, NextCursor handling, and the page-vs-cursor decision table.

Error handling

Most errors returned by the SDK service layer are *pkg/errors.Error with structured fields:

Field	What it carries
`Category`	The error class (validation, authentication, network, configuration, and so on).
`Code`	A stable string code suitable for branching or telemetry.
`Operation`	The SDK operation that produced the error (e.g. `Accounts.GetAccount`).
`Resource`	The resource family the error refers to, when relevant.

You can branch with typed predicates, walk fields with errors.As, or use the canonical Retryable() method to drive retry policy.

Branch with typed predicates

The SDK ships with a full set of Is* predicates so you can match errors without poking at internals:

import (
    "errors"
    "fmt"

    sdkerrors "github.com/LerianStudio/midaz-sdk-golang/v4/pkg/errors"
)

acc, err := c.Accounts.GetAccount(ctx, orgID, ledgerID, accountID)
if err != nil {
    switch {
    case sdkerrors.IsNotFoundError(err):
        return fmt.Errorf("account not found: %w", err)
    case sdkerrors.IsAuthError(err):
        // Matches both 401 and 403 — re-authenticate or fix permissions.
        return fmt.Errorf("auth failure: %w", err)
    case sdkerrors.IsValidationError(err):
        return fmt.Errorf("invalid input: %w", err)
    case sdkerrors.IsConflictError(err):
        return fmt.Errorf("already exists: %w", err)
    case sdkerrors.IsRateLimitError(err):
        return fmt.Errorf("rate limited: %w", err)
    case sdkerrors.IsNetworkError(err):
        return fmt.Errorf("transient transport: %w", err)
    case sdkerrors.IsConfigurationError(err):
        return fmt.Errorf("setup mistake: %w", err)
    }

    // Walk the structured fields when you need them.
    var sdkErr *sdkerrors.Error
    if errors.As(err, &sdkErr) {
        log.Printf("op=%s resource=%s code=%s retryable=%v",
            sdkErr.Operation, sdkErr.Resource, sdkErr.Code, sdkErr.Retryable())
    }
}

Drive retry decisions with `Retryable()`

The Error.Retryable() method is the canonical retry-policy source. Use it instead of building your own classification.

var sdkErr *sdkerrors.Error
if errors.As(err, &sdkErr) && sdkErr.Retryable() {
    // Apply your retry logic — backoff, jitter, max attempts, etc.
}

Wrap raw transport errors

If you’re calling lower-level HTTP code outside the SDK and want the same structured error shape, use ClassifyTransportError:

import sdkerrors "github.com/LerianStudio/midaz-sdk-golang/v4/pkg/errors"

resp, err := httpClient.Do(req)
if err != nil {
    return sdkerrors.ClassifyTransportError("PaymentService.Charge", err)
}

Local validation: FieldErrors

Local input validation surfaces *pkg/validation.FieldErrors — a structured collection of per-field complaints from the SDK before any HTTP call. Use errors.As to inspect them when validating user input or builders.

import (
    "errors"
    "fmt"

    "github.com/LerianStudio/midaz-sdk-golang/v4/pkg/validation"
)

var fieldErrs *validation.FieldErrors
if errors.As(err, &fieldErrs) {
    for _, fe := range fieldErrs.Errs() {
        fmt.Printf("- %s: %s\n", fe.Field, fe.Message)
    }
}

Want to dive deeper? Check the Error handling guide in the SDK repo for the full category map, every code, and retry boundary semantics.

Logging

In v4, *slog.Logger is the canonical logger surface. Wire it via midaz.WithLogger(...). The SDK is silent by default — it uses slog.DiscardHandler until you opt in. That means no surprise log lines in your stdout, and no fighting with the SDK over log format. You decide the handler, the level, and the destination.

package main

import (
    "context"
    "log"
    "log/slog"
    "os"

    "github.com/LerianStudio/midaz-sdk-golang/v4"
)

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    }))

    c, err := midaz.New(
        midaz.WithEnvironment(midaz.EnvironmentLocal),
        midaz.WithAnonymous(),
        midaz.WithLogger(logger),
    )
    if err != nil {
        log.Fatalf("midaz.New: %v", err)
    }
    defer c.Shutdown(context.Background())

    // SDK retry diagnostics, slow-call warnings, and other internal
    // log lines now flow through your handler.
}

Need zap, zerolog, or charmbracelet/log? They all integrate as slog.Handler adapters — the SDK doesn’t care which backend produces the records, only that it speaks slog.

Wiring zap, zerolog, or another backend? The Logging guide has adapter recipes for every common logging library.

Observability

OpenTelemetry is first-class in v4. One observability provider gives you spans, metrics, and OTel-correlated logs through a single wiring point. Configure observability either by passing a fully-built provider, or by passing options that the SDK assembles for you.

Wire a provider

package main

import (
    "context"
    "log"

    "github.com/LerianStudio/midaz-sdk-golang/v4"
    "github.com/LerianStudio/midaz-sdk-golang/v4/pkg/observability"
)

func main() {
    ctx := context.Background()

    provider, err := observability.New(ctx,
        observability.WithServiceName("payments-api"),
        observability.WithEnvironment("production"),
        observability.WithComponentEnabled(true, true, true), // tracing, metrics, logs
    )
    if err != nil {
        log.Fatalf("observability.New: %v", err)
    }
    defer provider.Shutdown(ctx)

    c, err := midaz.New(
        midaz.WithEnvironment(midaz.EnvironmentProduction),
        midaz.WithAccessManager(midaz.AccessManager{ /* ... */ }),
        midaz.WithObservabilityProvider(provider),
    )
    if err != nil {
        log.Fatalf("midaz.New: %v", err)
    }
    defer c.Shutdown(ctx)
}

Or pass options inline

import "github.com/LerianStudio/midaz-sdk-golang/v4/pkg/observability"

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentProduction),
    midaz.WithAccessManager(am),
    midaz.WithObservabilityOptions(
        observability.WithServiceName("payments-api"),
        observability.WithComponentEnabled(true, true, true),
    ),
)

The SDK emits one HTTP span per outbound request with proper W3C traceparent propagation. Business log records carry safe IDs only — never payloads, names, addresses, or auth headers. You can also wrap a block of business logic in a span via Client.Trace:

err = c.Trace("create-organization", func(ctx context.Context) error {
    _, err := c.Organizations.CreateOrganization(ctx, input)
    return err
})

WithObservabilityOptions and WithObservabilityProvider use replacement semantics, not merge. Each call replaces any previously installed provider. To start from a baseline, include observability.WithDevelopmentDefaults or observability.WithProductionDefaults as the first option in the chain.

Want to dive deeper? See the 10-observability-otel example in the SDK repo for span attributes, metric names, and exporter setup.

Idempotency

Auto-idempotency is on by default in v4. The SDK emits an X-Idempotency: <uuid> header on every unsafe HTTP request (POST, PUT, PATCH, DELETE). Retries on transient failures then do not double-create resources. You can override the auto-generated key per-call when you need a stable, caller-supplied key — typical for saga steps, outbox rows, or UI-driven submissions.

Set a stable key per request

import "github.com/LerianStudio/midaz-sdk-golang/v4/pkg/sdkctx"

ctx := sdkctx.WithIdempotencyKey(context.Background(), "tx-2026-05-06-001")

tx, err := c.Transactions.CreateTransaction(ctx, orgID, ledgerID, input)

Suppress idempotency for one call

For rare fire-and-forget administrative endpoints, suppress the header per-request:

ctx := sdkctx.WithoutAutoIdempotency(context.Background())

err := c.SomeAdminService.DoOneShotThing(ctx, input)

Disable globally

If you don’t want auto-idempotency anywhere, turn it off at the client level:

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentLocal),
    midaz.WithAnonymous(),
    midaz.WithIdempotency(false),
)

You can also disable it via the MIDAZ_IDEMPOTENCY=false environment variable when using config.FromEnvironment().

Environment variables

You can configure the SDK with environment variables instead of hardcoded values. Environment loading is explicit in v4 — pass config.FromEnvironment() in your config option chain to opt in.

Variable	Description
`MIDAZ_ENVIRONMENT`	Target environment (`local`, `development`, `production`).
`MIDAZ_BASE_URL`	Base URL for all Midaz services, used when the service-specific URLs are not set.
`MIDAZ_LEDGER_URL`	Ledger API URL. It serves the onboarding and transaction endpoints.
`MIDAZ_CRM_URL`	CRM API URL. Holders and Aliases use it.
`PLUGIN_AUTH_ENABLED`	Enable Access Manager authentication (`true` or `false`).
`PLUGIN_AUTH_ADDRESS`	Address of the Access Manager service.
`MIDAZ_CLIENT_ID`	Client ID for Access Manager authentication.
`MIDAZ_CLIENT_SECRET`	Client secret for Access Manager authentication.
`MIDAZ_TIMEOUT`	HTTP request timeout in seconds.
`MIDAZ_DEBUG`	Enable debug logs (`true` or `false`).
`MIDAZ_MAX_RETRIES`	Maximum retry attempts for failed requests. Set `0` to disable retries.
`MIDAZ_IDEMPOTENCY`	Enable automatic idempotency keys for unsafe requests (`true` or `false`).

For the full option matrix across midaz, pkg/config, and pkg/sdkctx, see the Configuration guide in the SDK repo.

Example projects

The SDK ships with a numbered tour of its core capabilities (examples 01–10) plus a set of advanced and reference examples. The numbered set is focused tutorials: each one teaches exactly one concept with the smallest possible body. Browse them in the examples directory on GitHub.

Example	What it demonstrates
`01-hello-world`	Minimal init plus the first API call (~17 body lines).
`02-auth`	Access Manager authentication (production setup).
`03-end-to-end`	Org → ledger → asset → account → transaction.
`04-listing-cursor`	Cursor-based pagination with `iter.Seq2`.
`05-listing-pages`	Page-based pagination — `List` / `ListAll` / `ListPages`.
`06-idempotency`	Auto / explicit / suppressed idempotency modes.
`07-retries`	Default policy, custom policy, disabled retries.
`08-logging-slog`	`*slog.Logger` integration (v4 logging).
`09-testing-with-mocks`	`go.uber.org/mock` for unit testing your code against the SDK.
`10-observability-otel`	Full OpenTelemetry surface (tracing + metrics + logs).

The repository also includes specialized and reference examples — concurrency, configuration, context, tracing, tracing-server, pkg-validation-demo, mass-demo-generator, and workflow-with-entities. They cover advanced patterns (bounded parallelism, OTel context propagation across processes, mass data generation) for when you’ve outgrown the focused set.

Migrating from v2

v4 is a clean-cut major version with no deprecation window. There is no transitional release, no // Deprecated: shim, no backward-compatible alias of the old surface. Swap your import from /v2 to /v4 and walk the breaking changes below. The biggest moves to plan for:

Module path and package name: github.com/LerianStudio/midaz-sdk-golang/v4 (was /v2), package midaz (was client).
Authentication: WithAuthToken is gone. Use WithAccessManager for production or WithAnonymous for local stacks. One auth source is required at construction time.
Service access: c.Accounts.X (was c.Entity.Accounts.X). The c.Entity field still exists for compatibility, but every example uses the short form.
Pagination: models.ListOptions and its 30 fluent setters are gone. Use the typed per-endpoint opts (models.AccountsListOpts, models.TransactionsListOpts, …) and the new ListAll / ListPages iterators.
Errors: *MidazError is gone. Service-layer errors now use *pkg/errors.Error with Retryable() as the official retry source. Local validation may surface *pkg/validation.FieldErrors.
Tenant identity: WithTenantID, the MIDAZ_TENANT_ID env var, and the X-Tenant-ID header are gone. Tenant scope flows through Access Manager / JWT claims.
Logging: *slog.Logger replaces the bespoke observability.Logger interface as the canonical surface. The SDK is silent by default.

For the authentication changes in detail, see the Authentication guide in the SDK repo. The examples directory shows the v4 API in practice.

​Getting started

​Step 1 – Install Go

​Step 2 – Create or use an existing Go project

​Step 3 – Add the Midaz SDK

​Step 4 – Import the SDK

​Step 5 – Run the project

​SDK architecture

​Layered design

​Services

​Available services

​Models

​Common model types

​Utility packages

​Core packages

​Helper packages

​Authentication

​Production: Access Manager

​Local development: Anonymous

​Configure via environment variables

​Multi-tenancy

​Listing and iteration

​Typed list options

​Iterate every item with ListAll

​Iterate page envelopes with ListPages

​Error handling

​Branch with typed predicates

​Drive retry decisions with Retryable()

​Wrap raw transport errors

​Local validation: FieldErrors

​Logging

​Observability

​Wire a provider

​Or pass options inline

​Idempotency

​Set a stable key per request

​Suppress idempotency for one call

​Disable globally

​Environment variables

​Example projects

​Migrating from v2

​Explore the APIs

External API mapping

Internal API mapping

Godoc documentation

Getting started

Step 1 – Install Go

Step 2 – Create or use an existing Go project

Step 3 – Add the Midaz SDK

Step 4 – Import the SDK

Step 5 – Run the project

SDK architecture

Layered design

Services

Available services

Models

Common model types

Utility packages

Core packages

Helper packages

Authentication

Production: Access Manager

Local development: Anonymous

Configure via environment variables

Multi-tenancy

Listing and iteration

Typed list options

Iterate every item with `ListAll`

Iterate page envelopes with `ListPages`

Error handling

Branch with typed predicates

Drive retry decisions with `Retryable()`

Wrap raw transport errors

Local validation: FieldErrors

Logging

Observability

Wire a provider

Or pass options inline

Idempotency

Set a stable key per request

Suppress idempotency for one call

Disable globally

Environment variables

Example projects

Migrating from v2

Explore the APIs