Midaz SDK for TypeScript

The Midaz SDK for TypeScript helps you build financial integrations. It gives you a typed, developer-friendly interface over the Midaz financial services platform. The SDK works with Organizations, Ledgers, Accounts, Transactions, and more. Use it for a simple workflow or for complex operations.

Why use the Midaz SDK for TypeScript?

Type-safe by design: Full TypeScript support with precise type definitions.
Builder pattern: Fluent, readable interfaces to construct complex objects.
Error handling: Clear error signals.
Observability included: Tracing, metrics, and logs, off by default.
Layered architecture: Clean separation between client, entities, API, and models.
Automatic retries: Retries for transient failures.
Concurrency controls: Built-in tools to run tasks in parallel with controlled throughput.
Strict validation: Catch invalid input early with clear error messages.

Getting started

Prerequisite

The Midaz SDK for TypeScript requires Node.js v18.18 to v24 and TypeScript v5.8 or later.

Installing the SDK

Install the Midaz SDK for TypeScript with one of the following commands:

npm install @lerianstudio/midaz-sdk

yarn add @lerianstudio/midaz-sdk

After you install it, follow the Quick Start Guide to learn how to use the SDK.

Authentication

The Midaz SDK for TypeScript authenticates through the Lerian Access Manager (OAuth). For a local stack with authentication disabled, you can build a client without it. You never call a createClient factory. Build a configuration with createClientConfigWithAccessManager() (or createClientConfigBuilder() for a no-auth local stack) and pass it to new MidazClient(config).

Access Manager authentication

To integrate with external identity providers over OAuth:

import { createClientConfigWithAccessManager, MidazClient } from '@lerianstudio/midaz-sdk';

const client = new MidazClient(
  createClientConfigWithAccessManager({
    address: 'https://auth.example.com',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  }).withEnvironment('sandbox')
);

The Access Manager handles tokens for you: acquisition, caching, and renewal. You do not manage tokens manually.

Local development (no authentication)

For a local Midaz stack with authentication disabled, build a client without the Access Manager:

import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk';

const client = new MidazClient(
  createClientConfigBuilder().withBaseUrls({
    onboarding: 'http://localhost:3002',
    transaction: 'http://localhost:3002',
  })
);

We offer an Access Manager plugin that you can use. If you’d like to know more about it, contact us.

Quick start guide

The following sections give practical code examples for the Midaz SDK for TypeScript.

Create a client

The client is your main entry point to the SDK. It handles authentication and gives you access to all entity services. Example:

import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk';

const client = new MidazClient(
  createClientConfigBuilder().withEnvironment('sandbox') // Options: 'development', 'sandbox', 'production'
);

The withEnvironment() presets use example URLs. Set your Midaz address with withBaseUrls() or the MIDAZ_ONBOARDING_URL and MIDAZ_TRANSACTION_URL environment variables. Both URLs point to your Midaz ledger.

Create an Asset

Create assets with the builder pattern and createAssetBuilder. Example:

import { createAssetBuilder } from '@lerianstudio/midaz-sdk';

const assetInput = createAssetBuilder('US Dollar', 'USD')
  .withType('currency')
  .withMetadata({ precision: 2, symbol: '$' })
  .build();

const asset = await client.entities.assets.createAsset('org_123', 'ledger_456', assetInput);

In this code, you add the required name and code fields to the builder const assetInput = createAssetBuilder('US Dollar', 'USD'). Then you add any other properties with with* methods.

Create an Account

Create accounts with the builder pattern and createAccountBuilder. Example:

import { createAccountBuilder } from '@lerianstudio/midaz-sdk';

const accountInput = createAccountBuilder('Savings Account', 'USD', 'savings')
  .withAlias('personal-savings')
  .build();

const account = await client.entities.accounts.createAccount('org_123', 'ledger_456', accountInput);

In this code, you add the required name, assetCode, and account type to the builder const accountInput = createAccountBuilder('Savings Account', 'USD', 'savings'). Then you add any other properties with with* methods.

Create a Transaction

Create transactions with a CreateTransactionInput object and createTransaction. Example:

import type { CreateTransactionInput } from '@lerianstudio/midaz-sdk';

const transactionInput: CreateTransactionInput = {
  code: 'payment_001',
  chartOfAccountsGroupName: 'PAYMENTS',
  description: 'Monthly payment',
  metadata: { purpose: 'Monthly payment' },
  send: {
    asset: 'USD',
    value: '100.00',
    source: {
      from: [{ account: 'source-account-alias', amount: { asset: 'USD', value: '100.00' } }],
    },
    distribute: {
      to: [{ account: 'destination-account-alias', amount: { asset: 'USD', value: '100.00' } }],
    },
  },
};

const transaction = await client.entities.transactions.createTransaction('org_123', 'ledger_456', transactionInput);

In this code, send holds the amount. source.from lists the accounts that send it, and distribute.to lists the accounts that receive it. Each account is an account alias. Amounts are decimal strings.

Clean up resources

await client.destroy();

Using Access Manager for authentication

import { createClientConfigWithAccessManager, MidazClient } from '@lerianstudio/midaz-sdk';

// Initialize the client with Access Manager authentication
const client = new MidazClient(
  createClientConfigWithAccessManager({
    address: 'https://auth.example.com', // Identity provider address
    clientId: 'your-client-id', // OAuth client ID
    clientSecret: 'your-client-secret', // OAuth client secret
    tokenEndpoint: '/v1/login/oauth/access_token', // Optional, this is the default
    refreshThresholdSeconds: 300, // Optional, defaults to 300 (5 minutes)
  })
    .withEnvironment('sandbox')
    .withApiVersion('v1')
);

// The SDK handles token acquisition and renewal
// You can now use the client as normal
const organizations = await client.entities.organizations.listOrganizations();

// Clean up resources when done
await client.destroy();

SDK architecture

The Midaz SDK uses a multi-layered service architecture. It has three layers, shown in Figure 1. Each layer serves a distinct purpose.

Client interface: This is the main entry point for SDK users. It manages configuration such as authentication and environments. It gives access to the entity services through client.entities.
Entity services layer: This layer holds domain-specific services, such as Accounts, Assets, and Transactions. Most services offer create, get, update, delete, and list methods. Some services also add specialized operations for their entity.
Core services layer: All entity services use these foundational utilities. They handle HTTP requests, input validation, error processing, observability, and configuration.

Layered architecture of the Midaz SDK for TypeScript, with the client interface over the entity services layer over the shared core services layer — Figure 1. The layered architecture of the Midaz SDK for TypeScript.

The SDK architecture emphasizes:

Consistency through shared patterns across services.
Scalability via dependency injection and service factories.
Reliability through enhanced error handling and typed responses.
Testability with support for mocking and integration testing.

For more information about the architecture, see the following pages:

Builder pattern

The Midaz SDK for TypeScript uses a builder pattern to help you assemble complex objects in a safe, adaptable way. Instead of a fixed set of inputs, it gives you a step-by-step, fluent, chainable interface. Builder functions in the SDK:

Tell you the parameters in advance.
Let you set optional fields with .with*() methods and chain them.
Hide internal complexity for better readability.

Example

const assetInput = createAssetBuilder('USD Currency', 'USD')
  .withType('currency')
  .withMetadata({ precision: 2 })
  .build();

You can then pass this assetInput to the corresponding create method in the SDK.

For more information, see the Builder Pattern in Midaz SDK page.

Working with entities

Each entity service covers a distinct part of the financial domain, such as accounts, assets, or transactions. These services read and write data for each type of entity. They also offer specialized features for each use case.

Entity	Description
Organizations	Manage business units and organizational data.
Ledgers	Structure and manage financial records.
Assets	Work with assets such as currencies, commodities, and other value units.
Accounts	Create, retrieve, update, and delete accounts within a Ledger.
Segments	Group accounts within a Ledger.
Portfolios	Group accounts into collections.
Balances	Retrieve and update account balances.
Transactions	Create and manage transactions that move assets between accounts.
Operations	Manage atomic debits and credits that make up a transaction.

You access each service through the SDK client. They follow a consistent structure, so you build and maintain financial features more easily.

For more information, see the Entities pages.

Using utilities

The SDK provides utility modules for common operations: performance, error handling, configuration, and observability.

Utility	Description
Account Helpers	Simplifies common account-related logic and transformations.
Concurrency	Helps coordinate and limit concurrent tasks safely and efficiently.
Config	Centralized configuration setup and access.
Data	Assists with data formatting and pagination tasks.
Error Handling	Offers error processing mechanisms.
HTTP Client	Provides a low-level HTTP interface for direct API calls.
Network	Adds high-level networking features like retries and backoff.
Observability	Captures traces, metrics, and logs to support monitoring and debugging.
Pagination	Handles paginated responses with predictable, consistent helpers.
Validation	Validates input and output data to help maintain data integrity.

For more information, see the Utilities pages.

Error handling

The Midaz SDK for TypeScript helps you handle errors clearly and consistently. When an SDK operation fails, the SDK throws an error. An API error response throws an HttpError with these fields:

status: The HTTP status code.
statusText: The HTTP status text.
response: The error body from Midaz.

Invalid input throws a ValidationError before the request. Use processError() to read both types in one shape. Handle an error like this:

import { processError } from '@lerianstudio/midaz-sdk';

try {
  await client.entities.transactions.createTransaction('org_123', 'ledger_456', transactionInput);
} catch (err) {
  const info = processError(err);
  console.error(`Error (${info.statusCode}): ${info.message}`);
}

Best practices

Validate input before you call SDK methods.
Check your auth when you get status 401 or 403.
Retry on transient issues like status 500 or 503.
Use statusCode and message to show debug info in development logs.

CI/CD pipeline

We use GitHub Actions for automated, production-ready builds:

Runs tests across multiple Node.js versions.
Enforces code quality with ESLint and Prettier.
Keeps dependencies up to date with Dependabot.
Handles releases automatically with semantic versioning.
Generates changelogs.

Want to contribute?

To contribute to the Midaz SDK for TypeScript, start with our contributing guide on GitHub.

License

This project is licensed under the Apache License 2.0. For details, see the License page.

Midaz Core

CRM

Fees

Midaz SDK for TypeScript

Why use the Midaz SDK for TypeScript?

Getting started

Prerequisite

Installing the SDK

Authentication

Access Manager authentication

Local development (no authentication)

Quick start guide

Create a client

Create an Asset

Create an Account

Create a Transaction

Clean up resources

Using Access Manager for authentication

SDK architecture

Builder pattern

Example

Working with entities

Using utilities

Error handling

Best practices

CI/CD pipeline

Want to contribute?

License

​Why use the Midaz SDK for TypeScript?

​Getting started

​Prerequisite

​Installing the SDK

​Authentication

​Access Manager authentication

​Local development (no authentication)

​Quick start guide

​Create a client

​Create an Asset

​Create an Account

​Create a Transaction

​Clean up resources

​Using Access Manager for authentication

​SDK architecture

​Builder pattern

​Example

​Working with entities

​Using utilities

​Error handling

​Best practices

​CI/CD pipeline

​Want to contribute?

​License

Why use the Midaz SDK for TypeScript?

Getting started

Prerequisite

Installing the SDK

Authentication

Access Manager authentication

Local development (no authentication)

Quick start guide

Create a client

Create an Asset

Create an Account

Create a Transaction

Clean up resources

Using Access Manager for authentication

SDK architecture

Builder pattern

Example

Working with entities

Using utilities

Error handling

Best practices

CI/CD pipeline

Want to contribute?

License