Getting started with the DALP Platform API

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 keys skip wallet verification. Browser sessions still require it on write operations.

API integration model

Create an API key

Step 1: Open the 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, for example Production Integration or CI/CD Pipeline
3. Optionally, set an expiry date. Keys without an 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 in a secret manager, environment variable, or password vault.

Key format: sm_dalp_xxxxxxxxxxxxxxxx

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

Step 4: Review key settings

The key inherits permissions from the user who created it. Check the user's role before using a key for automation. Organisation scope locks to the organisation active at creation time.

Choose read-write access for integrations that create or update DALP resources. Choose read for reporting jobs that call only safe HTTP methods: GET, HEAD, or OPTIONS. Read-only keys reject write methods: POST, PUT, PATCH, and DELETE.

API keys authenticate versioned API requests and carry organizationId and access scope for request context.

Managing API keys

From the API Keys page you can view active keys, including name and expiry date, and delete keys to permanently revoke access.

Configure the SDK

The recommended TypeScript path is the @settlemint/dalp-sdk package. The SDK is generated from the DALP OpenAPI contract, sends authenticated calls to /api/v2, and adds the API key as the X-Api-Key request header.

bun add @settlemint/dalp-sdk zod

Wire amounts as the OpenAPI document declares them (often decimal strings on the wire). See the TypeScript SDK page for scalars and TanStack factories.

Create a client

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

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

Use the deployment origin as baseUrl. Do not append /api. Generated operations call /api/v2. For multi-organisation setups, pass context.organizationId. This pins every request to one organisation:

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

Test your connection

Verify authentication with a safe read before running mutations:

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

const client = createDalpClient({
  baseUrl: "https://your-platform.example.com",
  apiKey: process.env.DALP_API_KEY,
});
const tokens = (await v2TokenList({ client, query: {}, throwOnError: true })).data;

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

This first call confirms the deployment origin is correct, the SDK can reach /api/v2, and the API key is accepted. UNAUTHORIZED means the key value or expiry is wrong. FORBIDDEN means the user role or key scope needs updating.

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/docs on the DALP deployment.

Common errors

For complete error handling guidance, see the Error handling guide. The quick fixes below cover the most common setup errors:

• 401 Unauthorized: the API key is invalid or expired. Confirm the key includes the sm_dalp_ prefix and is enabled on the API Keys page.
• 403 Forbidden: your user account lacks permissions. See Platform setup for role management.
• 403 API_KEY_READ_ONLY: the key has read scope and the request uses a write method. Use read-only keys for GET, HEAD, and OPTIONS calls. Switch to a read-write key for POST, PUT, PATCH, or DELETE requests.
• 404 Not Found: confirm baseUrl is the DALP deployment origin without an /api suffix, and that the deployment is running.

Authentication header formats

DALP accepts API keys in the X-Api-Key header:

X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx

Wallet verification for write operations

The platform uses wallet verification as a second factor for browser sessions. API keys skip this check entirely, so you can omit the walletVerification field:

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

Browser sessions still require wallet verification for write operations. Pass the walletVerification field with the method and code the session established:

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

API keys are scoped credentials for machine-to-machine use. The key itself is the authorization factor; the platform issues no second interactive challenge. Browser sessions require wallet verification to block 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 for operators and agents that need a supported command surface. Use the SDK for TypeScript applications making direct API 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/docs. 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 auth failures, permission errors, validation rejections, and retryable platform faults.

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.