---
title: "Architecture"
description: "Learn how the walt.id Wallet SDK, sample apps, and Wallet API v2 share one holder core."
stack: "Community Stack (open source) — version 1.1.1"
stack_version: "1.1.1"
stack_comparison: https://docs.walt.id/community-vs-enterprise.md
canonical_url: https://docs.walt.id/community-stack/mobile-wallet/architecture
generated: 2026-10-01
---
# Architecture

This page explains how the walt.id Wallet SDK is assembled: a shared holder core, a mobile facade, a Swift API, sample apps, and the custodial Wallet API v2.

The Wallet SDK is a **headless holder stack**. Your app owns screens, branding, and consent UX. The SDK owns protocol sessions, credential matching, keys, and storage.

## Product Boundaries

```mermaid
flowchart LR
  Core[openid4vc-wallet core]
  Mobile[Mobile SDK]
  Swift[Swift WalletSDK]
  Server["Wallet API v2"]
  Compose[Compose demo]
  NativeIos[Native iOS demo]
  Core --> Mobile
  Core --> Server
  Mobile --> Swift
  Mobile --> Compose
  Swift --> NativeIos
```

| Piece | Role |
|---|---|
| **Core library** | Framework-agnostic [OID4VCI 1.0](https://docs.walt.id/concepts/data-exchange-protocols/openid4vci.md) and [OID4VP 1.0](https://docs.walt.id/concepts/data-exchange-protocols/openid4vp.md) holder logic, including [DCQL](https://docs.walt.id/concepts/data-exchange-protocols/dcql.md) matching. |
| **Mobile SDK** | Android and Kotlin Multiplatform facade: sessions, encrypted persistence, platform keys, proximity, and Digital Credentials API hooks. |
| **Swift WalletSDK** | Native `async`/`await` iOS API over the same mobile module. |
| **Wallet API v2** | Custodial HTTP surface that uses the same core. Community and Enterprise share this holder logic. |
| **Sample apps** | Reference shells that prove the integration. Replace the UI; keep the SDK. |

## When to Use Which Surface

- **Mobile SDK** — You are embedding a non-custodial wallet in an Android or iOS app. Keys stay on the device.
- **Wallet API v2** — You are building a custodial or server-held wallet, a web wallet, or a Wallet-as-a-Service backend.
- **Sample apps** — You want a working wallet to try [Portal2](https://portal2.demo.walt.id), white-label a shell, or copy an integration pattern.

The demo apps own PIN lock, brand colours, QR rendering, and permission prompts. Those are not Wallet SDK APIs. Session state, matching, reader trust, and credential storage stay in the SDK.

## Next Steps

- **Try a sample app** — [Try the Demo](https://docs.walt.id/community-stack/mobile-wallet/try-the-demo.md).
- **Create a wallet in your app** — [Integrate the SDK](https://docs.walt.id/community-stack/mobile-wallet/integrate-the-sdk.md).
- **Use the custodial HTTP wallet** — [Wallet API v2 Getting Started](https://docs.walt.id/community-stack/wallet2/getting-started.md).