Organisation deployment API

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. For how to authenticate and discover the OpenAPI spec, see API reference.

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

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.

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"]
  }'

{
  "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

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

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.

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.

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 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.

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

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 for X-Participant and X-Executor, and Smart wallet API overview for wallet reads, gas checks, signer management, and async status handling.

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

• Platform setup overview maps the full setup path before asset creation.
• DALP admin operating model covers user and role management, API keys, webhooks, and provider configuration.
• API reference covers authentication and the full OpenAPI specification.
• Organization and system scope describes how integrations stay in the correct organization and system context.
• Create an asset starts the first asset workflow after platform setup is complete.