TypeScript SDK

The @settlemint/dalp-sdk package is generated from the same native HTTP declaration that serves /api/v2 and /api/v2/spec.json. The published package is Effect-free: flat promise operation functions, a per-instance fetch client, zod v4 response validation, and optional TanStack Query factories.

Use the SDK for TypeScript integrations. Use the OpenAPI document when another language or API tool needs a language-neutral contract.

Install

bun add @settlemint/dalp-sdk zod

Add @tanstack/react-query only when you use the React Query factories export.

Create a client

import { createDalpClient } from "@settlemint/dalp-sdk";
import { v2TokenList, v2UserMe } from "@settlemint/dalp-sdk/operations";

const client = createDalpClient({
  baseUrl: "https://dalp.example.com",
  apiKey: process.env.DALP_API_KEY,
  context: { organizationId: "org_01hxy7example" },
});

const me = (await v2UserMe({ client, throwOnError: true })).data;
const tokens = (await v2TokenList({ client, query: {}, throwOnError: true })).data;

createDalpClient builds one generated client instance. Pair it with tree-shakable operation functions from @settlemint/dalp-sdk/operations. Pass throwOnError: true when you want HTTP and validation failures to reject the promise instead of returning an error field.

Configuration

Per-call context overrides instance defaults through headers built with createDalpContextHeaders, or by setting headers on the operation options.

import { createDalpClient, createDalpContextHeaders } from "@settlemint/dalp-sdk";
import { v2TokenCreate } from "@settlemint/dalp-sdk/operations";

const client = createDalpClient({
  baseUrl: "https://dalp.example.com",
  apiKey: process.env.DALP_API_KEY,
  context: { organizationId: "org_01hxy7example" },
});

await v2TokenCreate({
  client,
  body: {
    type: "equity",
    name: "Example Equity",
    symbol: "EXEQ",
    decimals: 18,
    countryCode: "840",
    priceCurrency: "USD",
    basePrice: "10.00",
    class: "COMMON_EQUITY",
    category: "VOTING_COMMON_STOCK",
    uniqueIdentifier: "US0378331005",
    initialModulePairs: [],
    walletVerification: {
      secretVerificationCode: "123456",
      verificationType: "PINCODE",
    },
  },
  headers: createDalpContextHeaders({
    idempotencyKey: crypto.randomUUID(),
  }),
  throwOnError: true,
});

Reuse an idempotency key only for retries of the same logical mutation.

Auth and session cookies

• API key: pass apiKey to createDalpClient on the server or CLI.
• Browser session: create a browser runtime client; the fetch client sends cookies with credentials: "include".
• SSR: pass ssr: { requestHeaders } so the server forwards the inbound cookie to the platform origin only.
• Better Auth actions (sign-in, passkeys, organization membership): use @settlemint/dalp-sdk/auth and createDalpAuthClient.

TanStack Query factories

The package ships factory helpers, not generated React hooks. Spread them into your own hooks:

import { useQuery } from "@tanstack/react-query";
import { createDalpClient } from "@settlemint/dalp-sdk";
import { v2TokenListOptions } from "@settlemint/dalp-sdk/react-query";

const client = createDalpClient({
  baseUrl: "https://dalp.example.com",
  apiKey: process.env.DALP_API_KEY,
});
const options = v2TokenListOptions({ client, query: {} });
const query = useQuery(options);

@tanstack/react-query is an optional peer dependency. Non-React consumers install the package without it.

Bundler and paymaster

createDalpBundlerClient keeps the eight established method names while calling the v2 REST resources. They accept EntryPoint v0.9 viem shapes and return the corresponding typed values.

Direct HTTP callers should use the bundler REST reference.

Errors

Catch DalpSdkError or DalpApiError at a promise boundary. Branch on the stable public error id, status, and retryable fields rather than message text.

import { createDalpClient, isDalpApiError } from "@settlemint/dalp-sdk";
import { v2TokenRead } from "@settlemint/dalp-sdk/operations";

const client = createDalpClient({
  baseUrl: "https://dalp.example.com",
  apiKey: process.env.DALP_API_KEY,
});

try {
  await v2TokenRead({
    client,
    path: { tokenAddress: "0x0000000000000000000000000000000000000000" },
    throwOnError: true,
  });
} catch (error) {
  if (!isDalpApiError(error)) throw error;
  if (error.id === "DALP-0022") {
    console.log("Token does not exist");
  } else {
    throw error;
  }
}

See Error handling for retry and support-diagnostic rules.

Async mutations

Queue-backed writes may return either a synchronous { data } body or an accepted { transactionId, statusUrl } body. Poll with waitForTransaction from @settlemint/dalp-sdk/wait-for-transaction until the transaction reaches a terminal state.

Upgrade notes

The package stays on the 3.x line. The Effect-face client (makeDalpEffectClient, makeDalpApiLayer) is removed. Use createDalpClient and the generated operation functions. Follow the v2 migration guide for route hierarchy and schema fingerprint changes.