TypeScript SDK

The @settlemint/dalp-sdk package wraps the DALP REST endpoint at /api/v2 with TypeScript types, adds authentication headers when you configure them, and serializes DALP numeric and timestamp values before each request leaves your application.

Use the SDK when you want TypeScript autocomplete for DALP routes without generating an OpenAPI client in your own project. If you need a language-neutral contract or want to generate a client for another runtime, use the API reference instead.

Prerequisites

Gather these values before configuring the SDK.

• a DALP deployment URL, such as https://dalp.example.com
• an API key for authenticated routes, created in the DALP dashboard or provided by a platform administrator

The API key is optional for public-only routes. Authenticated routes return an authorization error when x-api-key is missing.

Also have ready:

• zod >= 4.0.0 installed in the application that imports the SDK
• an organisation ID when the API key can access more than one organisation

Install the package

Install the SDK and its peer dependency zod. The SDK requires zod >= 4.0.0 for request and response validation. Choose the command for your package manager:

npm install @settlemint/dalp-sdk zod

bun add @settlemint/dalp-sdk zod

Create a client

Configure one DALP instance per deployment and authentication scope. Store the API key in an environment variable and pass it at startup:

import { createDalpClient } from "@settlemint/dalp-sdk";

const apiKey = process.env.DALP_API_KEY;
if (!apiKey) {
  throw new Error("Set DALP_API_KEY before creating an authenticated DALP client");
}

const dalp = createDalpClient({
  url: "https://dalp.example.com",
  apiKey,
  organizationId: "org_01hxy7example",
});

The SDK normalizes the base URL and sends requests to /api/v2. It also trims whitespace around apiKey. Empty or whitespace-only API keys raise a configuration error instead of sending an invalid credential.

Public client

Use a public instance for routes that do not require authentication. Omit apiKey and the SDK sends requests without x-api-key:

import { createDalpClient } from "@settlemint/dalp-sdk";

const publicDalp = createDalpClient({
  url: "https://dalp.example.com",
});

Make your first call

Start by reading the current system address and deployment status before you run asset or identity mutations. System addresses are part of your integration configuration. Pair this first call with the organization and system scope checklist when you move between test, production, or multiple customer organizations.

const system = await dalp.system.read({
  params: { systemAddress: "default" },
});

console.log(system.data.id);
console.log(system.data.status);

Then list tokens after authentication is working:

const tokens = await dalp.token.list({ query: {} });

for (const token of tokens.data) {
  console.log(token.name, token.symbol, token.id);
}

Configuration reference

The headers option accepts either Record<string, string> or a callback that returns that shape. Use it for request metadata such as correlation IDs, tenant routing, or custom user-agent details. The callback may be synchronous or asynchronous.

Security headers are applied after default and user headers. User-supplied headers cannot override x-api-key, x-organization-id, or Idempotency-Key when those values are set through the client configuration.

Use idempotency safely

idempotencyKey is a client-wide option. The SDK sends the same key on every request made by that client. Use it for a one-shot mutation client:

const apiKey = process.env.DALP_API_KEY;
if (!apiKey) {
  throw new Error("Set DALP_API_KEY before minting tokens");
}

const dalpForOneMint = createDalpClient({
  url: "https://dalp.example.com",
  apiKey,
  idempotencyKey: "mint-request-2026-05-24-001",
});

await dalpForOneMint.token.mint({
  params: { tokenAddress: "0x1234567890abcdef1234567890abcdef12345678" },
  body: {
    recipients: "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
    amounts: "1000000000000000000000",
  },
});

The mint route accepts amounts in token base units. For an 18-decimal token, "1000000000000000000000" represents 1000 whole tokens. Do not reuse that instance for a sequence of different mutations. Reusing the same idempotency key causes the server to deduplicate later mutations as retries of the first one. For multi-step workflows, create a new one-shot instance per mutation, or inject a fresh header through a custom fetch or headers callback for each operation.

Enable validation during development

Request validation catches malformed input before the SDK sends the request. Response validation checks that the API response still matches the published contract. Both options are off by default and most useful during development or in test environments.

const apiKey = process.env.DALP_API_KEY;
if (!apiKey) {
  throw new Error("Set DALP_API_KEY before enabling SDK validation");
}

const dalp = createDalpClient({
  url: "https://dalp.example.com",
  apiKey,
  requestValidation: true,
  responseValidation: true,
});

Keep both options enabled in tests and integration environments when you want early feedback. In production, decide based on latency and failure-handling requirements for the application that wraps the SDK.

Import types without runtime code

To import only types without pulling in executable code, use the /types subpath. When you need runtime exports such as createDalpClient or error constants, use the main package entry.

import type { DalpClient, DalpClientConfig } from "@settlemint/dalp-sdk/types";

export type DalpClientFactory = (config: DalpClientConfig) => DalpClient;

import { createDalpClient, CUSTOM_ERROR_CODES } from "@settlemint/dalp-sdk";

Extend the link pipeline

The SDK re-exports optional oRPC plugins for custom link pipelines. Use them only when you need behavior beyond the default OpenAPI link that createDalpClient creates:

import { BatchLinkPlugin, RequestValidationPlugin } from "@settlemint/dalp-sdk/plugins";

Handle errors

The SDK wraps DALP route errors in DalpSdkError, which extends oRPC's ORPCError and exposes a code property. DALP-specific codes are exported as CUSTOM_ERROR_CODES.

import { CUSTOM_ERROR_CODES, DalpSdkError } from "@settlemint/dalp-sdk";

try {
  await dalp.token.read({ params: { tokenAddress: "0x0000000000000000000000000000000000000000" } });
} catch (error) {
  if (!(error instanceof DalpSdkError)) {
    throw error;
  }

  if (error.code === "NOT_FOUND") {
    console.log("Token does not exist");
  } else if (error.code === CUSTOM_ERROR_CODES.USER_NOT_AUTHORIZED) {
    console.log("The API key does not allow this operation");
  } else {
    throw error;
  }
}

For the complete list of error codes and handling strategies, see Error handling.

Protect API keys

Do not commit API keys to source control. Load them from your runtime secret manager, environment variables, or deployment platform.

Pass the key to createDalpClient at process start. Rotate it through the same secret-management path used by the application.

Related pages

• API reference: inspect every available API namespace, request schema, and response schema.
• Error handling: map error codes to caller behavior.
• Token lifecycle: follow token creation, minting, transfer, and retirement flows.
• Asset decimals: represent token precision and decimal quantities correctly.