TypeScript SDK

The @settlemint/dalp-sdk package gives TypeScript applications typed access to the DALP API. It calls the public REST endpoint at /api/v2, adds DALP authentication headers when you configure them, and serializes DALP numeric and timestamp values before the 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

Have these values ready before you configure 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
• 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

You can omit the API key only for public DALP API routes. Authenticated routes return an authorization error when x-api-key is missing.

Install the package

Install the SDK and its peer validation library with your TypeScript project's 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:

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 only for routes that do not require authentication:

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

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

Without apiKey, requests are sent without x-api-key.

Make your first call

Start by reading the current system address and deployment status before you run asset or identity mutations:

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.tokenAddress);
}

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 can cause the server to deduplicate later mutations as retries of the first one.

For multi-step workflows, create a new one-shot instance per mutation. You can also 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.

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 validation 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

When you only need types for function signatures, import from the /types subpath:

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

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

Use the main package entry when you need runtime exports:

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

Extend the link pipeline

The SDK re-exports optional oRPC plugins for custom link pipelines:

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

Use them only when you need behavior beyond the default OpenAPI link that createDalpClient creates.

Handle errors

The SDK uses oRPC's error model. Errors from DALP routes are instances of ORPCError with a code property. DALP-specific codes are exported as CUSTOM_ERROR_CODES.

import { ORPCError } from "@orpc/client";
import { CUSTOM_ERROR_CODES } from "@settlemint/dalp-sdk";

try {
  await dalp.token.read({ query: { address: "0x0000000000000000000000000000000000000000" } });
} catch (error) {
  if (!(error instanceof ORPCError)) {
    throw error;
  }

  if (error.code === "NOT_FOUND") {
    console.log("Token does not exist");
    return;
  }

  if (error.code === CUSTOM_ERROR_CODES.USER_NOT_AUTHORIZED) {
    console.log("The API key does not allow this operation");
    return;
  }

  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.