Organisation deployment API

Organisation deployment creates the organisation context and starts the setup workflow. The workflow prepares the platform system, registries, roles, identity, compliance, factories, and add-ons. It includes optional setup nodes, such as Exchange Rate Feeds and paymaster phases, only when the active chain supports them. Onboarding automation uses this API path before asset creation, post-deployment role assignment, or provider-specific configuration.

For the broader setup sequence, see Platform setup overview. For API authentication and OpenAPI discovery, see API reference.

Prerequisites

Before calling the deployment API, confirm these inputs and runtime conditions:

• The caller has an authenticated session for the user that owns the new organisation setup.
• The organisation name is final 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

Start deployment with POST /api/v2/organizations. The response returns a deploymentId and the current deployment tree. DALP waits for terminal success by default; clients can send Prefer: respond-async when they want to start deployment 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" }
      ]
    }
  ]
}

The 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 instead of returning a skipped or failed feed node. Smart-wallet setup for account abstraction does not appear as a deployment-tree node. Integration code should key off id, type, and status instead of display text.

Request fields

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

Monitor deployment progress

Open the deployment stream after the create response returns a deploymentId. Reuse the cookie jar from the create request so the active-organisation cookie set during deployment is preserved for the server-sent event stream.

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.

Deployment node 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 deployment.

Organisation deployment and system creation scope

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

The lower-level system creation route deploys a SMART system with identity registry, compliance engine, and token factory registry contracts. New integrations should not call it as a substitute for organisation deployment. Organisation deployment establishes the workspace scope, then continues through system, registry, role, identity, compliance, factory, and add-on setup. It adds Exchange Rate Feeds and paymaster phases only when the active chain supports those capabilities.

System create requests accept an optional contract address. When omitted, the server resolves the standard system factory address from indexed directory state. Successful system creation returns a systemAddress; clients can read that system after the operation completes.

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

Account abstraction during deployment

Organisation deployment can run smart-wallet setup when account abstraction is enabled for the deployment, but that setup is not a deployment-tree node. The bootstrap writes still run through the setup user's externally owned account so the organisation, system, registries, roles, identity, compliance modules, factories, and add-ons can be established before a participant smart wallet becomes the executor for later operations.

For integration code, keep these phases separate:

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. They bootstrap the organisation workflow rather than selecting a per-request executor.
4. After setup, use the normal participant and executor selection 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 gas readiness 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 is a workflow. If a deployment is interrupted after a child node completes, retrying deployment for the same organisation can resume from completed phases instead of redeploying every phase. The tested retry path covers system, registries, roles, identity, compliance, factories, and add-ons. It also covers feeds and paymaster phases when the active chain includes those nodes.

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. On interruption, 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 successfully 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 explains organisation, user, role, API key, webhook, provider, and operator-wallet responsibilities.
• API reference explains OpenAPI discovery, authentication, headers, and route namespaces.
• Organization and system scope explains how integrations stay in the correct organization and system context.
• Create an asset starts the first asset workflow after platform setup is complete.