Operational integration patterns for the DALP API

Your integration connects off-chain ledgers, cap table systems, analytics stores, and customer platforms through the public API contract. Build consumers from REST APIs, the generated OpenAPI specification, indexed token events, account activity reads, and blockchain monitoring endpoints. Do not read internal databases directly. For a category-level map of documented provider surfaces and project-specific responsibilities, see the integration overview.

Choose the integration surface

Choose the public surface that matches your operational job.

Use the diagram as a routing map. Once you have the right surface, the API contract lives in the generated OpenAPI specification and the linked reference sections below.

Event access model

To reconcile token movements into an off-chain ledger, use the token events collection. This endpoint supports pagination, filtering by event fields, and sorted replay:

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/events?page[offset]=0&page[limit]=50&sort=-blockTimestamp" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

The endpoint returns the canonical collection envelope:

• data: event items
• meta: total count and facet counts
• links: pagination links for the current query

The default sort is newest first by blockTimestamp. You can also sort by blockNumber. Supported filters include eventName, senderAddress, accountAddress, walletAddress, transactionHash, and blockTimestamp ranges.

Use pagination to backfill or replay reads for a token in your integration. DALP does not document Kafka as a public delivery interface for token events. If you need event-driven processing, use the REST collection for durable reads and generate a typed client from the OpenAPI specification. Live operation screens may use server-sent events where a specific endpoint documents a stream, such as blockchain monitoring snapshots or migration progress, but token events are consumed through the REST collection. See Token holders and transfers and API reference for the full event collection contract.

Event payload fields

Token event items include the operational fields needed for ledger reconciliation. Each item carries block number, block timestamp, and transaction hash. It also includes the event name, the emitting contract, the sender address, the related account, the amount, and any event-specific values.

Example shape:

{
  "id": "evt_01j...",
  "eventName": "TransferCompleted",
  "blockNumber": "8154321",
  "blockTimestamp": "2026-05-01T11:59:30.000Z",
  "transactionHash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "txIndex": "0",
  "emitter": { "id": "0x2000000000000000000000000000000000000002" },
  "sender": { "id": "0x3000000000000000000000000000000000000003" },
  "values": [
    {
      "id": "evt_01j...-account",
      "name": "account",
      "value": "0x3000000000000000000000000000000000000003"
    },
    { "id": "evt_01j...-amount", "name": "amount", "value": "500" }
  ]
}

Consumers should treat the OpenAPI response schema as the contract. Use exact transaction-hash filtering when reconciling one operation:

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/events?filter[transactionHash][eq]=0xTRANSACTION_HASH" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Deterministic replay and idempotency

Token event reads are queryable, paginated collections. The default event order is newest first by blockTimestamp, with block and log metadata available for deterministic reconciliation. For deterministic replay jobs:

1. Scope each reader to one token address.
2. Use blockTimestamp windows or pagination for REST replay. The token events API includes blockNumber in each event item, but block-number range replay is an indexer capability rather than a public token-event query parameter.
3. Persist the last processed event identifier, timestamp, transaction hash, block number, and transaction index.
4. On resume, reread inclusively from the last processed timestamp or a bounded timestamp window.
5. Dedupe by event identifier plus transaction hash, block number, and transaction index.
6. Store processed transaction hash, block number, event name, event identifier, transaction index, and token contract address in your own ledger.

For mutation APIs that submit transactions, pass an Idempotency-Key header. DALP uses that key when queueing blockchain transactions so a retry returns the existing result instead of submitting the same transaction twice. Read-only event collection calls do not need an idempotency key; they should be replay-safe through persisted checkpoints and deduplication.

When you use the DALP SDK for a one-shot mutation script, set idempotencyKey on the client to send the Idempotency-Key header. The SDK sends that option on every request made by the configured instance, so do not reuse it for different mutations. For workflows that submit several mutations, create a fresh client per operation or send operation-specific request headers. Mutation APIs can return transaction metadata synchronously or an async statusUrl, depending on the operation. On confirmation timeout, check transaction status before retrying. Never re-submit a confirmed on-chain operation.

Related pages: SDK reference, Token holders and transfers, and Transaction tracking.

Chain finality, indexer health, and reindexing

Use blockchain monitoring endpoints to verify whether DALP can read the chain reliably. The API reports chain RPC and indexer health, including sync lag, block age, finality lag, stall time, reindex status, and recent service state.

The indexer records block hashes and detects chain reorganizations by comparing indexed blocks with the canonical RPC chain. When a reorg is detected, DALP rolls indexed state back to the fork block and reprocesses affected blocks. Consumers should still keep their own ingestion idempotent because a previously read event can disappear or be replaced after rollback and reprocessing.

Operational endpoints include:

• GET /api/v2/blockchain-monitoring/health-metrics/summary
• GET /api/v2/blockchain-monitoring/health-metrics/timeline
• GET /api/v2/blockchain-monitoring/service-health-metrics
• GET /api/v2/blockchain-monitoring/health-snapshots
• GET /api/v2/blockchain-monitoring/health-snapshots/stream

The stream endpoint uses server-sent events for live operations screens. Snapshot events include eventType, serviceType, chainId, networkName, status, blockHeight, chainHeadBlock, syncLag, finalityLagBlocks, stallSeconds, and optional deployment state. For full details on these endpoints, see Blockchain monitoring.

Token and class discovery

Use the API reference and token lifecycle guides for token creation and discovery. Token creation returns the deployed contract address. After issuance, your integration works from that address. Token-specific endpoints cover details, holders, events, features, metadata, compliance modules, transfer approvals, and denomination assets.

The following endpoints are available for discovery.

• GET /api/v2/tokens supports filter[q]=... and field filters including factory, type, name, symbol, and creation date
• GET /api/v2/system/factories lists factories on the active system
• GET /api/v2/settings/asset-class-definitions lists asset class definitions

Per-token endpoints:

• GET /api/v2/tokens/{tokenAddress} for details
• GET /api/v2/tokens/{tokenAddress}/holders for the holder balance collection
• GET /api/v2/tokens/{tokenAddress}/holder-balances with holderAddress for one holder
• GET /api/v2/tokens/{tokenAddress}/events for indexed events
• GET /api/v2/tokens/{tokenAddress}/features for attached features
• GET /api/v2/tokens/{tokenAddress}/metadata for metadata entries
• GET /api/v2/tokens/{tokenAddress}/compliance-modules for compliance configuration
• GET /api/v2/tokens/{tokenAddress}/transfer-approvals for transfer approval records

DALP does not expose a single public issuer-to-contract registry endpoint in the current API. If your integration models each share class as a separate token contract, keep the issuer-to-token mapping in the integrating system and reconcile it with token and factory discovery endpoints. Collect class metadata during asset creation through instrument templates, asset class definitions, and token metadata fields. Metadata mutability depends on permissions and the supported metadata update flow.

For context, see API reference, Asset class definitions, Token lifecycle, Instrument templates, and Asset detail workspace.

Balance history and cap-table servicing

Use holder reads, indexed token events, and feature endpoints to reconcile cap-table and servicing systems. DALP exposes current token holders and indexed events through the token API.

The current public API does not expose a token balance-at-block endpoint or a dividend-specific record-date snapshot endpoint. For dividend or record-date workflows, store the record date and block reference in your off-chain servicing system, then build the required snapshot from token events and current holder reconciliation. Keep the snapshot inputs and replay checkpoint so your calculation can be reproduced and audited. Related resources: Lifecycle after issuance, Token lifecycle, and Token holders and transfers.

Upgrade operations and compatibility

DALP includes a guided system upgrade workflow for keeping deployed system contracts current with the latest implementations available for the active network. The workflow compares deployed system components with the network directory, shows which components differ, and runs the upgrade with live progress.

Relevant endpoints include:

• GET /api/v2/system/migration/compare for directory-versus-deployed comparison
• POST /api/v2/system/migration/start to start a migration or upgrade workflow
• GET /api/v2/system/migration/active to check active migration state
• GET /api/v2/system/migration/{migrationId}/stream for live migration progress

Only accounts with the required system-management permission can run upgrades. The API accepts platform admins or wallets with the system manager or admin role on the indexed system. Completed on-chain steps remain applied if a later step fails, so review the comparison before starting and use the retry flow after fixing the reported issue.

System contract upgrades emit implementation-update events such as ImplementationUpdated and BatchImplementationsSet for system implementation changes. Integrations should still rely on the API and OpenAPI schema as the compatibility contract. On-chain events are low-level operational evidence, not a substitute for the API contract.

For integration compatibility:

• Generate your clients from the current OpenAPI specification.
• Treat OpenAPI response schemas as the public API contract.
• Read token features before calling feature-specific routes.
• Reconcile events and transaction status after upgrade or migration work.
• Use blockchain monitoring deployment state when an indexer is rebuilding.

For runbooks and monitoring, see System upgrades, API reference, and Blockchain monitoring.

Self-hosted deployment and operations

Self-hosted DALP deployments run on Kubernetes or OpenShift through Helm charts. For Azure AKS, the self-hosting prerequisites call for managed PostgreSQL, managed Redis, object storage and backup storage, and managed observability unless an approved self-hosted fallback is used.

The Helm charts expose replica counts and placement controls for API and worker services. The indexer runs as its own workload and is intentionally single-replica with a recreate update strategy. Design capacity and isolation around workload placement, database capacity, RPC capacity, queue throughput, and operational monitoring rather than horizontal indexer replicas.

SettleMint leads the initial installation when the prerequisites are complete. Agree long-term operational ownership during the deployment handover: who runs Helm upgrades, who patches, who monitors, and who owns backups. SettleMint can also operate the environment through an agreed control-plane-managed model, depending on the commercial and operational scope. The environment must export telemetry through the cloud provider or an approved managed observability stack. See Self-hosting prerequisites and Blockchain monitoring for infrastructure requirements and health endpoints.

Private keys and secrets

DALP uses Key Management for private-key protection. It supports multiple storage tiers: encrypted database storage, cloud secret managers, Luna HSM hardware-backed partition signing, and third-party custody providers such as DFNS and Fireblocks. Your production deployment should use the tier approved for the asset value and regulatory posture.

Key Management receives signing requests without exposing raw key material and routes each one to the configured backend. It logs signing activity, key generation, rotation events, and access denials for security review.

For Luna HSM deployments, keep quorum activation and partition administration in the HSM control plane. DALP routes EVM signing requests through the signer adapter after the configured HSM partition and key labels are available. DALP does not replace the HSM approval or partition-management process. For architecture details, see Key Management, Custody providers, and Signing flow.

Rate limits and throughput

Authentication endpoints and API keys both carry explicit rate-limit controls.

Counters use shared storage and apply across replicas. DALP trusts x-real-ip for rate-limit attribution; the accepted header is fixed to x-real-ip in the auth server configuration.

Configure real-client-IP attribution before exposing authentication endpoints:

• For nginx-ingress, enable the real-IP module in the controller ConfigMap. Set the real-IP source header from the trusted upstream edge proxy, keep the trusted proxy CIDR list current, and verify the controller overwrites X-Real-IP before forwarding to DALP. A typical checklist: enable-real-ip: "true", real-ip-header set to the trusted upstream header, and proxy-real-ip-cidr restricted to the load balancer or upstream proxy ranges.
• For Traefik, configure trusted forwarded-header sources only for the entry point that receives traffic from the managed load balancer. Then add a router middleware or upstream edge rule that sets X-Real-IP to the validated client IP before the request reaches the DALP service. Do not pass through a client-supplied X-Real-IP value.
• For Gateway API, Envoy, or OpenShift Routes, do not assume the DALP route object rewrites X-Real-IP. Add an equivalent trusted header rewrite in the Gateway policy, Envoy filter, OpenShift router configuration, or upstream edge proxy before forwarding traffic to DALP. Without that rewrite, rate-limit counters attribute to the gateway, router, or proxy IP instead of the client IP.
• Validate the configuration by sending requests through the public route and confirming the API service receives x-real-ip as the original client IP. Do not rely on other forwarded headers or client-supplied values for rate-limit attribution; those values can be missing, incorrect, or spoofable.

DALP does not publish a universal transactions-per-second number for every deployment. Throughput depends on the selected chain, RPC provider, custody backend, queue configuration, infrastructure sizing, bundler settings, and operation mix.

Use load testing against the target environment and agree production rate limits during implementation. For self-hosted environments, base capacity decisions on the infrastructure baselines documented in Self-hosting prerequisites. See also API reference for the full endpoint surface.

SLA and operational addenda

The API and Helm charts expose operational health probes and telemetry endpoints. These include /healthz for liveness, /readyz for readiness, OpenTelemetry export, blockchain monitoring health metrics, service health metrics, health snapshots, and snapshot streams.

SLA terms are not defined by the public API documentation. Treat uptime, support response times, maintenance windows, backup responsibilities, and incident processes as part of the SLA addendum or managed-service agreement for the deployment. See Blockchain monitoring and Self-hosting prerequisites for health endpoint and infrastructure details.

Recommended off-chain ledger pattern

Use an append-only mirror in your integrating system so each ingested event is idempotent and auditable. Store at minimum the fields below.

• token contract address
• event identifier
• event name
• block number
• block timestamp
• transaction hash
• sender address
• account or wallet address
• amount and value fields
• ingestion timestamp
• source API timestamp window and replay checkpoint

Rebuild from the event collection when needed. Reconcile current balances with holder reads. Do not treat the mirror as the source of truth for token ownership: DALP and the chain are authoritative.