API reference

DALP serves versioned OpenAPI 3.x specifications for the REST API. Use /api/v2/spec.json for new integrations, SDK generation, Postman, Insomnia, and read-only API documentation. Use /api/v1/spec.json only when you maintain an existing integration on that route family.

OpenAPI specification endpoints

DALP exposes a versioned interactive API explorer and a versioned OpenAPI JSON file. Use the JSON endpoint when you generate clients, import the API into Postman or Insomnia, or preview the contract with tools such as Redoc.

Choose /api/v2/spec.json for new integrations. Use /api/v1/spec.json only when you maintain a v1 client.

The JSON endpoint returns a document conforming to the OpenAPI 3.x specification. The spec includes:

• endpoint definitions for the selected API version
• request schemas with parameter types, validation rules, and required fields
• response schemas for successful responses and error codes
• authentication through the X-Api-Key header
• shared headers such as Idempotency-Key, Prefer, X-Transaction-Speed, X-Participant, and X-Executor

DALP serves the explorer HTML separately from the OpenAPI JSON. The explorer at /api/v2 loads a local Scalar bundle, then fetches /api/v2/spec.json asynchronously. The JSON endpoint can also return cached and precompressed responses when the client sends Accept-Encoding: br or Accept-Encoding: gzip; use the same /api/v2/spec.json URL in tools, and the server selects the response encoding.

Viewing the specification

Open the current explorer in your browser:

Fetch the JSON specification for code generators and API tools:

curl https://your-platform.example.com/api/v2/spec.json | jq '.info.title, .info.version'

Import the versioned OpenAPI JSON URL to auto-generate a collection with all endpoints configured.

Authentication

All API requests require authentication, either via an API key in the X-Api-Key header or a session cookie. When using session-based (cookie) authentication, sensitive operations that trigger blockchain transactions also require wallet verification. When using API key authentication, wallet verification is skipped automatically, so the walletVerification field can be omitted.

Use the optional X-Participant and X-Executor headers only when a request must select the acting participant or execution wallet explicitly. For values, defaults, route applicability, and validation errors, see Request headers.

DALP validates request-header participant and executor selection before queueing a blockchain operation. Remove the headers to fall back to automatic selection, or retry after the selected wallet configuration is available and indexed.

See Getting started for API key creation and client configuration. See Request headers for participant and executor selection. See Smart wallet API overview for smart wallet discovery, signer management, and multisig approvals. See Events when an integration needs webhook payload schemas, lifecycle states, or replay-safe reconciliation after a write request. See UserOperations for the smart-account request model behind account abstraction execution.

Response headers

Transaction hash header

Mutation operations that submit blockchain transactions return the transaction hash in the X-Transaction-Hash response header.

The API automatically waits for transaction confirmation, so you typically don't need this header. However, if you receive a CONFIRMATION_TIMEOUT error, use the hash to check whether the transaction eventually succeeded before retrying.

See Transaction tracking for timeout recovery patterns.

API namespaces

The API is organized into logical namespaces, each containing related procedures:

Each namespace maps to versioned HTTP routes. For example, v2 token operations use routes under /api/v2/tokens.

Bundler JSON-RPC endpoint

The account abstraction bundler endpoint is exposed separately from the OpenAPI procedure namespaces because ERC-4337 wallets call it as JSON-RPC 2.0. See Bundlers for the concept model.

Send the method name in the JSON-RPC method field. eth_chainId returns the active chain ID as a hexadecimal string. eth_supportedEntryPoints returns an array containing the EntryPoint address registered for the active network after directory and indexer resolution.

curl -X POST "$DALP_API_URL/api/v2/bundler" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_supportedEntryPoints","params":[]}'

Requests without an id are treated as JSON-RPC notifications and return 204 No Content, including unsupported ERC-4337 method names. Unsupported methods return a JSON-RPC method not found response only when the request includes an id.

For paymaster funding, sponsorship settings, and signer-key rotation, use System paymasters and Paymasters and gas sponsorship.

Exchange-rate operations

Use the exchangeRates namespace when an integration needs current or historical fiat rates for multi-currency assets.

baseCurrency and quoteCurrency use ISO 4217 alpha-3 currency codes such as USD and EUR. The list response includes baseCurrency, quoteCurrency, rate, effectiveAt, updatedAt, and feedAddress; rate and timestamps can be null when a feed exists but has not observed a value yet.

Use GET /api/v2/exchange-rates/supported-currencies before presenting currency choices for onboarding, platform settings, or payment-currency configuration.

The response returns the configured exchange-rate provider key and a sorted list of supported currency codes:

{
  "data": {
    "providerKey": "open-er-api",
    "currencies": ["AED", "EUR", "USD"]
  },
  "links": {
    "self": "/v2/exchange-rates/supported-currencies"
  }
}

The list reflects the provider's current supported-currency snapshot. DALP caches the response for fast reads.

If a later configuration request rejects a currency as unsupported, refresh choices from this endpoint before retrying.

For the product workflow behind these choices, see Exchange-rate target currencies. For CLI equivalents, see Exchange rate commands. For the feed architecture behind the API, see Feeds system.

Organization deployment stream

The organization.deployStream operation exposes deployment progress as a server-sent event stream for the active organization.

The deploymentId is scoped to the caller's active organization. A caller can subscribe only to the deployment stream for that organization. A missing organization context or a deploymentId from another organization returns a not-found shaped error before the stream starts, so clients should treat it the same way as an unavailable deployment.

The stream emits events in this order:

A successful or failed complete event closes the stream. A terminal stream error also yields one error event and closes the stream. For failed deployments, read complete.failedSteps[].wireError when present; it uses the same public contract-error fields documented in Error handling.

Reconnect only when the terminal payload is retryable or when the user restarts the deployment workflow. Do not keep polling after complete or error.

Fixed yield schedule operations

The addons.fixedYield namespace exposes the fixed yield schedule lifecycle:

Create requests include the token address, yield rate in basis points, payment interval, future start and end times, and the ISO 3166-1 numeric country code. topUp and withdraw also include the amount and linked token address; withdraw includes the recipient address.

For CLI examples and funding notes, see Fixed yield schedule commands and Configure yield schedules.

User statistics data sources

User statistics endpoints (user.stats, user.statsUserCount, user.statsGrowthOverTime) report counts based on organization membership data in the DALP database. Recent activity is derived from each member's most recent login timestamp, falling back to their created date when login history is unavailable.

TypeScript SDK

Use @settlemint/dalp-sdk for TypeScript services that call DALP directly. The packaged SDK provides typed route namespaces, SDK-managed x-api-key headers, and serializers for DALP numeric and timestamp values.

See Getting started for SDK setup and client configuration.

Using with API tools

Interactive explorer

The interactive explorer serves the selected API version:

1. Open /api/v2 in your browser, for example https://your-platform.example.com/api/v2.
2. Expand endpoint groups to inspect request schemas and response examples.
3. Use the explorer for quick checks, then build production clients from /api/v2/spec.json.

The explorer is useful for manual inspection. For automated checks, CI imports, generated clients, and large-spec troubleshooting, fetch /api/v2/spec.json directly. Use a tool that sends Accept-Encoding: br or Accept-Encoding: gzip. If a browser tab fails while rendering the explorer, verify the JSON endpoint first:

curl -L --compressed https://your-platform.example.com/api/v2/spec.json \
  | jq '.openapi, .info.title, (.paths | length)'

A successful JSON response means the route contract is available even if the browser renderer needs a refresh or another viewing tool. Use Redoc, Postman, Insomnia, or a local file preview when you need a read-only contract view outside the live explorer.

Redoc

For a cleaner, read-only documentation view:

1. Download the OpenAPI spec: curl https://your-platform.example.com/api/v2/spec.json > openapi.json.
2. Serve with Redoc:

   npx @redocly/cli preview-docs openapi.json

3. Open http://localhost:8080 in your browser.

Postman

Import the OpenAPI spec into Postman:

1. Click Import in Postman.
2. Select the Link tab.
3. Paste https://your-platform.example.com/api/v2/spec.json.
4. Click Continue and then Import.
5. Configure the collection's authorization with your API key:
   • Auth Type: API Key
   • Key: X-Api-Key
   • Value: sm_dalp_xxxxxxxxxxxxxxxx
   • Add to: Header

Insomnia

Import the OpenAPI spec into Insomnia:

1. Click Create and then Import.
2. Paste https://your-platform.example.com/api/v2/spec.json.
3. Click Scan and then Import.
4. Add an environment variable for the X-Api-Key header.

curl examples

Use the OpenAPI specification as the route contract before copying curl examples into integration code:

curl https://your-platform.example.com/api/v2/spec.json \
  | jq '.paths | keys[]' \
  | head

For authenticated calls, send the API key in the X-Api-Key header and the request body defined by the operation schema:

curl -X GET https://your-platform.example.com/api/v2/exchange-rates/supported-currencies \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx" \
  -H "Accept: application/json"

For mutation routes that submit blockchain transactions, API-key authentication does not require a walletVerification field. Session-cookie authentication requires wallet verification on sensitive operations.

Generating client SDKs

Use the OpenAPI spec to generate clients for languages beyond TypeScript.

Python (openapi-generator)

openapi-generator-cli generate \
  -i https://your-platform.example.com/api/v2/spec.json \
  -g python \
  -o ./dalp-python-client

Go

openapi-generator-cli generate \
  -i https://your-platform.example.com/api/v2/spec.json \
  -g go \
  -o ./dalp-go-client

C# / .NET

openapi-generator-cli generate \
  -i https://your-platform.example.com/api/v2/spec.json \
  -g csharp-netcore \
  -o ./dalp-csharp-client

Java

openapi-generator-cli generate \
  -i https://your-platform.example.com/api/v2/spec.json \
  -g java \
  -o ./dalp-java-client

Generated clients can require manual adjustments for BigInt and BigDecimal serialization. The TypeScript SDK includes toBigDecimal() and fromBigDecimal() helpers for this purpose.

Error handling

The API returns standardized HTTP status codes and machine-readable error codes. Errors include detailed messages and contextual data to help diagnose issues.

See Error handling for the complete error reference, retry strategies, and blockchain revert reasons.

Next steps

• Getting started - Create an API key and configure the TypeScript client
• Error handling - Handle errors and implement retry strategies
• Transaction tracking - Recover from confirmation timeouts
• Token lifecycle - Visual flowcharts for token operations