Skip to main content

TypeScript SDK

A typed, namespaced client for every published v2 route, generated from the platform's declaration, with TanStack Query factories and an Effect surface.

Overview

@settlemint/dalp-sdk is the TypeScript client for the DALP Platform API, the HTTP API a DALP instance serves under /api/v2. Every published v2 route is a typed method on one object: GET /tokens is dalp.api.token.list() and GET /users/me is dalp.api.party.users.me().

The SDK and OpenAPI contract are generated from the same route declaration for a release. Match the SDK version to the deployment version: a newer client can name a route an older deployment does not serve.

One declaration feeds the client, its types, and the CLI.The platform's route declaration is the single source. Generation reads it once and emits two artifacts: a route table carrying each route's path, method, and settlement behaviour, and a type registry keyed by route id carrying each route's request and response types. Three consumers are built from those artifacts rather than maintained by hand: the namespaced promise client a browser or server application calls, the Effect client with the same routes and a typed failure channel, and the command-line interface. Because all three read the same two artifacts, a route the platform adds or changes reaches every one of them through regeneration, and their route definitions match the release used to generate them.One declaration feeds the client, its types, and the CLI.The platform's route declaration is the single source. Generation emits a route table of paths, methods, and settlement behaviour, and a type registry keyed by route id. The promise client, the Effect client, and the command-line interface are all built from those two artifacts, so a route the platform adds reaches every one of them through regeneration.

One declaration, read once, emits the route table and type registry that generate the promise client, the Effect client and the CLI.

The SDK runs in browser, server and React Native applications. A browser or React Native client authenticates with the session cookie and refuses an API key, and a server client authenticates with an API key. It has no framework dependency: React, TanStack Start, Next.js, and a worker all use the same client, and the framework-shaped conveniences are opt-in.

Start with Install and configure. To call the API from another language, or to read the endpoint schemas themselves, use the API reference, which renders every route from the spec. The integration guides cover the header contracts every client shares.

Migrate from SDK 3.1 to 3.2

Move from the 3.1 client to 3.2: route calls, settlement handling and imports.

Install and configure

Install the package, construct a client and pick the credential for your runtime.

Calling routes

How a route call is shaped, what comes back, and how paging and caching work.

Mutations and settlement

Writes: retry safety, on-chain settlement, acting context headers and errors.

Streaming routes

Routes that push a sequence of events instead of returning one body.

TanStack Query

Query and mutation factories, cache keys and invalidation after a write.

Browser apps with user sessions

Keep host-only cookies on your app origin with createDalpProxy.

Server-side rendering

Where the client lives, how the session travels and what to hydrate.

Effect

The same routes, returning Effect values instead of promises.

Settlement, credentials, and caching

A write can resolve before the chain does. dalp.api.token.transfer(...) asks the platform to wait for a bounded time, set through settlementTimeoutMs. The call returns either the settled record or a handle, { transactionId, status, statusUrl }, for an instruction still in progress. A handle is not a failed write, and treating it as one tells a user their transfer was rejected while it is still in flight. Mutations and settlement covers both shapes and how to follow a handle.

The SDK refuses an API key in a browser client. A client whose runtime resolves to browser or react-native throws at construction when it is given a key, rather than at the first request. A key acts as the user it belongs to, in the one organisation it was issued for, up to its read or read-write scope. A key in a browser bundle is readable by every visitor. The check trusts runtime: a client built with runtime: "server", or a call that sets X-Api-Key in its own headers, sends the key wherever the code runs. Install and configure covers which credential belongs where.

Cache keys are derived, not written. queryOptions builds its key from route identity plus canonicalised input, so two callers passing the same parameters in different key order share one cache entry. A hand-written key that differs by one character creates a second entry that never invalidates, and a colliding key makes one entry serve two different requests. TanStack Query covers the key shape and invalidation.

Validation and state

The platform validates every request on the way in and every response on the way out. The SDK checks each JSON and event-stream success response against the route's declared response and throws sdk.response.MALFORMED_SUCCESS on a mismatch. Binary downloads are not checked. The check is strict about enum members, so an SDK older than the platform can throw this error on a value the platform added later. It loads those response schemas on the first call rather than at import, and it does not validate input. Validating user input before you send it stays your choice of library, and the Console's own approach is one worked example.

The SDK is not a state manager. It returns promises and, for the routes that stream, async iterables. The TanStack Query factories are plain objects in the shapes that library expects.

Was this page helpful?