# API reference

Source: https://docs.settlemint.com/docs/developer-guides/api-integration/api-reference
Access the OpenAPI specification and generate type-safe clients for integrating with the DALP platform programmatically.



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.

![REST API documentation with full endpoint reference](/docs/screenshots/xvp/xvp-api-light.webp)

## OpenAPI specification endpoints [#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.

| API version | Interactive explorer | OpenAPI JSON        | Use it for                                      |
| ----------- | -------------------- | ------------------- | ----------------------------------------------- |
| v2          | `/api/v2`            | `/api/v2/spec.json` | New integrations and generated clients.         |
| v1          | `/api/v1`            | `/api/v1/spec.json` | Existing integrations that still use v1 routes. |

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](https://spec.openapis.org/oas/latest.html). 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 [#viewing-the-specification]

Open the current explorer in your browser:

<a href="https://your-platform.example.com/api/v2" target="_blank" rel="noopener noreferrer">
  Open DALP API explorer
</a>

Fetch the JSON specification for code generators and API tools:

```bash
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 [#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](/docs/developer-guides/api-integration/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](/docs/developer-guides/api-integration/getting-started) for API key creation and client configuration. See [Request headers](/docs/developer-guides/api-integration/request-headers) for participant and executor selection. See [Smart wallet API overview](/docs/developer-guides/api-integration/smart-wallets) for smart wallet discovery, signer management, and multisig approvals. See [Events](/docs/events) when an integration needs webhook payload schemas, lifecycle states, or replay-safe reconciliation after a write request. See [UserOperations](/docs/architecture/concepts/user-operations) for the smart-account request model behind account abstraction execution.

***

## Response headers [#response-headers]

### Transaction hash header [#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](/docs/developer-guides/operations/transaction-tracking) for timeout recovery patterns.

***

## API namespaces [#api-namespaces]

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

| Namespace         | Description                                                | Example operations                                                                           |
| ----------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **token**         | Token CRUD, supply management, compliance, stats           | `token.create`, `token.mint`, `token.burn`, `token.transfer`, `token.freezeAddress`          |
| **transaction**   | Blockchain transaction status tracking                     | `transaction.read`                                                                           |
| **system**        | Platform infrastructure (access control, identity, claims) | `system.accessManager.grantRole`, `system.identity.register`, `system.trustedIssuers.create` |
| **user**          | User profile and organization membership                   | `user.me`, `user.update`                                                                     |
| **account**       | Blockchain wallet and identity management                  | `account.identity`, `account.claims`                                                         |
| **actions**       | Scheduled tasks and executable operations                  | `actions.list`, `actions.read`                                                               |
| **addons**        | Optional features such as token sales and fixed yield      | `addons.tokenSale.create`, `addons.fixedYield.create`, `addons.fixedYield.claim`             |
| **contacts**      | Contacts for frequent wallet recipients                    | `contacts.list`, `contacts.create`                                                           |
| **exchangeRates** | Foreign exchange rates for multi-currency assets           | `exchangeRates.list`, `exchangeRates.supportedCurrencies`                                    |
| **search**        | Global search across tokens, contacts, transactions        | `search.query`                                                                               |
| **settings**      | Platform configuration and preferences                     | `settings.get`, `settings.update`                                                            |
| **externalToken** | Import and track tokens from other systems                 | `externalToken.register`, `externalToken.list`                                               |
| **bundler**       | ERC-4337 JSON-RPC discovery for account abstraction        | `eth_chainId`, `eth_supportedEntryPoints`                                                    |
| **auth**          | Better Auth endpoints (sign-in, sessions, passkeys)        | `/auth/sign-in`, `/auth/session`, `/auth/passkey/create`                                     |

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

### Bundler JSON-RPC endpoint [#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](/docs/architecture/concepts/bundlers) for the concept model.

| Endpoint               | Protocol     | Supported methods                         | Use it for                                |
| ---------------------- | ------------ | ----------------------------------------- | ----------------------------------------- |
| `POST /api/v2/bundler` | JSON-RPC 2.0 | `eth_chainId`, `eth_supportedEntryPoints` | Discover the active chain and EntryPoint. |

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.

```bash
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](/docs/developer-guides/api-integration/system-paymasters) and [Paymasters and gas sponsorship](/docs/architecture/concepts/paymasters-and-gas-sponsorship).

### Exchange-rate operations [#exchange-rate-operations]

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

| Operation                           | HTTP route                                                          | Permission               | Use it for                                                     |
| ----------------------------------- | ------------------------------------------------------------------- | ------------------------ | -------------------------------------------------------------- |
| `exchangeRates.list`                | `GET /api/v2/exchange-rates`                                        | `exchangeRates:list`     | List feed-backed rates with pagination, sorting, and filters.  |
| `exchangeRates.read`                | `GET /api/v2/exchange-rates/{baseCurrency}/{quoteCurrency}`         | `exchangeRates:read`     | Read one current currency pair.                                |
| `exchangeRates.update`              | `PUT /api/v2/exchange-rates/{baseCurrency}/{quoteCurrency}`         | `exchangeRates:update`   | Set a manual rate override for one pair.                       |
| `exchangeRates.delete`              | `DELETE /api/v2/exchange-rates/{baseCurrency}/{quoteCurrency}`      | `exchangeRates:remove`   | Delete a manual rate override.                                 |
| `exchangeRates.sync`                | `POST /api/v2/exchange-rates/sync`                                  | `exchangeRates:sync`     | Refresh rates from the configured provider.                    |
| `exchangeRates.history`             | `GET /api/v2/exchange-rates/{baseCurrency}/{quoteCurrency}/history` | `exchangeRates:list`     | Read historical values for one pair.                           |
| `exchangeRates.supportedCurrencies` | `GET /api/v2/exchange-rates/supported-currencies`                   | authenticated read route | Read the provider's supported ISO 4217 currency-code snapshot. |

`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:

```json
{
  "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](/docs/user-guides/data-feeds/overview#exchange-rate-target-currencies). For CLI equivalents, see [Exchange rate commands](/docs/developer-guides/cli/command-reference#exchange-rate-commands). For the feed architecture behind the API, see [Feeds system](/docs/architecture/components/infrastructure/feeds-system#exchange-rate-refresh).

### Organization deployment stream [#organization-deployment-stream]

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

| Operation                   | HTTP route                                               | Use it for                                            |
| --------------------------- | -------------------------------------------------------- | ----------------------------------------------------- |
| `organization.deployStream` | `GET /api/v2/organizations/deploy/{deploymentId}/stream` | Watch organization deployment progress until it ends. |

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:

| Event type | Meaning                                                                                                                             | Client handling                                                            |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `tree`     | Full deployment tree. Sent when the workflow state is available and whenever node shape changes.                                    | Replace the local deployment tree with the received nodes.                 |
| `update`   | Status change for an existing deployment node.                                                                                      | Patch the matching node by `nodeId`.                                       |
| `complete` | Terminal deployment result. `success: true` means the deployment finished successfully. `success: false` can include `failedSteps`. | Stop listening and show the final result.                                  |
| `error`    | Stream or polling failure encoded as a public DAPI error payload.                                                                   | Stop listening, inspect `error.id`, `error.retryable`, and the request ID. |

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](/docs/developer-guides/api-integration/error-handling#deployment-workflow-errors).

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 [#fixed-yield-schedule-operations]

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

| Operation                    | HTTP route                                                                | Use it for                                    |
| ---------------------------- | ------------------------------------------------------------------------- | --------------------------------------------- |
| `addons.fixedYield.create`   | `POST /api/v2/addons/fixed-yield-schedules`                               | Create a fixed yield schedule for a token.    |
| `addons.fixedYield.read`     | `GET /api/v2/addons/fixed-yield-schedules/{scheduleAddress}`              | Read one schedule by contract address.        |
| `addons.fixedYield.topUp`    | `POST /api/v2/addons/fixed-yield-schedules/{scheduleAddress}/top-ups`     | Deposit denomination asset into the schedule. |
| `addons.fixedYield.withdraw` | `POST /api/v2/addons/fixed-yield-schedules/{scheduleAddress}/withdrawals` | Withdraw unused denomination asset.           |
| `addons.fixedYield.claim`    | `POST /api/v2/addons/fixed-yield-schedules/{scheduleAddress}/claims`      | Claim available yield from the schedule.      |

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](/docs/developer-guides/cli/command-reference#fixed-yield-schedule-commands) and [Configure yield schedules](/docs/user-guides/system-addons/yield-schedule).

### User statistics data sources [#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 [#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](/docs/developer-guides/api-integration/getting-started#configure-the-sdk) for SDK setup and client configuration.

***

## Using with API tools [#using-with-api-tools]

### Interactive explorer [#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:

```bash
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 [#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:
   ```bash
   npx @redocly/cli preview-docs openapi.json
   ```
3. Open `http://localhost:8080` in your browser.

### Postman [#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 [#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 [#curl-examples]

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

```bash
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:

```bash
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 [#generating-client-sdks]

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

### Python (openapi-generator) [#python-openapi-generator]

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

### Go [#go]

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

### C# / .NET [#c--net]

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

### Java [#java]

```bash
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 [#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](/docs/developer-guides/api-integration/error-handling) for the complete error reference, retry strategies, and blockchain revert reasons.

***

## Next steps [#next-steps]

* **[Getting started](/docs/developer-guides/api-integration/getting-started)** - Create an API key and configure the TypeScript client
* **[Error handling](/docs/developer-guides/api-integration/error-handling)** - Handle errors and implement retry strategies
* **[Transaction tracking](/docs/developer-guides/operations/transaction-tracking)** - Recover from confirmation timeouts
* **[Token lifecycle](/docs/developer-guides/api-integration/token-lifecycle)** - Visual flowcharts for token operations