Getting started

The DALP API is the programmatic entry point for organisation-scoped asset operations. Start here when you need a machine client that can authenticate, call the OpenAPI REST surface, and then route to the right API page for asset lifecycle, compliance, wallet, settlement, monitoring, webhook, or error-handling work.

API keys are organisation credentials. Each key inherits the creating user's DALP permissions, carries a read or read-write scope, and authenticates REST requests with X-Api-Key. Use one key per organisation or environment so reporting jobs, settlement automation, and asset operations do not share the same blast radius.

Choose the right API path

Prerequisites

Before creating an API key:

1. Have a running DALP instance, either hosted or local.
2. Sign in to the platform UI with an account that belongs to the target organisation.
3. Select the organisation that should own the API key. The key stores that organisation context.
4. Confirm your account has the role permissions needed for the operations you plan to call. A read-only key can call safe HTTP methods. Mutations require a read-write key.

API key authentication skips interactive wallet verification. Browser session authentication still requires wallet verification on write operations that ask for it.

API integration model

Create an API key

Step 1: Navigate to API Keys page

1. Click your profile avatar in the top right corner
2. Select API Keys from the dropdown menu

Step 2: Generate a new key

1. Click Create API Key
2. Enter a descriptive name (e.g., "Production Integration", "CI/CD Pipeline")
3. (Optional) Set an expiry date - keys without expiry remain valid until manually revoked
4. Click Create

Step 3: Copy and secure your key

The platform displays your API key once. Copy it immediately and store it securely (environment variable, secret manager, password vault).

Key format: sm_dalp_xxxxxxxxxxxxxxxx

Important: If you lose the key, you cannot recover it. Revoke the old key and create a new one.

Step 4: Review key settings

Your API key has:

• Permissions: Inherits the permissions of the user who created the key. Check the user's role before using a key for automation.
• Organization scope: Locked to the organization active when you created the key
• Access scope: Choose read-write for integrations that create or update DALP resources. Choose read for reporting jobs that only call safe HTTP methods (GET, HEAD, or OPTIONS). Read-only keys cannot use write methods such as POST, PUT, PATCH, or DELETE.
• REST API access: API keys authenticate REST requests. They are not accepted on /api/rpc. Use REST endpoints for API-key based integrations.
• Metadata: Stores organizationId and access scope for session context

Managing API keys

From the API Keys page you can:

• View active keys - Name, expiry date
• Delete keys - Permanently revoke access (cannot be undone)

Configure the SDK

The recommended TypeScript path is the @settlemint/dalp-sdk package. The SDK uses the DALP API contract directly, sends authenticated calls to /api/v2, and adds the API key as the x-api-key request header.

npm install @settlemint/dalp-sdk dnum zod

Or with Bun:

bun add @settlemint/dalp-sdk dnum zod

The SDK requires zod >= 4.0.0. The examples below also use dnum for token amounts, so install both packages explicitly with the SDK.

Create a client

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

const dalp = createDalpClient({
  url: "https://your-platform.example.com",
  apiKey: process.env.DALP_API_KEY,
});

Use the deployment origin as url. Do not append /api; the SDK normalises the base URL and calls the current REST API under /api/v2.

For multi-organisation setups, pass the active organisation explicitly when the integration must pin every request to one organisation:

const dalp = createDalpClient({
  url: "https://your-platform.example.com",
  apiKey: process.env.DALP_API_KEY,
  organizationId: "org_xxx",
});

Test your connection

Verify authentication with a safe read before running mutations:

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

console.log("Token count:", tokens.data.length);

This first call proves that the deployment origin is correct, the SDK can reach /api/v2, and the API key is accepted for the active organisation. If the call fails with UNAUTHORIZED, check the key value and expiry. If the call fails with FORBIDDEN, check the user's role and the key scope.

When to use the OpenAPI specification

Use the SDK for TypeScript services. Use the OpenAPI specification when you need to generate a client in another language, import the API into a gateway, or inspect the REST contract directly.

curl https://your-platform.example.com/api/v2/spec.json \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

The current API specification is served at /api/v2/spec.json. Legacy integrations can still inspect /api/v1/spec.json where required. The interactive reference for the current REST API is available under /api/v2 on the DALP deployment.

Common errors

For complete error handling guidance, see the Error handling guide.

Quick fixes:

• 401 Unauthorized - API key is invalid or expired. Check the key includes the sm_dalp_ prefix and is enabled in the API Keys page.
• 403 Forbidden - Your user account lacks permissions. See Platform setup for role management.
• 404 Not Found - Check that url is the DALP deployment origin without an added /api suffix and that the deployment is running.

Authentication header formats

DALP accepts API keys in following header format:

X-Api-Key (recommended):

X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx

Wallet verification for write operations

When authenticating with an API key, wallet verification is not required. You can omit the walletVerification field entirely:

import { from as dnumFrom } from "dnum";

// API key auth: no walletVerification needed
await dalp.token.mint({
  params: { tokenAddress: "0xABCD..." },
  body: {
    recipients: ["0x1234..."],
    amounts: [dnumFrom("1000", 18)],
  },
});

When authenticating with a session cookie (browser-based), write operations still require wallet verification:

// Session-based auth: walletVerification required
await dalp.token.mint({
  params: { tokenAddress: "0xABCD..." },
  body: {
    recipients: ["0x1234..."],
    amounts: [dnumFrom("1000", 18)],
    walletVerification: {
      verificationType: "PINCODE",
      secretVerificationCode: "123456", // Your 6-digit PINCODE
    },
  },
});

Why the difference? API keys are scoped credentials designed for machine-to-machine use. The key is the authorization factor, so an interactive second challenge is unnecessary. Session-based authentication still requires wallet verification as a second factor to prevent unauthorized transactions from a compromised session.

CLI and AI agent integration

The CLI follows the same authentication model. dalp login opens the browser device flow, creates a read-write API key for the CLI, and stores the credential locally. Use dalp logout when you need to revoke that CLI key and clear the local credential.

For scripts and AI agents, prefer CLI commands that return structured output:

dalp login --url https://your-platform.example.com
dalp whoami --format json
dalp auth org-list --format json

Use the CLI when an operator or agent needs a supported command surface. Use the SDK when your application needs direct TypeScript calls. Use OpenAPI when another language or gateway needs the REST contract. For MCP and skill-file setup, see AI agent integration.

What the SDK and REST surface provide

The DALP SDK creates a typed client over the current REST API at /api/v2. It normalises the deployment origin and sends the API key as x-api-key. The client can also forward an optional x-organization-id and serialise BigInt, decimal, and timestamp values safely for JSON requests.

The REST API exposes the current OpenAPI specification at /api/v2/spec.json and the interactive API reference at /api/v2. Read operations use safe HTTP methods. Mutations use write methods and can return transaction headers when the operation submits an on-chain transaction.

For production integrations, add the request controls that match the job:

• Use organisation and system scope before sharing one service across tenants, environments, or systems.
• Use replay and idempotency controls before retrying write operations.
• Use error handling to distinguish authentication failures, permission failures, validation errors, and retryable platform failures.

Next steps

Now that your client is configured:

1. Review organization and system scope to keep API keys, organizations, systems, and environments separated
2. Review the token lifecycle to understand operation flows
3. Set up roles to grant yourself system and token permissions
4. Choose an asset guide and deploy your first token:
   • Bonds
   • Deposits
   • Equities
   • Funds
   • Stablecoins

For API reference documentation and OpenAPI spec, see API reference.