Environment variables

Lerian SPI is Lerian’s native messaging integration for Pix. It reaches BACEN’s instant-payment system (SPI) and the DICT key directory over the RSFN. It ships four runtime binaries (spi, dict, brcode, and core), so its variable set is broad. The service reads every variable at startup. When systemplane is on (the default), it can override a subset at runtime without a restart. The rest of the variables need a restart to change. For the knobs that behave the same across every Lerian Go service (deployment posture, datastores, telemetry, streaming), see BYOC configuration essentials. In the tables below, Required marks a variable you must set, always (Yes) or under the condition named. — means no default. The conditions use three terms:

Live: the BACEN endpoint uses https. A local environment also accepts an http endpoint.
Local environment: ENV_NAME is development, local, or test.
Protected environment: ENV_NAME is production, prod, staging, stage, pre-prod, preprod, pre-production, or preproduction.

Most BACEN-facing variables carry a surface prefix: BACEN_SPI_* for the SPI settlement transport, BACEN_DICT_* for the DICT client, BACEN_BRCODE_JOSE_* for BR Code JOSE signing, and BACEN_ICOM_* for the inbound long-poll channel.

Runtime and server

Variable	Description	Default	Required
`ENV_NAME`	Runtime environment label. When unset, it resolves to `development`. An explicit `none` is invalid.	`development`	No
`LOG_LEVEL`	Log verbosity (`debug`, `info`, `warn`, `error`).	`info`	No
`SERVER_ADDRESS`	Main HTTP listen address (`host:port` or `:port`). Liveness, readiness, and systemplane bind this port.	`:8080`	No
`HTTP_BODY_LIMIT_BYTES`	Maximum request body size in bytes.	`1048576`	No
`PUBLIC_BASE_URL`	Externally reachable base URL of the service. It builds the BR Code payload links and the URL of the JWS key set.	—	In a protected environment or if BR Code JOSE is enabled
`ACCESS_CONTROL_ALLOW_ORIGIN`	Allowed CORS origins. A protected environment refuses a wildcard.	`http://localhost:3000`	No
`ACCESS_CONTROL_ALLOW_METHODS`	Allowed CORS methods.	`GET,POST,PUT,PATCH,DELETE,OPTIONS`	No
`ACCESS_CONTROL_ALLOW_HEADERS`	Allowed CORS request headers.	(standard set)	No
`TRUSTED_PROXIES`	Comma-separated proxy IPs or CIDRs trusted to set the real client IP. Wildcards are refused.	—	In a protected environment with `TLS_TERMINATED_UPSTREAM=true`
`SERVER_TLS_CERT_FILE`	Path to the server TLS certificate. Set together with the key file.	—	No
`SERVER_TLS_KEY_FILE`	Path to the server TLS private key. Sensitive.	—	No
`SERVER_TLS_CLIENT_CA_FILE`	CA file for verifying client certificates (mutual TLS). Requires the certificate and key files.	—	No
`TLS_TERMINATED_UPSTREAM`	Set `true` when TLS is terminated by a load balancer or reverse proxy.	`false`	No

A protected environment requires the server certificate and key files, or TLS_TERMINATED_UPSTREAM=true.

Authentication

Lerian SPI authorizes protected routes, including the systemplane admin API, through Access Manager.

Variable	Description	Default	Required
`AUTH_ENABLED`	Require Access Manager authentication on protected routes. Set `true` or `false`. A blank value stops startup. `false` starts only when `ENV_NAME` is `development`, `develop`, `dev`, `local`, or `test`, and never with `DEPLOYMENT_MODE=saas`.	—	Yes
`PLUGIN_AUTH_ADDRESS`	Access Manager service address. A protected environment requires `https://`.	—	If `AUTH_ENABLED=true` or in a protected environment

BACEN callback (inbound from SPI)

Variable	Description	Default	Required
`BACEN_CALLBACK_TRUSTED_PROXY_CIDRS`	CIDRs trusted as the source of BACEN callbacks. Set together with the header secret.	—	With the header secret
`BACEN_CALLBACK_MTLS_HEADER_SECRET`	Shared secret proving the upstream terminated the callback mutual TLS. At least 32 characters. Sensitive.	—	If an ICOM consumer is enabled

Outside a local environment, the rail needs exactly one callback mutual-TLS mode. In direct mode, set SERVER_TLS_CERT_FILE, SERVER_TLS_KEY_FILE, and SERVER_TLS_CLIENT_CA_FILE. In proxy mode, set TLS_TERMINATED_UPSTREAM=true, the trusted CIDRs, and the header secret.

SPI settlement transport (`BACEN_SPI_*`)

Connection to BACEN’s SPI settlement endpoint over the RSFN, with the secondary messaging channel and the file-transfer (ARQ) endpoint.

Variable	Description	Default	Required
`BACEN_SPI_ENDPOINT`	Primary SPI endpoint URL.	`http://localhost:9900`	Outside a local environment
`BACEN_SPI_SECONDARY_ENDPOINT`	Secondary messaging channel URL. The rail sends `pain.013`, `pain.014`, `camt.025`, and `trck.002` on this channel. When it is unset, those sends fail.	—	If the secondary ICOM consumer is enabled
`BACEN_ARQ_ENDPOINT`	BACEN file-transfer endpoint URL. The rail fetches large statement files from it.	—	No
`BACEN_SPI_PARTICIPANT_ISPB`	The participant’s 8-digit ISPB for the SPI surface.	—	When live or if an ICOM consumer is enabled
`BACEN_SPI_ALLOWED_ENDPOINT_HOSTS`	Allow-list of hosts the SPI client may reach (SSRF guard). It must include the endpoint host.	—	Outside a local environment
`BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS`	Allow-list for the secondary endpoint.	—	No
`BACEN_ARQ_ALLOWED_ENDPOINT_HOSTS`	Allow-list for the ARQ endpoint.	—	No
`BACEN_SPI_TIMEOUT_SEC`	Request timeout (seconds).	`30`	No
`BACEN_SPI_INITIATION_TIMEOUT_MS`	Payment-initiation timeout (milliseconds).	`150`	No
`BACEN_SPI_RETRY_ATTEMPTS`	Retry attempts on transport failure.	`3`	No
`BACEN_SPI_RETRY_INITIAL_BACKOFF_MS`	Initial retry backoff (milliseconds).	`500`	No
`BACEN_SPI_RETRY_MAX_BACKOFF_MS`	Maximum retry backoff (milliseconds).	`5000`	No
`BACEN_SPI_OUTBOUND_QUOTA_ENABLED`	Enable client-side outbound rate quota. Must be `true` outside a local environment.	`false`	Outside a local environment
`BACEN_SPI_OUTBOUND_QUOTA_LIMIT`	Sustained outbound quota (requests per second). Must be positive.	—	If quota enabled
`BACEN_SPI_OUTBOUND_QUOTA_BURST`	Burst allowance above the quota. Must be positive.	—	If quota enabled
`BACEN_SPI_CATALOGUE_VERSION`	BACEN SPI message-catalogue version.	`5.12.1`	No
`BACEN_SPI_XSD_DIR`	Directory of the bundled BACEN XSD schemas for the catalogue.	Bundled path	No
`BACEN_SPI_CATALOGUE_ROOT`	Override root for the message catalogue.	—	No
`BACEN_SPI_INTERNAL_CALLBACK_SECRET`	Shared secret for the internal callback path. At least 32 characters when set. Sensitive.	—	In a protected environment or if an ICOM consumer is enabled

mutual TLS to BACEN

The BACEN_TLS_* files back the mutual-TLS channel to BACEN. The SPI and DICT clients share them.

Variable	Description	Default	Required
`BACEN_TLS_CERT_FILE`	Client certificate presented to BACEN.	—	When live
`BACEN_TLS_KEY_FILE`	Client private key. Sensitive.	—	When live
`BACEN_TLS_CA_FILE`	CA bundle used to verify BACEN’s server certificate.	—	When live

Message signing and certificates

Lerian SPI digitally signs its outbound messages. Pick a custody backend with BACEN_SPI_SIGNER_KIND.

Variable	Description	Default	Required
`BACEN_SPI_SIGNER_KIND`	Signing custody backend: `file`, `pkcs11`, or `kmip`. A protected environment refuses `file`.	`file`	In a protected environment
`BACEN_SPI_SIGNER_COMMON_NAME`	Expected common name of the signing certificate.	—	Outside a local environment
`BACEN_SPI_SIGNING_CERT_FILE`	Path to the certificate bound to the signing key.	—	If `pkcs11` or `kmip`
`BACEN_SPI_VERIFY_CERT_FILE`	Certificate bundle used to verify BACEN’s signature on inbound messages.	—	When live
`BACEN_SPI_INBOUND_SIGNER_COMMON_NAME`	Expected common name of the signer on inbound messages.	—	Outside a local environment
`CERT_READINESS_MIN_DAYS`	Minimum days-to-expiry before the certificate readiness check reports degraded.	`14`	No
`BACEN_SPI_PKCS11_MODULE_PATH`	PKCS#11 module library path.	—	If `pkcs11`
`BACEN_SPI_PKCS11_TOKEN_LABEL`	PKCS#11 token label.	—	If `pkcs11`
`BACEN_SPI_PKCS11_PIN_FILE`	Path to a file holding the token PIN. Sensitive.	—	If `pkcs11`
`BACEN_SPI_PKCS11_KEY_LABEL`	Signing-key label on the token.	—	If `pkcs11`
`BACEN_SPI_KMIP_BASE_URL`	KMIP service base URL.	—	If `kmip`
`BACEN_SPI_KMIP_VHSM`	Virtual HSM identifier.	—	If `kmip`
`BACEN_SPI_KMIP_CRYPTO_USER`	KMIP crypto user.	—	If `kmip`
`BACEN_SPI_KMIP_CRYPTO_USER_TOKEN`	KMIP crypto-user token. Sensitive.	—	If `kmip`
`BACEN_SPI_KMIP_SIGN_PRIVATE_KEY_UID`	UID of the signing private key.	—	If `kmip`
`BACEN_SPI_KMIP_SIGN_PUBLIC_KEY_UID`	UID of the signing public key.	—	If `kmip`
`BACEN_SPI_KMIP_DIGEST_INFO_PREFIX`	Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.	`false`	No

Certificate validation (OCSP/CRL)

Variable	Description	Default	Required
`BACEN_SPI_OCSP_MODE`	Certificate revocation-check mode: `soft_fail`, `hard_fail`, or `disabled`. A protected environment refuses `disabled`.	`soft_fail`	No
`BACEN_SPI_OCSP_TIMEOUT_MS`	OCSP request timeout (milliseconds).	`3000`	No
`BACEN_SPI_OCSP_CACHE_TTL_CAP_SEC`	Cap on cached OCSP response TTL (seconds).	`3600`	No
`BACEN_SPI_OCSP_CRL_CACHE_TTL_SEC`	CRL cache TTL (seconds).	`3600`	No

Payload resolver

These variables control how the service stores and references large SPI payloads.

Variable	Description	Default	Required
`BACEN_SPI_PAYLOAD_RESOLVER_KIND`	Payload storage backend: `in_memory` or `postgres`. A protected environment refuses `in_memory`.	`in_memory`	In a protected environment
`BACEN_SPI_PAYLOAD_RESOLVER_IN_MEMORY_MAX_BYTES`	Max bytes held by the in-memory resolver.	`134217728`	No
`BACEN_SPI_PAYLOAD_RESOLVER_TTL_SEC`	Retention TTL for resolved payloads (seconds).	`86400`	No
`BACEN_SPI_PAYLOAD_RESOLVER_ENCRYPTION_KEY`	AES-256 key for encrypting stored payloads. Sensitive.	—	If kind is `postgres`

Inbound channel (`BACEN_ICOM_*`)

Long-poll channel for messages BACEN pushes back to the participant.

Variable	Description	Default	Required
`BACEN_ICOM_BASE_URL`	Inbound channel base URL.	—	If the primary ICOM consumer is enabled
`BACEN_ICOM_ISPB`	Participant ISPB for the inbound channel. It must equal `BACEN_SPI_PARTICIPANT_ISPB`.	—	If an ICOM consumer is enabled
`BACEN_ICOM_CONSUMER_ENABLED`	Enable the primary inbound consumer.	`false`	No
`BACEN_ICOM_SECONDARY_CONSUMER_ENABLED`	Enable the secondary inbound consumer.	`false`	No
`BACEN_ICOM_LONGPOLL_TIMEOUT_MS`	Long-poll wait timeout (milliseconds).	`90000`	No

Either consumer requires a configured persistence backend, BACEN_ICOM_ISPB, BACEN_SPI_INTERNAL_CALLBACK_SECRET, and BACEN_CALLBACK_MTLS_HEADER_SECRET. The primary consumer also requires BACEN_ICOM_BASE_URL. The secondary consumer also requires BACEN_SPI_SECONDARY_ENDPOINT.

DICT client (`BACEN_DICT_*`)

Client for BACEN’s Pix key directory (DICT), including the NP endpoint for batch key-existence checks.

Variable	Description	Default	Required
`BACEN_DICT_ENDPOINT`	DICT endpoint URL.	`http://localhost:9900`	Outside a local environment
`BACEN_DICT_PARTICIPANT_ISPB`	Participant ISPB for the DICT surface.	—	Outside a local environment
`BACEN_DICT_ALLOWED_ENDPOINT_HOSTS`	Allow-list of hosts the DICT client may reach. It must include the endpoint host.	—	Outside a local environment
`BACEN_DICT_TIMEOUT_SEC`	DICT request timeout (seconds).	`10`	No
`BACEN_DICT_NP_ENDPOINT`	NP endpoint URL for batch key-existence checks. When it is unset, the batch check answers `501`.	—	No
`BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS`	Allow-list for the NP endpoint.	—	No
`BACEN_DICT_SIGNER_KIND`	DICT signing custody backend: `file`, `pkcs11`, or `kmip`.	`file`	No
`BACEN_DICT_SIGNING_CERT_FILE`	Path to the DICT signing certificate.	—	For the selected DICT custody path
`BACEN_DICT_SIGNING_KEY_FILE`	Path to the DICT signing private key (file backend). Sensitive.	—	If `file`
`BACEN_DICT_VERIFY_CERT_FILE`	Certificate used to verify DICT responses.	—	When live
`BACEN_DICT_PKCS11_MODULE_PATH`	PKCS#11 module path.	—	If `pkcs11`
`BACEN_DICT_PKCS11_TOKEN_LABEL`	PKCS#11 token label.	—	If `pkcs11`
`BACEN_DICT_PKCS11_PIN_FILE`	Path to the token PIN file. Sensitive.	—	If `pkcs11`
`BACEN_DICT_PKCS11_KEY_LABEL`	Signing-key label on the token.	—	If `pkcs11`
`BACEN_DICT_KMIP_BASE_URL`	KMIP service base URL.	—	If `kmip`
`BACEN_DICT_KMIP_VHSM`	Virtual HSM identifier.	—	If `kmip`
`BACEN_DICT_KMIP_CRYPTO_USER`	KMIP crypto user.	—	If `kmip`
`BACEN_DICT_KMIP_CRYPTO_USER_TOKEN`	KMIP crypto-user token. Sensitive.	—	If `kmip`
`BACEN_DICT_KMIP_SIGN_PRIVATE_KEY_UID`	UID of the signing private key.	—	If `kmip`
`BACEN_DICT_KMIP_SIGN_PUBLIC_KEY_UID`	UID of the signing public key.	—	If `kmip`
`BACEN_DICT_KMIP_DIGEST_INFO_PREFIX`	Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.	`false`	No
`BACEN_DICT_INTENT_ENCRYPTION_KEY`	AES-256 key that encrypts pending DICT requests (key deletions and claim operations) before storage. Sensitive.	—	In a protected environment
`BACEN_DICT_OUTBOUND_QUOTA_ENABLED`	Enable the client-side DICT request quota. `false` starts only in a local environment.	`true`	No
`BACEN_DICT_ENTRIES_READ_CATEGORY`	The participant’s DICT entry-read category, a letter from `A` to `H`.	—	For the `dict` binary while the quota is enabled
`BACEN_DICT_SPONSORED_ENTRIES_READ_CATEGORIES`	Entry-read categories of sponsored participants, as `ispb:letter` pairs. A participant without a pair uses `H`.	—	No
`BACEN_DICT_QUERY_MONITOR_ENABLED`	Enable the DICT query monitor. `false` starts only in a local environment. Its thresholds have defaults.	`true`	No

BR Code JOSE signing (`BACEN_BRCODE_JOSE_*`)

Signs dynamic BR Code payloads (JWS). When BACEN_BRCODE_JOSE_SIGNER_KIND is unset, JOSE is disabled and the public payload endpoints refuse to serve.

Variable	Description	Default	Required
`BACEN_BRCODE_JOSE_SIGNER_KIND`	JOSE signing custody backend: `file`, `pkcs11`, or `kmip`.	—	No
`BACEN_BRCODE_JOSE_SIGNING_CERT_FILE`	Path to the JOSE signing certificate.	—	If BR Code JOSE is enabled
`BACEN_BRCODE_JOSE_SIGNING_KEY_FILE`	Path to the JOSE signing private key (file backend). Sensitive.	—	If BR Code JOSE is enabled with `file`
`BACEN_BRCODE_JOSE_KID`	JWS key identifier (`kid`) header value.	—	If BR Code JOSE is enabled
`BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH`	PKCS#11 module path.	—	If BR Code JOSE is enabled with `pkcs11`
`BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL`	PKCS#11 token label.	—	If BR Code JOSE is enabled with `pkcs11`
`BACEN_BRCODE_JOSE_PKCS11_PIN_FILE`	Path to the token PIN file. Sensitive.	—	If BR Code JOSE is enabled with `pkcs11`
`BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL`	Signing-key label on the token.	—	If BR Code JOSE is enabled with `pkcs11`
`BACEN_BRCODE_JOSE_KMIP_BASE_URL`	KMIP service base URL.	—	If BR Code JOSE is enabled with `kmip`
`BACEN_BRCODE_JOSE_KMIP_VHSM`	Virtual HSM identifier.	—	If BR Code JOSE is enabled with `kmip`
`BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER`	KMIP crypto user.	—	If BR Code JOSE is enabled with `kmip`
`BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN`	KMIP crypto-user token. Sensitive.	—	If BR Code JOSE is enabled with `kmip`
`BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID`	UID of the signing private key.	—	If BR Code JOSE is enabled with `kmip`
`BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID`	UID of the signing public key.	—	If BR Code JOSE is enabled with `kmip`
`BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX`	Prepend the ASN.1 DigestInfo prefix before the KMIP sign call.	`false`	No

PII encryption and hashing

Every variable below holds sensitive key or pepper material. It protects personal data at rest through encryption and blind indexing. Never commit or log a value. Inject it at deploy time through your secret manager. A pepper or key rotation requires a planned re-index or re-encryption.

Each key is 32 bytes, raw or base64. Each pepper has at least 32 characters.

Variable	Description	Default	Required
`DICT_KEY_PII_ENCRYPTION_KEY`	AES key for DICT key-holder PII. Sensitive.	—	`dict` binary in a protected environment
`DICT_KEY_BLIND_INDEX_PEPPER`	Pepper for blind-indexing DICT key PII. Sensitive.	—	`dict` binary in a protected environment
`DICT_AUDIT_HASH_PEPPER`	Pepper for DICT audit-record hashing. Sensitive.	—	In a protected environment, or for the `dict` binary outside a local environment
`AUDIT_HASH_PEPPER`	Fallback audit-hash pepper, read only when `DICT_AUDIT_HASH_PEPPER` is unset. Sensitive.	—	No
`SPI_RESPONSIBLES_ENCRYPTION_KEY`	AES key for responsible-party PII. Sensitive.	—	`spi` binary in a protected environment
`SPI_OPERATIONS_PII_ENCRYPTION_KEY`	AES-256 key for operation PII. Sensitive.	—	Yes, for the `spi` binary
`SPI_OPERATIONS_BLIND_INDEX_PEPPER`	Pepper for blind-indexing operation PII. Sensitive.	—	Yes, for the `spi` binary
`BRCODE_PII_ENCRYPTION_KEY`	AES key for BR Code PII. Sensitive.	—	`brcode` binary in a protected environment
`BRCODE_PII_BLIND_INDEX_PEPPER`	Pepper for blind-indexing BR Code PII. Sensitive.	—	`brcode` binary in a protected environment

PostgreSQL

Variable	Description	Default	Required
`POSTGRES_HOST`	Primary PostgreSQL host.	`localhost`	Yes
`POSTGRES_PORT`	Primary PostgreSQL port.	`5432`	No
`POSTGRES_USER`	Database user.	`brspi`	No
`POSTGRES_PASSWORD`	Database password. Sensitive. Use an explicit secret in a protected environment.	In-code development password	No
`POSTGRES_DB`	Database name.	`brspi`	No
`POSTGRES_SSLMODE`	libpq TLS mode. A protected environment refuses `disable`. Use `verify-full` with a trusted CA for remote connections. `require` encrypts the channel but does not verify the server identity.	`disable`	In a protected environment
`POSTGRES_MAX_OPEN_CONNS`	Maximum open connections.	`25`	No
`POSTGRES_MAX_IDLE_CONNS`	Maximum idle connections.	`5`	No
`POSTGRES_CONN_MAX_LIFETIME_MINS`	Connection max lifetime (minutes).	`30`	No
`POSTGRES_CONN_MAX_IDLE_TIME_MINS`	Connection max idle time (minutes).	`5`	No
`POSTGRES_CONNECT_TIMEOUT_SEC`	Connection timeout (seconds).	`10`	No
`POSTGRES_REPLICA_HOST`	Optional read-replica host. The service uses the replica only when its host and port are both set.	—	No
`POSTGRES_REPLICA_PORT`	Replica port.	—	No
`POSTGRES_REPLICA_USER`	Replica user.	—	No
`POSTGRES_REPLICA_PASSWORD`	Replica password. Sensitive.	—	No
`POSTGRES_REPLICA_DB`	Replica database name.	—	No
`POSTGRES_REPLICA_SSLMODE`	Replica TLS mode. When unset, the replica uses the primary’s mode.	—	No

Redis

Variable	Description	Default	Required
`REDIS_HOST`	Redis host and port.	`localhost:6379`	No
`REDIS_MASTER_NAME`	Sentinel master name (if using Sentinel).	—	No
`REDIS_PASSWORD`	Redis password. Sensitive.	—	No
`REDIS_DB`	Redis database number.	`0`	No
`REDIS_PROTOCOL`	Redis protocol version (2 or 3).	`3`	No
`REDIS_TLS`	Enable TLS to Redis.	`false`	No
`REDIS_CA_CERT`	CA certificate for Redis TLS.	—	If `REDIS_TLS=true`
`REDIS_POOL_SIZE`	Connection pool size.	`10`	No
`REDIS_MIN_IDLE_CONNS`	Minimum idle connections.	`2`	No
`REDIS_READ_TIMEOUT_MS`	Read timeout (milliseconds).	`3000`	No
`REDIS_WRITE_TIMEOUT_MS`	Write timeout (milliseconds).	`3000`	No
`REDIS_DIAL_TIMEOUT_MS`	Dial timeout (milliseconds).	`5000`	No

Outbox and streaming

Lerian SPI publishes events through a transactional outbox and a streaming producer, and consumes settlement events for BR Code. The BR Code settlement consumer runs unconditionally. Streaming has no enable switch: STREAMING_BROKERS is required at startup, including when OUTBOX_ENABLED=false. Each binary requires its own fixed STREAMING_CLOUDEVENTS_SOURCE value, and any other value stops startup. Use the value that Lerian supplies for each binary. Configure STREAMING_COMPRESSION, STREAMING_REQUIRED_ACKS, and STREAMING_EVENT_POLICIES as described in Streaming and outbox.

Variable	Description	Default	Required
`OUTBOX_ENABLED`	Enable the transactional outbox dispatcher. Must be `true` for the `spi`, `dict`, and `brcode` binaries in a protected environment.	`true`	No
`OUTBOX_DISPATCH_INTERVAL_MS`	Interval between dispatch cycles (milliseconds).	`2000`	No
`OUTBOX_BATCH_SIZE`	Rows drained per dispatch cycle.	`50`	No
`OUTBOX_MAX_DISPATCH_ATTEMPTS`	Dispatch attempts before an event is parked.	`10`	No
`OUTBOX_PROCESSING_TIMEOUT_MS`	Per-batch processing timeout (milliseconds).	`600000`	No
`OUTBOX_RETRY_WINDOW_MS`	Retry window before a stuck row is reclaimed (milliseconds).	`300000`	No
`SPI_PARTICIPANT_CONSUMER_ENABLED`	Enable the Core-to-SPI participant-request consumer. It subscribes to the Core producer’s application stream; the topic is derived and not configurable. It requires `STREAMING_BROKERS`, BACEN transport, and persistence when enabled.	`false`	No
`CORE_PARTICIPANT_CONSUMER_ENABLED`	Enable the Core consumer that applies participant confirmations from the SPI binary.	`false`	No
`CORE_SETTLEMENT_COMPLETION_CONSUMER_ENABLED`	Enable the Core consumer that moves a settlement from `PENDING` to `SETTLED`.	`false`	No
`CORE_SETTLEMENT_TERMINATION_CONSUMER_ENABLED`	Enable the Core consumer that applies returns and failures to settlements.	`false`	No

Schedulers

Background jobs, each with its own switch. The four DICT jobs that default to true carry regulatory duties, so the dict binary starts its scheduler for them unless SCHEDULER_ENABLED=false. The jobs that default to false also need SCHEDULER_ENABLED=true. DICT discovery and inventory workers have their own controls in the next section.

Variable	Description	Default	Required
`SCHEDULER_ENABLED`	Master switch for the scheduler subsystem. An explicit `false` stops every job below.	`false`	No
`SCHEDULER_CLAIM_DEADLINE_ENABLED`	Run the DICT claim-deadline job.	`true`	No
`SCHEDULER_INBOUND_DISCOVERY_ENABLED`	Run the DICT claim discovery walks, for the donor and the claimer sides.	`true`	No
`SCHEDULER_INBOUND_DISCOVERY_MAX_STALENESS_MINUTES`	Readiness staleness threshold for the claim discovery walks. Must be greater than zero.	`15`	No
`SCHEDULER_DICT_RECONCILIATION_INCREMENTAL_ENABLED`	Run the daily DICT reconciliation, at 02:00 Brasília time.	`true`	No
`SCHEDULER_DICT_RECONCILIATION_FULL_ENABLED`	Run the weekly full DICT reconciliation, on Sunday at 03:00 Brasília time.	`true`	No
`SCHEDULER_QUOTA_RESET_ENABLED`	Run the daily participant-quota reset in Core, at midnight Brasília time.	`false`	No
`SCHEDULER_DICT_AUDIT_RETENTION_ENABLED`	Run the DICT audit-log retention purge.	`false`	No
`SCHEDULER_APPROVAL_EXPIRY_ENABLED`	Every 5 minutes, move expired approval requests to `EXPIRED`.	`false`	No
`SCHEDULER_PORTABILITY_DEADLINE_ENABLED`	Every 5 minutes, mark portability operations whose 24-hour deadline has passed. It never confirms them.	`false`	No

DICT discovery and inventory

The workers below run independently of SCHEDULER_ENABLED, each with its own switch.

Variable	Description	Default	Required
`DICT_FUNDS_RECOVERY_EVENTS_ENABLED`	Enable the DICT funds-recovery event feed.	`true`	No
`DICT_FUNDS_RECOVERY_EVENTS_MAX_STALENESS_MINUTES`	Readiness staleness threshold for the funds-recovery event feed.	`15`	No
`DICT_FUNDS_RECOVERY_EVENTS_GAP_BLOCK_HOURS`	Gap threshold after which the funds-recovery event feed records a blocked marker. Must be greater than zero.	`168`	No
`DICT_INFRACTION_DISCOVERY_ENABLED`	Enable the DICT infraction discovery walk.	`true`	No
`DICT_INFRACTION_DISCOVERY_MAX_STALENESS_MINUTES`	Readiness staleness threshold for infraction discovery. Must be greater than zero.	`15`	No
`DICT_REFUND_DISCOVERY_ENABLED`	Enable the DICT refund discovery walks.	`true`	No
`DICT_REFUND_DISCOVERY_MAX_STALENESS_MINUTES`	Readiness staleness threshold for refund discovery. Must be greater than zero.	`15`	No
`DICT_PERSON_WATCHLIST_ENABLED`	Enable polling for documents in the DICT person watchlist.	`true`	No
`DICT_PERSON_WATCHLIST_CADENCE_MINUTES`	Minimum age before a watched document is observed again. Must be greater than zero.	`60`	No
`DICT_PERSON_WATCHLIST_BATCH_LIMIT`	Maximum watched documents observed in one polling tick. Must be greater than zero.	`100`	No
`DICT_PERSON_WATCHLIST_MAX_DOCUMENTS_PER_PARTICIPANT`	Maximum active watched documents per participant. Must be greater than zero.	`500`	No
`DICT_PERSON_WATCHLIST_MAX_OBSERVATION_AGE_MINUTES`	Readiness threshold for the oldest watched document observation. Must be greater than zero.	`360`	No
`DICT_PERSON_WATCHLIST_QUARANTINE_AFTER_FAILURES`	Consecutive failed observations before a watched document is quarantined. Must be greater than zero.	`6`	No
`DICT_FRAUD_MARKER_INVENTORY_ENABLED`	Enable the DICT fraud-marker inventory sweep.	`true`	No
`DICT_FRAUD_MARKER_INVENTORY_SWEEP_MINUTES`	Interval between fraud-marker inventory sweeps. Must be greater than zero.	`60`	No
`DICT_FRAUD_MARKER_INVENTORY_MAX_DOCUMENTS_PER_SWEEP`	Maximum documents reconciled in one inventory sweep. Must be greater than zero.	`200`	No
`DICT_FRAUD_MARKER_INVENTORY_MAX_STALENESS_MINUTES`	Readiness staleness threshold for the fraud-marker inventory. Must be greater than zero.	`180`	No

Rate limiting, idempotency, and connectivity

Variable	Description	Default	Required
`RATE_LIMIT_ENABLED`	Enable request rate limiting. Forced on in a protected environment.	`true`	No
`RATE_LIMIT_MAX`	Maximum requests per window.	`100`	No
`RATE_LIMIT_EXPIRY_SEC`	Rate-limit window (seconds).	`60`	No
`IDEMPOTENCY_RETRY_WINDOW_SEC`	How long (seconds) an idempotency key is retained.	`86400`	No
`IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY`	AES-256 key for encrypting stored idempotency responses. Sensitive.	—	Yes
`INFRA_CONNECT_TIMEOUT_SEC`	Connect timeout for infrastructure dependencies at startup (seconds).	`30`	No

Systemplane and runtime configuration

Variable	Description	Default	Required
`SYSTEMPLANE_ENABLED`	Enable the systemplane runtime-configuration admin API, mounted at `/v1/system` on the main port. When `false`, the service runs in env-only mode with no admin plane. SPI defaults this on.	`true`	No

See Systemplane for the API, namespaces, and required permissions.

Observability

Variable	Description	Default	Required
`ENABLE_TELEMETRY`	Enable OpenTelemetry tracing and metrics.	`false`	No
`TELEMETRY_REQUIRED`	Fail startup if telemetry cannot initialize.	`false`	No
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP collector endpoint.	`localhost:4317`	If telemetry enabled
`OTEL_RESOURCE_SERVICE_NAME`	Service name attached to exported telemetry.	Service default	No
`OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT`	Deployment environment label.	`development`	No
`OTEL_LIBRARY_NAME`	Instrumentation library name.	Service default	No
`METRICS_PROMETHEUS_ENABLED`	Expose a dedicated Prometheus scrape endpoint.	`false`	No
`METRICS_PROMETHEUS_ADDRESS`	Listen address for the Prometheus endpoint. Binds loopback by default.	`127.0.0.1:9090`	No

Documentation

Variable	Description	Default	Required
`SWAGGER_ENABLED`	Serve the OpenAPI spec and API docs UI. Forced off in a protected environment.	`false`	No

Health and readiness

Lerian SPI exposes GET /health (liveness), GET /readyz (readiness), and GET /version on the main HTTP port. /metrics runs on its own listener when enabled. See Health and readiness for the probe contract.

​Runtime and server

​Authentication

​BACEN callback (inbound from SPI)

​SPI settlement transport (BACEN_SPI_*)

​mutual TLS to BACEN

​Message signing and certificates

​Certificate validation (OCSP/CRL)

​Payload resolver

​Inbound channel (BACEN_ICOM_*)

​DICT client (BACEN_DICT_*)

​BR Code JOSE signing (BACEN_BRCODE_JOSE_*)

​PII encryption and hashing

​PostgreSQL

​Redis

​Outbox and streaming

​Schedulers

​DICT discovery and inventory

​Rate limiting, idempotency, and connectivity

​Systemplane and runtime configuration

​Observability

​Documentation

​Health and readiness

Runtime and server

Authentication

BACEN callback (inbound from SPI)

SPI settlement transport (`BACEN_SPI_*`)

mutual TLS to BACEN

Message signing and certificates

Certificate validation (OCSP/CRL)

Payload resolver

Inbound channel (`BACEN_ICOM_*`)

DICT client (`BACEN_DICT_*`)

BR Code JOSE signing (`BACEN_BRCODE_JOSE_*`)

PII encryption and hashing

PostgreSQL

Redis

Outbox and streaming

Schedulers

DICT discovery and inventory

Rate limiting, idempotency, and connectivity

Systemplane and runtime configuration

Observability

Documentation

Health and readiness