Documentation/canton-network-docs/Wallet GatewaySet up & operateView on canton-network-docs ↗
canton-network-docs/Wallet GatewaySet up & operate

Configure the Wallet Gateway

The Wallet Gateway reads a single JSON configuration file that defines who the Wallet Gateway is, how it serves requests, where it persists data, and which networks and identity providers it starts with. This guide covers the file’s structure and the kernel, server, and store sections. For networks and authentication, see Networks & identity providers. For an exhaustive field reference, see the Configuration reference.

​
Generate a starting point

Write an example configuration you can edit: 
wallet-gateway --config-example > config.json
To see the full JSON Schema (useful for validation and IDE autocompletion): 
wallet-gateway --config-schema

​
File structure

The configuration file has five top-level sections:
SectionRequiredPurpose
kernelyesIdentity of this Wallet Gateway instance, served to dApps.
serveryesNetwork binding, ports, API paths, and the admin user.
storeyesDatabase connection for sessions, wallets, networks, IDPs, and transactions.
bootstrapyesNetworks and identity providers seeded on first run.
signingStorenoSecondary database for keys when using internal signing.
A minimal configuration for a local setup looks like this: 
{
    "kernel": {
        "id": "remote-da",
        "clientType": "remote"
    },
    "server": {
        "port": 3030,
        "dappPath": "/api/v0/dapp",
        "userPath": "/api/v0/user",
        "allowedOrigins": ["http://localhost:8080"],
        "admin": "operator"
    },
    "store": {
        "connection": {
            "type": "sqlite",
            "database": "store.sqlite"
        }
    },
    "bootstrap": {
        "idps": [],
        "networks": []
    }
}
Fill in bootstrap.idps and bootstrap.networks following Networks & identity providers.

​
Kernel

The kernel section identifies this Wallet Gateway instance to dApps.
  • id (required): a stable, unique identifier, for example "my-gateway-prod".
  • clientType (required): "remote" for a remote Wallet Gateway.
  • publicUrl (optional): the base URL used to redirect clients. If omitted, it is derived from the server host and port. Set this when running behind a reverse proxy or load balancer.
{
    "kernel": {
        "id": "my-production-gateway",
        "clientType": "remote",
        "publicUrl": "https://wallet.example.com"
    }
}

​
Server

The server section configures binding, ports, and API paths.
  • port (optional, default 3030): the port the server binds to. Also used to generate popup URLs in the discovery flow.
  • dappPath (optional, default /api/v0/dapp): the path where dApps connect.
  • userPath (optional, default /api/v0/user): the path used by the User UI and User API.
  • allowedOrigins (optional, default ["*"]): CORS allowed origins. In production, list exact origins instead of "*".
  • requestSizeLimit (optional, default "1mb"): maximum request body size.
  • requestRateLimit (optional, default 10000): maximum requests per minute per IP (health endpoints excluded).
  • admin (optional): the user ID (JWT sub claim) granted admin privileges, which allow managing networks and identity providers at runtime. If omitted, network and IDP management is restricted to the bootstrap configuration.
{
    "server": {
        "port": 3030,
        "dappPath": "/api/v0/dapp",
        "userPath": "/api/v0/user",
        "allowedOrigins": ["https://my-dapp.example.com"],
        "requestSizeLimit": "10mb",
        "requestRateLimit": 10000,
        "admin": "operator"
    }
}

​
Store

The store connection determines where the Wallet Gateway persists sessions, wallet configurations, networks, identity providers, and in-flight transactions. Three backends are available:
BackendUse forPersistence
memoryQuick testingLost on restart.
sqliteLocal developmentPersists to a file.
postgresProduction and testReliable, scalable, backup-friendly.
{
    "store": {
        "connection": {
            "type": "postgres",
            "host": "db.example.com",
            "port": 5432,
            "user": "wallet_gateway",
            "password": "secure-password",
            "database": "wallet_gateway_db"
        }
    }
}
With the memory store in Docker or Kubernetes, all data is lost when the container or pod is recreated. sqlite persists only if the database file is on a persistent volume. Use postgres for production. See the Configuration reference for backup guidance.

​
Signing store

The optional signingStore is a secondary database used only when the Wallet Gateway signs transactions itself (the internal signing provider). It uses the same connection options as store. Omit it entirely when using a participant node or an external custody provider. 
{
    "signingStore": {
        "connection": {
            "type": "sqlite",
            "database": "signingStore.sqlite"
        }
    }
}
The internal signing provider stores private keys in the signing store database. Do not use it in production systems with valuable assets. See Signing providers.

​
Next steps

Networks & identity providers

Connect to a validator and configure authentication.

Configuration reference

Every field, all auth methods, and per-environment guidance.