Setup

There are two ways to set up a new wallet (wallet-service):

  • Wizard-based setup: Use the Wallet Service wizard to automatically create a wallet instance and configure the necessary dependency services (e.g., KMS, DID Store, Credential Store). This setup not only enables core wallet functionality—such as receiving and sharing credentials—but also ensures that credentials, keys, and DIDs are associated and stored for the wallet.
  • Manual setup: Create a standalone wallet service without any dependency services to enable core wallet functionality, such as receiving credentials via OID4VC and presenting them via OID4VP. Optionally, you can provide a static key and DID to associate with the wallet — ideal if the wallet only needs to have a single key and DID. With that there is no requirement for a DID store or KMS. If needed, you can also manually attach services like KMS, DID service, DID store, or a credential store to support multiple keys and DIDs, and to persist (store) received credentials.

Each Wallet Service instance corresponds to a single wallet identified by a unique ID, known as a target ( e.g., waltid.tenant1.wallet1).

Creating a Wallet with Dependencies (Wizard)


The Role of Dependency Services

Dependency services ensure that the wallet goes beyond basic, stateless functionality—such as receiving credentials via OID4VC without storing them, or presenting credentials via OID4VP by supplying the raw credential instead of a stored reference.

These services provide the necessary infrastructure for persistence and full-featured wallet capabilities:

  • KMS Service – Provides the wallet with keys needed to receive credentials and to sign credential presentations.
  • DID Service – Enables the wallet to create one or more decentralized identifiers (DIDs).
  • DID Store – Persists the DID Documents of the created DIDs.
  • Credential Store – Stores received credentials so they can be viewed, managed, and later retrieved for presentation.

Create New Service Dependencies

In this example, we will create a wallet and initialize all dependency services like KMS, DID Service, DID Store Service, and Credential Store Service. If you already have created some of these services, please refer to the Link Existing Service Dependencies Example.

CURL

Endpoint: /v1/{target}/wallet-service-api/init-wallet | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/wallet-service-api/init-wallet' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "createKms": true,
  "kmsName": "my-custom-kms-name",
  "createKeyInKms": {
    "backend": "jwk",
    "keyType": "Ed25519"
  },
  "createDidStore": true,
  "didStoreName": "my-custom-did-store-name",
  "createDidService": true,
  "didServiceName": "my-custom-did-service-name",
  "createDidWithDidService": "jwk",
  "createCredentialStore": true,
  "credentialStoreName": "my-custom-credential-store-name"
}'

Body

{
  "createKms": true,
  "kmsName": "my-custom-kms-name",
  "createKeyInKms": {
    "backend": "jwk",
    "keyType": "Ed25519"
  },
  "createDidStore": true,
  "didStoreName": "my-custom-did-store-name",
  "createDidService": true,
  "didServiceName": "my-custom-did-service-name",
  "createDidWithDidService": "jwk",
  "createCredentialStore": true,
  "credentialStoreName": "my-custom-credential-store-name"
}

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant in which to create the new wallet ( wallet service) and the wallet's ID ({organizationID}.{tenantID}.[walletID]), e.g. waltid.tenant1.wallet1

Body Parameters

  • createKms Boolean - Specifies whether a new KMS service should be created.
  • kmsName (optional) String - Custom name for the KMS service. This will be the last part of the resource ID. For example, waltid.tenant1.{kms-name}.
  • createKeyInKms (optional) Object - Object defining the key to create in the KMS. It follows the same structure as the create key request in the KMS service. Learn more about the different options here.
  • createDidStore Boolean - Indicates whether a DID Store Service should be created.
  • didStoreName (optional) String - Custom name for the DID Store Service. This will form part of the resource ID. For example, waltid.tenant1.{did-store-name}.
  • createDidService Boolean - Specifies if a DID Service should be created.
  • didServiceName (optional) String - Custom name for the DID Service. This will be included in the resource ID. For example, waltid.tenant1.{did-service-name}.
  • createDidWithDidService (optional) String - Method for creating a DID in the DID Service. Supported values: jwk orkey
  • createCredentialStore Boolean - Indicates whether a Credential Store Service should be created.
  • credentialStoreName (optional) String - Custom name for the Credential Store Service. This will be part of the resource ID. For example, waltid.tenant1.{credential-store-name}.

Response Codes

  • 201 - Wallet created successfully.

Body

{
  "dependencies": [
    "waltid.tenant1.my-custom-did-store-name-test-1",
    "waltid.tenant1.my-custom-did-service-name-test-1",
    "waltid.tenant1.my-custom-kms-name-test-1",
    "waltid.tenant1.my-custom-credential-store-name-test-1"
  ],
  "traversable": true,
  "_id": "waltid.tenant1.wallet-test-1",
  "configuration": {},
  "parent": "waltid.tenant1"
}

Link Existing Service Dependencies

In this example, we will create a wallet and link existing dependency services like KMS, DID Service, DID Store Service, and Credential Store Service.

CURL

Endpoint: /v1/{target}/wallet-service-api/init-wallet | API Reference

Example Request

curl -X 'POST' \
  'https://{orgID}.enterprise-sandbox.waltid.dev/v1/{target}/wallet-service-api/init-wallet' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {yourToken}' \
  -H 'Content-Type: application/json' \
  -d '{
  "kms": "waltid.tenant1.my-custom-kms-name-test-1",
  "createKms": false,
  "didStore": "waltid.tenant1.my-custom-did-store-name-test-1",
  "createDidStore": false,
  "didService": "waltid.tenant1.my-custom-did-service-name-test-1",
  "createDidService": false,
  "credentialStore": "waltid.tenant1.my-custom-credential-store-name-test-1",
  "createCredentialStore": false
}'

Body

{
  "kms": "waltid.tenant1.my-custom-kms-name-test-1",
  "createKms": false,
  "didStore": "waltid.tenant1.my-custom-did-store-name-test-1",
  "createDidStore": false,
  "didService": "waltid.tenant1.my-custom-did-service-name-test-1",
  "createDidService": false,
  "credentialStore": "waltid.tenant1.my-custom-credential-store-name-test-1",
  "createCredentialStore": false
}

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant in which to create the new wallet ( wallet service) and the wallet's ID ({organizationID}.{tenantID}.[walletID]), e.g. waltid.tenant1.wallet1

Body Parameters

  • kms Target - Resource ID (target) of the KMS to link to the wallet, e.g. waltid.tenant1.kms1.
  • createKms Boolean - Specifies whether a new KMS service should be created.
  • didStore Target - Resource ID (target) of the DID Store to link to the wallet, e.g. waltid.tenant1.did-store1.
  • createDidStore Boolean - Indicates whether a DID Store Service should be created.
  • didService Target - Resource ID (target) of the DID Service to link to the wallet, e.g. waltid.tenant1.did-service1.
  • createDidService Boolean - Specifies if a DID Service should be created.
  • credentialStore Target - Resource ID (target) of the Credential Store Service to link to the wallet, e.g. waltid.tenant1.credential-store1.
  • createCredentialStore Boolean - Indicates whether a Credential Store Service should be created. resource ID. For example, waltid.tenant1.{credential-store-name}.

Response Codes

  • 201 - Wallet created successfully.

Body

{
  "dependencies": [
    "waltid.tenant1.my-custom-did-store-name-test-1",
    "waltid.tenant1.my-custom-did-service-name-test-1",
    "waltid.tenant1.my-custom-kms-name-test-1",
    "waltid.tenant1.my-custom-credential-store-name-test-1"
  ],
  "traversable": true,
  "_id": "waltid.tenant1.wallet-test-2",
  "configuration": {},
  "parent": "waltid.tenant1"
}
  • 401 - Invalid authentication

Creating a Wallet without Dependencies

In this example, we will create a wallet without any dependency services (KMS, DID service, DID Store, Credential Store). Optionally, we can provide a static key and DID to be associated with the wallet.

With this setup (with static key and DID), the wallet is still capable of receiving and presenting credentials. However, it will not store them, since no credential store is attached. Similarly, the DID document related to the static DID must be stored separately, as there is no DID store connected.

Despite this minimal setup (static key and DID), it is still possible to manually attach other services like a credential store or DID store, as described in the section below.

CURL

Endpoint: /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": "wallet",
  "configuration": {
    "staticKey": {
      "type": "jwk",
      "jwk": {
        "kty": "OKP",
        "d": "wZ69WYFIZHYEC9gWsRYCIHsJ4G5qdZeCrCry6szGij4",
        "crv": "Ed25519",
        "kid": "I-bh2IYP93feK_dIYA7QaNSHoRlftw53KYpNYPdEpNQ",
        "x": "sD8DqvgzEjQaex5p4NNp_Qyd8knJAJfZY7Ge8vCmBGY"
      }
    },
    "staticDid": "did:key:z6MkrKFXimvdRgYnsFeyQq5sUn4vmXJVDHriHJKpgy6oaC6H"
  }
}'

Body

{
  "type": "wallet",
  "configuration": {
    "staticKey": {
      "type": "jwk",
      "jwk": {
        "kty": "OKP",
        "d": "wZ69WYFIZHYEC9gWsRYCIHsJ4G5qdZeCrCry6szGij4",
        "crv": "Ed25519",
        "kid": "I-bh2IYP93feK_dIYA7QaNSHoRlftw53KYpNYPdEpNQ",
        "x": "sD8DqvgzEjQaex5p4NNp_Qyd8knJAJfZY7Ge8vCmBGY"
      }
    },
    "staticDid": "did:key:z6MkrKFXimvdRgYnsFeyQq5sUn4vmXJVDHriHJKpgy6oaC6H"
  }
}

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant in which to create the new wallet ( wallet service) and the wallet's ID ({organizationID}.{tenantID}.[walletID]), e.g. waltid.tenant1.wallet1

Body Parameters

  • type serviceType - Specifies the type of service to create. In our case wallet
  • configuration (optional) Object - Object to configure static key & DID.
    • staticKey Key - A key object that specifies the key to be associated with the wallet. Its structure matches the format returned under the key property when creating a key using the KMS service.
    • staticDid String - String of the DID to be associated with the wallet.

Response Codes

  • 201 - Wallet created successfully.

Attach Service Dependencies to Wallet After Creation

In the example below, we will attach a credential store service to an existing wallet to ensure that received credentials are automatically stored. The same approach can be used to attach other services as needed, such as a KMS service, DID service, or DID store service.

CURL

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

Example Request

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

Body

waltid.tenant1.credential-store-1

Path Parameters

  • orgID: - When performing operations within an organization, it is essential to use the organization's Base URL or another valid host alias. For example, if your organization is named test, your default Base URL will be test.enterprise-sandbox.walt.dev when using the sandbox environment.
  • target: resourceIdentifier - The target indicates the organization + tenant + wallet service to which to add an existing Credential Store ({organizationID}.{tenantID}.{walletServiceID}), e.g. waltid.tenant1.wallet1

Body Parameters

  • Specifies the ID of the Credential store that should be linked.

Response Codes

  • 201 - Unit attached.
OverviewOverview