Setup

There are two ways to set up a new Wallet2 service:

  • Composable init (recommended): Bootstrap a Wallet2 instance and optional dependency services (KMS, DID Store, DID Service, Credential Store) in one call via POST /v1/{target}/resource-api/services/init.
  • Manual setup: Create a standalone Wallet2 with "type": "wallet2" via the resource API. Optionally provide a static key and DID, then attach dependencies as needed.

Each Wallet2 instance corresponds to a single wallet identified by a unique target (e.g. waltid.tenant1.wallet1). The resource type must be "wallet2". Use the /v2/{target}/wallet-service-api/... endpoints for all Wallet2 operations.

Need the legacy draft Wallet (type: "wallet", /v1 API)? See Wallet Service setup. That path requires the wallet-draft-routes feature.

Prerequisites

Creating a Wallet2 with Composable Init

Composable init creates a Wallet2 (type: wallet2) and can create or link KMS, keys, DID store/service, DIDs, and credential store in dependency order. The endpoint is idempotent when createIfNotFound is true.

CURL

Endpoint: POST /v1/{target}/resource-api/services/init | API Reference

Example Request (full wallet bootstrap)

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{org}.{tenant}/resource-api/services/init' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "wallet": {
    "createIfNotFound": true,
    "target": "waltid.tenant1.wallet1",
    "kms": {
      "createIfNotFound": true,
      "target": "waltid.tenant1.wallet1.kms",
      "key": {
        "createIfNotFound": true,
        "target": "waltid.tenant1.wallet1.kms.wallet_key",
        "config": {
          "backend": "jwk",
          "keyType": "Ed25519"
        }
      }
    },
    "didStore": {
      "createIfNotFound": true,
      "target": "waltid.tenant1.wallet1.didstore"
    },
    "didService": {
      "createIfNotFound": true,
      "target": "waltid.tenant1.wallet1.didservice",
      "dependencies": [
        "waltid.tenant1.wallet1.kms",
        "waltid.tenant1.wallet1.didstore"
      ],
      "did": {
        "createIfNotFound": true,
        "target": "waltid.tenant1.wallet1.didstore.wallet_did",
        "type": "key"
      }
    },
    "credentialStore": {
      "createIfNotFound": true,
      "target": "waltid.tenant1.wallet1.credentialstore"
    }
  }
}'

Path Parameters

  • orgID — Organization base URL / host alias (e.g. test.enterprise-sandbox.waltid.dev on sandbox).
  • target — Tenant path where initialization runs ({organizationID}.{tenantID}), e.g. waltid.tenant1.

Body Parameters (wallet block)

  • wallet.createIfNotFound — Create the Wallet2 if missing.
  • wallet.target — Full Wallet2 resource path, e.g. waltid.tenant1.wallet1.
  • wallet.config (optional) — Wallet configuration object (e.g. staticDid, staticKey).
  • wallet.kms / didStore / didService / credentialStore (optional) — Nested composable blocks with their own target, createIfNotFound, and configs.

You can also include an issuer block in the same request to bootstrap Issuer2 alongside Wallet2.

Response Codes

  • 200 / 201 — Initialization completed (created and/or reused existing resources).

Creating a Wallet2 without Dependencies

Create a Wallet2 service with "type": "wallet2". Optionally provide a static key and DID when you do not attach KMS / DID store.

CURL

Endpoint: POST /v1/{target}/resource-api/services/create | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/resource-api/services/create' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "wallet2",
  "configuration": {
    "staticKey": {
      "type": "jwk",
      "jwk": {
        "kty": "OKP",
        "d": "wZ69WYFIZHYEC9gWsRYCIHsJ4G5qdZeCrCry6szGij4",
        "crv": "Ed25519",
        "kid": "I-bh2IYP93feK_dIYA7QaNSHoRlftw53KYpNYPdEpNQ",
        "x": "sD8DqvgzEjQaex5p4NNp_Qyd8knJAJfZY7Ge8vCmBGY"
      }
    },
    "staticDid": "did:key:z6MkrKFXimvdRgYnsFeyQq5sUn4vmXJVDHriHJKpgy6oaC6H"
  }
}'

Body Parameters

  • type — Must be wallet2.
  • configuration (optional) — Static key & DID:
    • staticKey — Key object associated with the wallet.
    • staticDid — DID string associated with the wallet.

Path Parameters

  • target — {organizationID}.{tenantID}.{walletID}, e.g. waltid.tenant1.wallet1.

Response Codes

  • 201 — Wallet2 created successfully.

Attach Service Dependencies to Wallet2 After Creation

Attach KMS, DID store, credential store, client-attester, or policy-store after creation:

CURL

Endpoint: POST /v2/{target}/wallet-service-api/dependencies/add | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v2/{target}/wallet-service-api/dependencies/add' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "dependency": "waltid.tenant1.credential-store-1"
}'

Path Parameters

  • target — {organizationID}.{tenantID}.{walletServiceID}, e.g. waltid.tenant1.wallet1.

Body Parameters

  • dependency — Resource ID of the dependency to link.

Response Codes

  • 201 — Dependency attached.
Last updated on August 18, 2026
OverviewWallet Management