Skip to main content
This page lists every environment variable read by the qc-custody binary, with its default and a one-line description. Source of truth: custody/config/config.go. All variables are prefixed CUSTODY_. They may be set in the process environment, in a .env file, or via your orchestrator’s secret-injection mechanism.

​
Server

VariableDefaultDescription
CUSTODY_SERVER_HOST0.0.0.0Bind address
CUSTODY_SERVER_PORT8080HTTP API port
CUSTODY_METRICS_PORT9090Prometheus metrics port
CUSTODY_SERVER_READ_TIMEOUT30sHTTP read timeout
CUSTODY_SERVER_WRITE_TIMEOUT30sHTTP write timeout
CUSTODY_SERVER_SHUTDOWN_TIMEOUT15sGraceful shutdown deadline
CUSTODY_SERVER_REQUEST_TIMEOUT30sPer-request timeout

​
Database

VariableDefaultDescription
CUSTODY_DB_HOSTlocalhostPostgreSQL host
CUSTODY_DB_PORT5432PostgreSQL port
CUSTODY_DB_NAMEqc_custodyDatabase name
CUSTODY_DB_USERcustodyDatabase user
CUSTODY_DB_PASSWORD(required unless IAM auth)Database password
CUSTODY_DB_SSLMODEverify-fullTLS mode; use disable only for local dev
CUSTODY_DB_SSL_ROOT_CERT—Path to CA cert (RDS)
CUSTODY_DB_MAX_OPEN_CONNS25Pool max
CUSTODY_DB_MAX_IDLE_CONNS5Pool idle
CUSTODY_DB_CONN_MAX_LIFETIME5mConnection lifetime
CUSTODY_DB_MIGRATE_ON_STARTtrueAuto-run schema migrations
CUSTODY_DB_IAM_AUTHfalseUse AWS RDS IAM auth (skips password)
CUSTODY_DB_READ_REPLICA_ENABLEDfalseRoute reads to replica
CUSTODY_DB_READ_HOST—Replica host
CUSTODY_DB_READ_PORT5432Replica port

​
Quantum Chain node

VariableDefaultDescription
CUSTODY_NODE_RPC_URLhttp://localhost:8545HTTP JSON-RPC endpoint (required)
CUSTODY_NODE_WS_URLws://localhost:8546WebSocket endpoint (deposit watching)
CUSTODY_NODE_BACKUP_RPC_URLS—Comma-separated failover endpoints
CUSTODY_NODE_DIAL_TIMEOUT10sConnection dial timeout
CUSTODY_NODE_REQUEST_TIMEOUT15sPer-request timeout
CUSTODY_NODE_HEALTH_CHECK_INTERVAL30sHealth-check cadence

​
Chain

VariableDefaultDescription
CUSTODY_CHAIN_ID20803Chain ID
CUSTODY_CONFIRMATION_DEPTH12Blocks before a tx is CONFIRMED
CUSTODY_CONFIRMATION_POLL_INTERVAL5sConfirmation poll interval
CUSTODY_SIGNING_PAYLOAD_TTL10mHow long a PENDING_SIGNATURE payload is valid

​
Authentication and SSO

VariableDefaultDescription
CUSTODY_AUTH_ENABLEDtrueRequire bearer auth
CUSTODY_WEBHOOK_SIGNING_KEY—HMAC key for webhook signatures (required in prod)
CUSTODY_SSO_ENABLEDfalseEnable SSO/OIDC
CUSTODY_SSO_JWT_SIGNING_KEY—HMAC-SHA256 key for SSO tokens (required if SSO)
CUSTODY_SSO_ACCESS_TOKEN_TTL15mAccess-token lifetime
CUSTODY_SSO_REFRESH_TOKEN_TTL24hRefresh-token lifetime
CUSTODY_SSO_ALLOWED_ISSUERS—Comma-separated OIDC issuer URLs
CUSTODY_SSO_AUTO_PROVISIONtrueAuto-create users on first SSO login
CUSTODY_SSO_DEFAULT_ROLEviewerRole assigned to auto-provisioned users

​
Webhooks

VariableDefaultDescription
CUSTODY_WEBHOOK_MAX_RETRIES5Per-delivery retry budget
CUSTODY_WEBHOOK_RETRY_BASE_DELAY10sInitial backoff
CUSTODY_WEBHOOK_RETRY_MAX_DELAY1hMax backoff
CUSTODY_WEBHOOK_DELIVERY_TIMEOUT10sPer-delivery HTTP timeout
CUSTODY_WEBHOOK_WORKER_COUNT4Concurrent delivery workers
CUSTODY_WEBHOOK_ENCRYPTION_KEY—64 hex chars (32 bytes) for AES-256-GCM at-rest encryption of webhook secrets

​
Signer

CUSTODY_SIGNER_* variables also accept CUSTODY_ENQLAVE_* aliases. If both are set, CUSTODY_SIGNER_* wins.
VariableDefaultDescription
CUSTODY_SIGNER_TYPEcallbackOne of callback, remote, grpc
CUSTODY_SIGNER_BACKENDenqlaveenqlave or qey (only for grpc)
CUSTODY_SIGNER_ENDPOINT—Remote signer HTTPS URL
CUSTODY_SIGNER_API_KEY—Remote signer bearer token
CUSTODY_SIGNER_GRPC_TARGET—Signer gRPC host:port (required if type=grpc)
CUSTODY_SIGNER_GRPC_TLS_CERT—Server TLS cert (one-way TLS)
CUSTODY_SIGNER_GRPC_CLIENT_CERT—Client cert for mTLS
CUSTODY_SIGNER_GRPC_CLIENT_KEY—Client private key for mTLS
CUSTODY_SIGNER_GRPC_CA_CERT—CA cert verifying the signer
CUSTODY_SIGNER_GRPC_TIMEOUT30sPer-call timeout
CUSTODY_SIGNER_GRPC_MAX_RECV_MSG_SIZE0Max gRPC response in bytes (0 = default 64 KB)
CUSTODY_SIGNER_KEYGEN_MODElocallocal or qey (Qey-side keygen requires backend=qey)

​
RBAC

VariableDefaultDescription
CUSTODY_RBAC_ENABLEDfalseEnforce role-based access control
CUSTODY_RBAC_SEED_ON_STARTUPtrueSeed system roles on first boot

​
Rate limiting

VariableDefaultDescription
CUSTODY_RATE_LIMIT_ENABLEDtrueEnable rate limiter
CUSTODY_RATE_LIMIT_RPM120Requests per minute per key
CUSTODY_RATE_LIMIT_BURST20Burst size
CUSTODY_RATE_LIMIT_REDIS_URL—Redis URL; enables distributed limiting

​
Telemetry (OpenTelemetry)

VariableDefaultDescription
CUSTODY_OTEL_ENABLEDfalseEmit traces
CUSTODY_OTEL_ENDPOINT—OTLP endpoint (e.g. otel-collector:4317)
CUSTODY_OTEL_SERVICE_NAMEqc-custodyService name
CUSTODY_OTEL_INSECUREfalseDisable TLS to collector
CUSTODY_OTEL_SAMPLE_RATE1.0Sample fraction (0.0–1.0)

​
Secrets provider

VariableDefaultDescription
CUSTODY_SECRETS_PROVIDERenvenv or aws
CUSTODY_SECRETS_AWS_REGION—Region for AWS Secrets Manager
CUSTODY_SECRETS_CACHE_TTL5mLocal cache TTL

​
Compliance / AML

VariableDefaultDescription
CUSTODY_COMPLIANCE_ENABLEDfalseEnable AML pre-broadcast screening
CUSTODY_COMPLIANCE_PROVIDERnoopnoop, chainalysis, or shuftipro
CUSTODY_CHAINALYSIS_API_KEY—Chainalysis API key (required if provider)
CUSTODY_CHAINALYSIS_BASE_URLhttps://api.chainalysis.com/api/kyt/v2Chainalysis endpoint
CUSTODY_CHAINALYSIS_TIMEOUT30sPer-call timeout
CUSTODY_SHUFTIPRO_CLIENT_ID—Shufti Pro client ID
CUSTODY_SHUFTIPRO_SECRET_KEY—Shufti Pro secret
CUSTODY_SHUFTIPRO_BASE_URLhttps://api.shuftipro.comShufti Pro endpoint
CUSTODY_SHUFTIPRO_CALLBACK_URL—Public URL for async callbacks
CUSTODY_SHUFTIPRO_TIMEOUT30sPer-call timeout
CUSTODY_SHUFTIPRO_ONGOINGfalseEnable ongoing monitoring

​
Validation rules

The service refuses to start if:
  • CUSTODY_DB_PASSWORD is empty and CUSTODY_DB_IAM_AUTH=false.
  • CUSTODY_NODE_RPC_URL is empty.
  • CUSTODY_SSO_ENABLED=true and CUSTODY_SSO_JWT_SIGNING_KEY is empty.
  • CUSTODY_COMPLIANCE_PROVIDER=shuftipro and either CUSTODY_SHUFTIPRO_CLIENT_ID or CUSTODY_SHUFTIPRO_SECRET_KEY is empty.
  • CUSTODY_COMPLIANCE_PROVIDER=chainalysis and CUSTODY_CHAINALYSIS_API_KEY is empty.
  • CUSTODY_SIGNER_TYPE=grpc and CUSTODY_SIGNER_GRPC_TARGET is empty.
  • CUSTODY_SIGNER_BACKEND is not enqlave or qey.
  • CUSTODY_SIGNER_BACKEND=qey and CUSTODY_SIGNER_TYPE is not grpc.
  • CUSTODY_SIGNER_KEYGEN_MODE is not local or qey.
  • CUSTODY_SIGNER_KEYGEN_MODE=qey and CUSTODY_SIGNER_BACKEND is not qey.
  • CUSTODY_WEBHOOK_ENCRYPTION_KEY is set but is not exactly 64 hex chars.