# Organisation deployment API

Source: https://docs.settlemint.com/docs/developers/platform-setup/organization-deployment-api
Start organisation deployment, read the deployment tree, track account-abstraction setup, and separate organisation deployment from system creation for API-based platform setup.



Use the organisation deployment API to create the organisation context and start the provisioning workflow. The platform prepares the system, registries, roles, identity contracts, compliance modules, factories, and add-ons, in that order. It includes optional nodes such as Exchange Rate Feeds and paymaster phases only when the active chain supports them. Call this API before you create assets, assign roles after deployment, or configure provider-specific settings.

For the broader setup path, see [Platform setup overview](/docs/developers/platform-setup/platform-overview). For how to authenticate and discover the OpenAPI spec, see [API reference](/docs/api-reference/reference/openapi).

## Prerequisites [#prerequisites]

Before you call the deployment API, confirm these inputs and conditions:

* You have an authenticated session for the user that owns the new organisation.
* The organisation name is clear enough for operators to identify the workspace.
* Currency choices use ISO 4217 alpha-3 codes such as `EUR`, `USD`, or `SGD`.
* `targetCurrencies` includes `baseCurrency`, contains no duplicates, and includes at least one currency other than `baseCurrency`.

## Quickstart [#quickstart]

Call `POST /api/v2/organizations` to start deployment. The platform returns a `deploymentId` and the initial progress tree. By default, DALP waits for terminal success before responding; send `Prefer: respond-async` to start and poll status separately.

```bash
curl -X POST "$DALP_API_URL/api/v2/organizations" \
  -H "Content-Type: application/json" \
  -H "Prefer: respond-async" \
  -b "$DALP_SESSION_COOKIE" \
  -c /tmp/dalp-org-deploy.cookies \
  -d '{
    "name": "Northwind Treasury",
    "baseCurrency": "EUR",
    "targetCurrencies": ["EUR", "SGD"]
  }'
```

```json
{
  "deploymentId": "org_01hz8y2w6q8x7n4p9r3s2t1v0w",
  "tree": [
    { "id": "wallet", "label": "Wallet", "type": "wallet", "status": "pending" },
    {
      "id": "organization",
      "label": "Organization",
      "type": "system",
      "status": "pending",
      "children": [
        { "id": "system", "label": "System Contract", "type": "system", "status": "pending" },
        { "id": "registries", "label": "Registries", "type": "registry", "status": "pending" },
        { "id": "roles", "label": "Access Roles", "type": "role", "status": "pending" },
        { "id": "identity", "label": "Identity", "type": "identity", "status": "pending" },
        { "id": "compliance", "label": "Compliance Modules", "type": "compliance", "status": "pending" },
        { "id": "factories", "label": "Asset Factories", "type": "factory", "status": "pending" },
        { "id": "addons", "label": "Addon Factories", "type": "addon", "status": "pending" }
      ]
    }
  ]
}
```

Exact node labels can vary by deployment state. The `feeds` node appears only when the active chain Directory reports feeds support for that system. On chains without feeds support, DALP omits the Exchange Rate Feeds step entirely rather than returning a skipped or failed feed node. Smart-wallet setup for advanced accounts does not appear as a deployment-tree node. Key your integration code off `id`, `type`, and `status` instead of display text.

## Request fields [#request-fields]

| Field              | Type      | Required | Rules                                                                                        |
| ------------------ | --------- | -------- | -------------------------------------------------------------------------------------------- |
| `name`             | string    | Yes      | 1 to 32 characters.                                                                          |
| `baseCurrency`     | string    | Yes      | ISO 4217 alpha-3 currency code. Must also appear in `targetCurrencies`.                      |
| `targetCurrencies` | string\[] | Yes      | ISO 4217 alpha-3 currency codes. No duplicates. Must include at least one non-base currency. |

DALP rejects the request before it starts deploying when the currency set is invalid. Fix the request body before retrying.

## Monitor deployment progress [#monitor-deployment-progress]

Open the event stream after the create response returns a `deploymentId`. Reuse the cookie jar from the create request so the platform preserves the active-organisation cookie for the server-sent event connection.

```bash
curl -N "$DALP_API_URL/api/v2/organizations/deployments/org_01hz8y2w6q8x7n4p9r3s2t1v0w/stream" \
  -H "Accept: text/event-stream" \
  -b /tmp/dalp-org-deploy.cookies
```

The stream emits deployment events as server-sent events.

| Event type | Payload fields                       | Client handling                                                      |
| ---------- | ------------------------------------ | -------------------------------------------------------------------- |
| `tree`     | `nodes`                              | Replace the local deployment tree with the received tree.            |
| `update`   | `nodeId`, `status`, optional `error` | Patch the matching node in the local tree.                           |
| `complete` | `success`, optional `failedSteps`    | Stop listening. If `success` is false, show the failed step details. |
| `error`    | `message`, `error`                   | Stop listening and inspect the public Platform API error payload.    |

Each node's status is one of `pending`, `in-progress`, `completed`, or `failed`. A `complete` event is terminal for that stream. Reconnect only when the terminal error is retryable or when the operator restarts the deployment.

## Organisation deployment and system creation scope [#organisation-deployment-and-system-creation-scope]

Organisation deployment is the public setup entry point for onboarding automation. It starts a workflow that creates the system and completes the remaining organisation bootstrap steps.

The lower-level system route deploys a SMART system with identity registry, compliance engine, and token factory registry contracts. Do not call it as a substitute for organisation deployment. Organisation deployment establishes the workspace scope, then runs the full bootstrap sequence described above. It adds Exchange Rate Feeds and paymaster phases only when the active chain supports those capabilities.

| Surface                        | Route                                                         | Use it for                                                                               |
| ------------------------------ | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Organization deployment        | `POST /api/v2/organizations`                                  | Create the organization context and start platform setup.                                |
| Organization deployment stream | `GET /api/v2/organizations/deployments/{deploymentId}/stream` | Track deployment progress until terminal success or failure.                             |
| Organization deployment status | `GET /api/v2/organizations/deployments/{deploymentId}`        | Read structured deployment status when polling without the event stream.                 |
| System creation                | `POST /api/v2/systems`                                        | Deploy a SMART system when a system-level integration explicitly needs it.               |
| Legacy system creation         | Existing system creation operation                            | Maintain an existing system-level client only. Do not use it for new organisation setup. |
| System deployment resumption   | `POST /api/v2/system-resumptions`                             | Resume a stalled system deployment when the system flow exposes that state.              |

The system create endpoint accepts an optional `contract` address. When omitted, the server resolves the standard system factory address from indexed directory state. A successful call returns a `systemAddress`; clients can read that system after the call completes.

For new onboarding work, direct clients to organisation deployment instead of the legacy endpoint. Keep the system route for existing system-level integrations that already own their organisation context and need to deploy or resume only the SMART system layer.

## Advanced accounts during deployment [#advanced-accounts-during-deployment]

Organisation deployment can run smart-wallet provisioning when advanced accounts is enabled, but that provisioning is not a deployment-tree node. The bootstrap writes still run through the externally owned account so every setup phase completes before a participant smart wallet becomes the executor for later operations.

Keep these phases separate in your client code:

1. Start and monitor organisation deployment until the stream returns terminal success.
2. Do not wait for a `smart-wallet` deployment-tree node. Smart-wallet setup runs as part of the account-abstraction plumbing behind the deployment workflow.
3. Do not send `X-Executor` to the organisation deployment create or stream routes. Those routes bootstrap the organisation workflow rather than selecting a per-request executor.
4. After setup, follow the normal participant and executor rules for mutating API calls. Omit `X-Executor` unless the request must force `eoa` or `smart-wallet` execution for a specific participant.
5. Before relying on smart-wallet execution, read the wallet or check whether the gas balance is sufficient through the smart wallet API.

See [Request headers](/docs/api-reference/reference/request-headers) for `X-Participant` and `X-Executor`, and [Smart wallet API overview](/docs/api-reference/wallets/smart-wallets) for wallet reads, gas checks, signer management, and async status handling.

## Retry and idempotency rules [#retry-and-idempotency-rules]

Organisation deployment runs as a workflow. If it is interrupted after a child node completes, retrying for the same organisation resumes from completed phases instead of redeploying every phase. The tested retry path covers all setup phases, including feeds and paymaster phases when the active chain includes those nodes.

Your client code should follow this rule:

1. Start deployment once for the organisation.
2. Store the returned `deploymentId` with the onboarding session.
3. Subscribe to the deployment stream until `complete` or `error`, or poll `GET /api/v2/organizations/deployments/{deploymentId}` until the status is `completed` or `failed`.
4. When interrupted, read the stored deployment status before starting a new deployment.
5. Treat completed nodes as durable progress and failed nodes as operator-visible work.

Do not create assets until organisation deployment completes and the active organisation context is set for the caller.

## Related pages [#related-pages]

* [Platform setup overview](/docs/developers/platform-setup/platform-overview) maps the full setup path before asset creation.
* [DALP admin operating model](/docs/developers/platform-setup/admin-operating-model) covers user and role management, API keys, webhooks, and provider configuration.
* [API reference](/docs/api-reference/reference/openapi) covers authentication and the full OpenAPI specification.
* [Organization and system scope](/docs/api-reference/reference/organization-system-scope) describes how integrations stay in the correct organization and system context.
* [Create an asset](/docs/operators/asset-creation/create-asset) starts the first asset workflow after platform setup is complete.