Getting started

This guide walks you through creating an API key in the DALP UI and configuring the OpenAPI TypeScript client for programmatic access to the platform. Within 10 minutes you will authenticate, fetch your user profile, and be ready to deploy tokens.

The DALP API enables you to:

• Automate issuance workflows – Create tokens, assign roles, configure compliance modules, and mint initial supply in one script
• Integrate compliance checks – Verify investor identities, enforce transfer restrictions, and manage allowlists from your own systems
• Build custom dashboards – Query token holders, balances, transaction history, and compliance status for reporting
• Trigger corporate actions – Distribute dividends, process redemptions, adjust yield schedules, and handle maturities programmatically
• Manage multi-token portfolios – Track NAV across fund holdings, rebalance allocations, and reconcile deposits/withdrawals
• Enforce custody controls – Freeze addresses, execute forced transfers, and recover tokens under regulatory or operational requirements

Prerequisites

Before creating an API key:

1. DALP deployment – Have a running DALP instance (local or hosted)
2. DALP account – Sign up through the platform UI with email and password
3. Wallet verification enabled (session-based auth only) – Required for session-cookie authentication; API key auth skips verification automatically
4. Organization membership – Join or create an organization to scope your API operations
5. Admin role (for role grants) – Your account needs admin role to grant system-level permissions

Your API key inherits the permissions of your user account and is scoped to a single organization. If you belong to multiple organizations, create separate API keys for each one.

API integration workflow

This diagram shows the complete flow from prerequisites through authentication to making API calls:

Key steps:

• Generate SDK – Run @hey-api/openapi-ts to create type-safe client from OpenAPI spec
• Initialize client – Configure base URL and API key header once at startup
• Test connection – Verify authentication with userMe() before proceeding
• Read operations – Token lists, holder queries, system info (no verification required)
• Write operations – Minting, role grants, token creation (no wallet verification required when using API key auth)

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 your user role permissions (check with systemAccessManagerRolesList())
• Organization scope: Locked to the organization active when you created the key
• Metadata: Stores organizationId 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 OpenAPI client

The recommended way to interact with the DALP API is through the generated OpenAPI TypeScript client, which provides full type safety and auto-completion for all API endpoints.

Generate the SDK

Use @hey-api/openapi-ts to generate a type-safe client from the OpenAPI specification:

npm install @hey-api/client-fetch
npx @hey-api/openapi-ts -i https://your-platform.example.com/openapi.json -o ./generated -c @hey-api/client-fetch

Or with Bun:

bun add @hey-api/client-fetch
bunx @hey-api/openapi-ts -i https://your-platform.example.com/openapi.json -o ./generated -c @hey-api/client-fetch

This generates three files in ./generated/:

• client.gen.ts – HTTP client configuration
• sdk.gen.ts – Type-safe API functions for each endpoint
• types.gen.ts – TypeScript types for all request/response schemas

Create the client wrapper

Create a client.ts file that wraps the generated SDK with initialization and helper functions:

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

// Create the SDK client — replace with your actual values
const dalp = createDalpClient({
  url: "https://your-platform.example.com",
  apiKey: "sm_dalp_xxxxxxxxxxxxxxxx",
});

// All methods are fully typed with auto-complete
const me = await dalp.user.me({});
console.log("Wallet:", me.data.wallet);

const tokens = await dalp.token.list({ query: {} });
console.log("Tokens:", tokens.data.length);

What this provides:

• initializeClient(baseUrl, apiKey) – One-time setup to configure the base URL and API key header
• SDK functions – All API endpoints as importable functions (e.g., userMe, tokenCreate, tokenMint)
• BigDecimal helpers – toBigDecimal() and fromBigDecimal() for precise numeric values
• Type exports – All TypeScript types for request/response schemas

Initialize the client

import { initializeClient, userMe, tokenList } from "./client";

const platformUrl = "https://your-platform.example.com/api";
const apiKey = "sm_dalp_xxxxxxxxxxxxxxxx"; // From Step 3

// Initialize once at app startup
initializeClient(platformUrl, apiKey);

Replace:

• platformUrl – Your DALP deployment URL + /api path
• apiKey – The key you copied in Step 3

Test your connection

Verify authentication by fetching your user profile:

const meResponse = await userMe();

console.log("User ID:", meResponse.data?.id);
console.log("Email:", meResponse.data?.email);
console.log("Wallet:", meResponse.data?.wallet);
console.log("Organization:", meResponse.data?.organization?.name);

Expected output:

{
  "id": "clxxx...",
  "email": "[email protected]",
  "wallet": "0x1234...",
  "organization": {
    "id": "org_xxx",
    "name": "Acme Corp"
  }
}

If you receive this response, your API key is working correctly.

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 the platformUrl includes /api suffix and your DALP 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 { tokenMint, toBigDecimal } from "./client";

// API key auth — no walletVerification needed
await tokenMint({
  path: { tokenAddress: "0xABCD..." },
  body: {
    recipients: ["0x1234..."],
    amounts: [toBigDecimal("1000", 18)],
  },
});

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

// Session-based auth — walletVerification required
await tokenMint({
  path: { tokenAddress: "0xABCD..." },
  body: {
    recipients: ["0x1234..."],
    amounts: [toBigDecimal("1000", 18)],
    walletVerification: {
      verificationType: "PINCODE",
      secretVerificationCode: "123456", // Your 6-digit PINCODE
    },
  },
});

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

API architecture

The DALP API is built on oRPC, which provides:

• Type-safe client generation – Auto-generated TypeScript clients with full IntelliSense support
• Automatic OpenAPI documentation – Explore endpoints, schemas, and examples at /api/
• Schema validation – Requests and responses validated against Zod schemas
• Custom serializers – BigInt, BigDecimal, and Timestamp types serialized correctly over JSON
• Transaction headers – Blockchain mutations return X-Transaction-Hash in response headers for easy tracking
• Streaming support – Long-running operations return progress updates via server-sent events

All endpoints follow RESTful conventions with POST for mutations, GET for queries, and standardized error codes (401 for auth failures, 403 for permission denials, 404 for missing resources).

Next steps

Now that your client is configured:

1. Review the token lifecycle to understand operation flows
2. Set up roles to grant yourself system and token permissions
3. Choose an asset guide and deploy your first token:
   • Bonds
   • Deposits
   • Equities
   • Funds
   • Stablecoins

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