Configuration reference

This reference complements the task-oriented guides with the details you need for production: the store backends in full, backup and recovery, signing store security, and how to handle secrets across environments. For the config file’s overall shape, see Configure the Wallet Gateway. For networks and authentication, see Networks & identity providers.

Store backends

The store.connection object selects one of three backends.

PostgreSQL

Recommended for production for its robustness, concurrent access, and backup support.

Field	Required	Description
`type`	yes	Must be `"postgres"`.
`host`	yes	Hostname or IP of the PostgreSQL server.
`port`	no (default `5432`)	Port PostgreSQL listens on.
`user`	yes	Database user to connect with.
`password`	yes	Password for the database user.
`database`	yes	Name of the database to use (must exist).

{
    "store": {
        "connection": {
            "type": "postgres",
            "host": "db.example.com",
            "port": 5432,
            "user": "wallet_gateway",
            "password": "secure-password",
            "database": "wallet_gateway_db"
        }
    }
}

SQLite

Suitable for single-instance deployments and local development. Stores all data in one file.

Field	Required	Description
`type`	yes	Must be `"sqlite"`.
`database`	yes	Path to the SQLite database file.

{
    "store": {
        "connection": {
            "type": "sqlite",
            "database": "store.sqlite"
        }
    }
}

Memory

Keeps all data in RAM. Useful for testing, not for production.

Field	Required	Description
`type`	yes	Must be `"memory"`.

{
    "store": {
        "connection": {
            "type": "memory"
        }
    }
}

Backups and recovery

The store database holds user sessions, networks and IDPs (seeded from bootstrap, then modifiable at runtime), wallet configurations and party mappings, and in-flight transactions. If the database is lost and cannot be restored:

All sessions are invalidated (users must log in again).
Networks and IDPs are re-seeded from bootstrap, but runtime changes are lost.
In-flight transactions are lost and may need manual intervention.
Wallets referencing lost networks may need reconfiguration.

Recommendations:

PostgreSQL: use pg_dump or an automated solution (pgBackRest, WAL-E).
SQLite: copy the database file regularly, with no writes during the copy.
Schedule automated daily backups with a retention policy, and test restores.

If the Wallet Gateway is used as the signing provider, the signing store holds private keys. If it is lost, those keys are unrecoverable. Do not use internal signing for any important system. See Signing providers.

Signing store security

The optional signingStore uses the same connection options as store and is only needed for the internal signing provider. When it holds keys:

Store the file in a secure location with restricted access.
Use strict filesystem permissions (for example chmod 600 for SQLite files).
For PostgreSQL, use separate credentials with minimal privileges.
Consider encrypting the database at rest.
Back it up regularly if it holds production keys.
Never commit signing store files to version control.

Secrets and environments

Maintain separate configuration files per environment (for example config.dev.json, config.staging.json, config.prod.json) to isolate settings and credentials. Never commit secrets. Override sensitive values with environment variables using the Env suffix on the field, for example clientSecretEnv:

{
    "bootstrap": {
        "networks": [
            {
                "auth": {
                    "clientSecretEnv": "OAUTH_CLIENT_SECRET"
                }
            }
        ]
    }
}

Then set the variable when running:

export OAUTH_CLIENT_SECRET="my-secret"
wallet-gateway -c ./config.json

Additional guidance:

Network and IDP configurations (excluding secrets) are visible to users with ledger access.
Anyone with read access to a shared config repository can see non-secret configuration.
Use environment variables or a secret manager (HashiCorp Vault, AWS Secrets Manager) for sensitive values.
adminAuth credentials are sensitive: store them securely, rotate them regularly, and use them only where truly needed.

Suggested environment profiles

Setting	Development	Production
Store	SQLite or memory	PostgreSQL
Authentication	Self-signed	OAuth
Network endpoints	Localhost	Production endpoints
CORS	Permissive	Restricted to known origins
Secrets	Inline (non-sensitive)	Environment variables or secret manager

Overview

Wallet Gateway

Wallets and Exchanges

Ecosystem

Release Notes

Store backends

PostgreSQL

SQLite

Memory

Backups and recovery

Signing store security

Secrets and environments

Suggested environment profiles

​Store backends

​PostgreSQL

​SQLite

​Memory

​Backups and recovery

​Signing store security

​Secrets and environments

​Suggested environment profiles

Store backends

PostgreSQL

SQLite

Memory

Backups and recovery

Signing store security

Secrets and environments

Suggested environment profiles