Configuration

Complete environment variable reference and configuration guide for CreditNexus

Quick Setup

Get started with minimal configuration

External Services

Configure Twilio, DigiSigner, and more

Overview

CreditNexus uses environment variables for all configuration. Create a .env file in the project root directory with your settings. All sensitive values (API keys, secrets) are stored as SecretStr types in Pydantic settings for security.

Configuration File: app/core/config.py

---

LLM Provider Configuration

CreditNexus supports multiple LLM providers: OpenAI (default), vLLM, and HuggingFace. You can also use local models with HuggingFace.

OpenAI Configuration

Required for all providers (used as fallback):

OPENAI_API_KEY · string · required

Your OpenAI API key. Get from https://platform.openai.com/api-keys

LLM_PROVIDER · string

LLM provider: "openai", "vllm", or "huggingface". Default: "openai"

LLM_MODEL · string

Model identifier. OpenAI: "gpt-4o", "gpt-4o-mini", "gpt-3.5-turbo". Default: "gpt-4o"

LLM_TEMPERATURE · float

Temperature for generation (0.0 = deterministic, 1.0 = creative). Default: 0.0

Code Reference: app/core/llm_client.py - get_chat_model()

vLLM Configuration

For self-hosted vLLM servers:

VLLM_BASE_URL · string

Base URL for your vLLM server (e.g., "http://localhost:8000")

VLLM_API_KEY · string

Optional API key if your vLLM server requires authentication

Example:

LLM_PROVIDER=vllm
VLLM_BASE_URL=http://localhost:8000
LLM_MODEL=meta-llama/Llama-3.1-8B-Instruct

HuggingFace Configuration

HuggingFace supports both inference endpoints (API-based) and local models.

HUGGINGFACE_API_KEY · string

HuggingFace API token. Get from https://huggingface.co/settings/tokens

HUGGINGFACE_BASE_URL · string

Custom base URL. Default: https://api-inference.huggingface.co/v1

For Inference Providers router: https://router.huggingface.co/{provider}/v3/openai

HUGGINGFACE_INFERENCE_PROVIDER · string

Inference provider selection. Options:

• "auto" (default): Selects first available provider from your preferences
• "novita", "together", "sambanova", "fireworks-ai", "cohere", "fal-ai", "groq", "replicate", "hf-inference", "black-forest-labs", "cerebras", "featherless-ai", "hyperbolic", "nebius", "novita", "nscale", "openai"

Default: "novita" (preferred provider)

HUGGINGFACE_USE_LOCAL · boolean

Set to true to load models locally using transformers (requires GPU/CPU resources). Set to false to use inference endpoints (API-based, no local resources needed).

Default: false

Recommended Models for Novita:

• meta-llama/Llama-3.1-8B-Instruct
• microsoft/Phi-3.5-mini-instruct
• deepseek-ai/DeepSeek-V3.2-Exp

Code Reference: app/core/llm_client.py - get_chat_model()

---

Embeddings Configuration

EMBEDDINGS_MODEL · string

Embeddings model identifier.

OpenAI: "text-embedding-3-small", "text-embedding-3-large", "text-embedding-ada-002"

HuggingFace: "sentence-transformers/all-MiniLM-L6-v2" (22.7M params, lightweight), "BAAI/bge-small-en-v1.5" (33.4M params)

Default: "text-embedding-3-small"

EMBEDDINGS_PROVIDER · string

Embeddings provider: "openai", "huggingface", or leave empty to use LLM_PROVIDER.

Default: "huggingface"

EMBEDDINGS_USE_LOCAL · boolean

Use local embeddings model instead of API (HuggingFace only). Default: false

EMBEDDINGS_DEVICE · string

Device for local embeddings: "cpu", "cuda", "cuda:0", or "auto". Default: "cpu"

EMBEDDINGS_MODEL_KWARGS · string

Additional model kwargs as JSON string. Examples:

• '{"device_map":"auto"}'
• '{"trust_remote_code":true}'
• '{"device":"cuda","model_kwargs":{"torch_dtype":"float16"}}'

Code Reference: app/core/llm_client.py - get_embeddings_model()

---

SentinelHub Configuration

SentinelHub provides satellite imagery for verification workflows.

SENTINELHUB_KEY · string

SentinelHub OAuth client ID. Get from https://www.sentinel-hub.com/

SENTINELHUB_SECRET · string

SentinelHub OAuth client secret. Get from https://www.sentinel-hub.com/

Setup Guide: See SentinelHub Setup Guide

Code Reference: app/agents/verifier.py

---

Policy Engine Configuration

POLICY_ENABLED · boolean

Enable policy engine for real-time compliance enforcement. Default: true

POLICY_RULES_DIR · string

Directory containing policy rule YAML files. Default: app/policies

POLICY_RULES_PATTERN · string

File pattern for policy rules. Default: *.yaml

POLICY_ENGINE_VENDOR · string

Policy engine vendor (optional). Default: "" (uses default engine)

POLICY_AUTO_RELOAD · boolean

Auto-reload policy rules on file changes (development only). Default: false

Code Reference: app/core/policy_config.py, app/services/policy_service.py

---

Agent Workflows Configuration

CreditNexus includes three AI agent workflows: LangAlpha (quantitative analysis), DeepResearch (iterative web research), and PeopleHub (business intelligence). Configure API keys and settings for each workflow.

LangAlpha Configuration

LangAlpha performs quantitative financial analysis using multiple specialized agents.

POLYGON_API_KEY · string

Polygon.io API key for market data. Get from https://polygon.io/

Required for: Market data fetching, ticker snapshots, historical data

ALPHA_VANTAGE_API_KEY · string

Alpha Vantage API key for fundamental data. Get from https://www.alphavantage.co/support/#api-key

Required for: Company fundamentals, financial statements, earnings data

TAVILY_API_KEY · string

Tavily API key for news/search. Get from https://tavily.com/

Optional: Falls back to WebSearchService if not configured

TICKERTICK_API_KEY · string

Tickertick API key for financial news.

Optional: Service may not be publicly available. Falls back to web_search tool or Tavily.

LLM Model Configuration:

LANGALPHA_REASONING_MODEL · string

LLM model for reasoning tasks (supervisor, planner, analyst). Default: "gpt-4o"

LANGALPHA_BASIC_MODEL · string

LLM model for basic tasks (researcher, reporter, market). Default: "gpt-4o-mini"

LANGALPHA_ECONOMIC_MODEL · string

LLM model for economic analysis tasks. Default: "gpt-4o-mini"

LANGALPHA_CODING_MODEL · string

LLM model for coding/calculation tasks. Default: "gpt-4o"

LANGALPHA_BUDGET_LEVEL · string

Budget level for LangAlpha agents: "low", "medium", or "high". Default: "medium"

• low: Uses cheaper models, fewer iterations
• medium: Balanced cost and quality
• high: Uses premium models, more thorough analysis

Code Reference: app/workflows/langalpha_graph.py, app/services/quantitative_analysis_service.py

Feature Documentation: Agent Workflows

DeepResearch Configuration

DeepResearch performs iterative web research with knowledge accumulation.

SERPER_API_KEY · string

Serper API key for Google search. Get from https://serper.dev/

Optional: Falls back to WebSearchService if not configured

WebSearchService Configuration:

WEB_SEARCH_RATE_LIMIT · integer

Web search rate limit (requests per hour). Default: 360

WEB_SEARCH_CACHE_ENABLED · boolean

Enable caching for web search results. Default: true

WEB_SEARCH_CACHE_TTL_HOURS · integer

Web search cache TTL in hours. Default: 24

Code Reference: app/agents/deep_research_agent.py, app/services/deep_research_service.py

Feature Documentation: Agent Workflows

Reranking Configuration

Reranking improves search result quality by reordering results based on relevance.

RERANKING_USE_LOCAL · boolean

Use local reranking model (True) or remote API (False). Default: true

Local: Uses sentence-transformers CrossEncoder (requires GPU/CPU resources) Remote: Uses API-based reranking (e.g., Cohere, Jina)

RERANKING_MODEL · string

Local reranking model identifier (HuggingFace model ID). Default: "BAAI/bge-reranker-base"

Alternatives:

• "BAAI/bge-reranker-large" (better quality)
• "cross-encoder/ms-marco-MiniLM-L-6-v2" (faster)

RERANKING_DEVICE · string

Device for local reranking: "cpu", "cuda", "cuda:0", etc. Default: "cpu"

RERANKING_API_URL · string

Remote reranking API URL (only needed if RERANKING_USE_LOCAL=false).

Examples:

• Cohere: https://api.cohere.ai/v1/rerank
• Jina: https://api.jina.ai/v1/rerank

RERANKING_API_KEY · string

Remote reranking API key (only needed if using remote reranking)

Code Reference: app/services/web_search_service.py

PeopleHub Configuration

PeopleHub provides business intelligence and psychometric analysis.

No additional API keys required - Uses existing WebSearchService and LLM configuration.

Code Reference: app/workflows/peoplehub_research_graph.py, app/services/digitizer_chatbot_service.py

Feature Documentation: Agent Workflows

Agent Dashboard Configuration

The Agent Dashboard requires no additional configuration - it automatically displays results from all agent workflows.

Code Reference: client/src/apps/agent-dashboard/AgentDashboard.tsx

Feature Documentation: Agent Workflows

---

Database Configuration

DATABASE_URL · string · required

PostgreSQL connection string:

Format: postgresql://user:password@localhost:5432/creditnexus

For SQLite (development fallback): sqlite:///./creditnexus.db

DATABASE_ENABLED · boolean

Enable database connection. Default: true

Database SSL/TLS Configuration

For production, SSL/TLS encryption is required:

DB_SSL_REQUIRED · boolean

Require SSL/TLS for database connections. Default: false (development), true (production)

DB_SSL_MODE · string

SSL mode: "prefer", "require", "verify-ca", "verify-full". Default: "prefer"

DB_SSL_CERT · string

Path to SSL client certificate file (optional)

DB_SSL_KEY · string

Path to SSL client key file (optional)

DB_SSL_CA_CERT · string

Path to SSL CA certificate file (required for verify-ca and verify-full modes)

DB_SSL_AUTO_GENERATE · boolean

Automatically generate self-signed certificates for development. Default: false

DB_SSL_AUTO_GENERATE_CA · boolean

Auto-generate CA certificate. Default: true (when DB_SSL_AUTO_GENERATE=true)

DB_SSL_AUTO_GENERATE_CLIENT · boolean

Auto-generate client certificate for mutual TLS. Default: false

DB_SSL_AUTO_CERT_DIR · string

Certificate directory for auto-generated certificates. Default: "./ssl_certs/db"

DB_SSL_AUTO_CERT_VALIDITY_DAYS · integer

Certificate validity period in days. Default: 365

Setup Guide: See Database SSL Setup Guide and SSL Troubleshooting Guide

Code Reference: app/core/config.py, app/db/ssl_config.py

---

Authentication Configuration

JWT_SECRET_KEY · string · required

Secret key for JWT token generation. Generate a secure random string.

Security: Never commit this to version control!

JWT_ALGORITHM · string

JWT algorithm. Default: "HS256"

JWT_ACCESS_TOKEN_EXPIRE_MINUTES · integer

Access token expiration in minutes. Default: 30

JWT_REFRESH_TOKEN_EXPIRE_DAYS · integer

Refresh token expiration in days. Default: 7

Code Reference: app/auth/jwt_auth.py

---

Twilio Configuration (Loan Recovery)

Twilio integration enables SMS and voice communication for loan recovery workflows.

TWILIO_ENABLED · boolean

Enable Twilio integration. Default: false

TWILIO_ACCOUNT_SID · string

Twilio Account SID. Get from https://console.twilio.com/

TWILIO_AUTH_TOKEN · string

Twilio Auth Token. Get from https://console.twilio.com/

Security: Never commit this to version control!

TWILIO_PHONE_NUMBER · string

Twilio phone number in E.164 format (e.g., [phone]).

Purchase from https://console.twilio.com/us1/develop/phone-numbers/manage/search

TWILIO_SMS_ENABLED · boolean

Enable SMS functionality. Default: true

TWILIO_VOICE_ENABLED · boolean

Enable voice call functionality. Default: true

TWILIO_WEBHOOK_URL · string

Webhook URL for Twilio status callbacks.

Format: https://your-domain.com/api/twilio/webhook/status

For local development with tunneling: https://your-tunnel-url.loca.lt/api/twilio/webhook/status

Setup Guide: See Twilio Setup Guide

Code Reference: app/services/twilio_service.py, app/services/loan_recovery_service.py

---

DigiSigner Configuration (Digital Signatures)

DIGISIGNER_API_KEY · string

DigiSigner API key. Get from https://www.digisigner.com/

DIGISIGNER_BASE_URL · string

DigiSigner API base URL. Default: https://api.digisigner.com/v1

DIGISIGNER_WEBHOOK_SECRET · string

Webhook secret for verifying DigiSigner webhook signatures (optional but recommended for production)

Setup Guide: See DigiSigner Setup Guide

Code Reference: app/services/signature_service.py

---

Companies House API Configuration (UK Regulatory Filings)

COMPANIES_HOUSE_API_KEY · string

Companies House API key. Free registration at https://developer.company-information.service.gov.uk/

Required for automated UK charge filings (MR01)

Code Reference: app/services/filing_service.py

---

Blockchain & Smart Contract Configuration

CreditNexus uses Base network (Coinbase Layer 2) for blockchain operations.

Network Configuration

X402_ENABLED · boolean

Enable x402 payment protocol. Default: true

X402_FACILITATOR_URL · string

x402 facilitator URL. Default: https://facilitator.x402.org

X402_NETWORK · string

Blockchain network. Default: "base"

X402_NETWORK_RPC_URL · string

RPC URL for Base network:

Mainnet: https://mainnet.base.org

Sepolia Testnet: https://sepolia.base.org (recommended for development)

Local Hardhat: http://127.0.0.1:8545

X402_TOKEN · string

Token symbol. Default: "USDC"

USDC_TOKEN_ADDRESS · string

USDC token address on Base network.

Base Mainnet: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

Base Sepolia: Check Base Sepolia documentation for testnet USDC address

Smart Contract Configuration

SECURITIZATION_NOTARIZATION_CONTRACT · string

SecuritizationNotarization contract address (Base network).

Leave empty to auto-deploy on first use (requires BLOCKCHAIN_AUTO_DEPLOY=true)

SECURITIZATION_TOKEN_CONTRACT · string

SecuritizationToken (ERC-721) contract address (Base network).

Leave empty to auto-deploy on first use (requires BLOCKCHAIN_AUTO_DEPLOY=true)

SECURITIZATION_PAYMENT_ROUTER_CONTRACT · string

SecuritizationPaymentRouter contract address (Base network).

Leave empty to auto-deploy on first use (requires BLOCKCHAIN_AUTO_DEPLOY=true)

BLOCKCHAIN_DEPLOYER_PRIVATE_KEY · string

Private key for contract deployment (optional, auto-generated in dev if not provided).

Not required for local Hardhat: use npm run deploy:local or npm run node + npm run deploy:localhost in contracts/ (see contracts/README.md).

Security: Never commit private keys to version control!

Format: 0x... (64 hex characters, no 0x prefix in .env)

BLOCKCHAIN_AUTO_DEPLOY · boolean

Auto-deploy contracts if addresses not in config.

Default: true (development), false (production - manually deploy contracts)

WALLET_AUTO_GENERATE_DEMO · boolean

Auto-generate demo wallet addresses for users without wallets.

Default: true (useful for development and demos)

Setup Guides: MetaMask Setup · Hardhat Local Blockchain (organisations)

Code Reference: app/core/config.py (lines 143-172), contracts/hardhat.config.js

---

Enhanced Satellite Verification & Green Finance

ENHANCED_SATELLITE_ENABLED · boolean

Enable enhanced satellite features (green finance metrics, OSM, air quality). Default: true

OpenStreetMap Configuration

STREET_MAP_API_PROVIDER · string

Street map API provider. Only "openstreetmap" supported.

OSM_OVERPASS_API_URL · string

OpenStreetMap Overpass API URL. Default: https://overpass-api.de/api/interpreter

OSM_CACHE_ENABLED · boolean

Enable OSM data caching. Default: true

OSM_CACHE_TTL_HOURS · integer

OSM cache TTL in hours. Default: 24

Air Quality Configuration

AIR_QUALITY_ENABLED · boolean

Enable air quality monitoring. Default: true

AIR_QUALITY_API_PROVIDER · string

Air quality API provider. Default: "openaq"

AIR_QUALITY_API_KEY · string

Air quality API key (not required for OpenAQ free tier)

AIR_QUALITY_CACHE_ENABLED · boolean

Enable air quality data caching. Default: true

AIR_QUALITY_CACHE_TTL_HOURS · integer

Air quality cache TTL in hours. Default: 24

Vehicle Detection (Selective - High Cost)

VEHICLE_DETECTION_ENABLED · boolean

Enable vehicle detection (default: disabled, enable for high-value cases only). Default: false

VEHICLE_DETECTION_MODEL_PATH · string

Path to vehicle detection model. Default: ./models/vehicle_detector.pt

VEHICLE_DETECTION_MIN_TRANSACTION_AMOUNT · float

Only process if transaction amount exceeds this value. Default: 1000000.0 ($1M)

VEHICLE_DETECTION_USE_HIGH_RES_IMAGERY · boolean

Use high-resolution imagery for vehicle detection. Default: true

Pollution Monitoring

POLLUTION_MONITORING_ENABLED · boolean

Enable pollution monitoring. Default: true

METHANE_MONITORING_ENABLED · boolean

Enable methane monitoring. Default: true

METHANE_USE_SENTINEL5P · boolean

Use Sentinel-5P for methane detection (free, coarse resolution). Default: true

Sustainability Scoring

SUSTAINABILITY_SCORING_ENABLED · boolean

Enable sustainability scoring. Default: true

SUSTAINABILITY_NDVI_WEIGHT · float

NDVI component weight (must sum to 1.0). Default: 0.25

SUSTAINABILITY_AQI_WEIGHT · float

Air Quality Index weight. Default: 0.25

SUSTAINABILITY_ACTIVITY_WEIGHT · float

Activity weight. Default: 0.20

SUSTAINABILITY_GREEN_INFRA_WEIGHT · float

Green infrastructure weight. Default: 0.15

SUSTAINABILITY_POLLUTION_WEIGHT · float

Pollution weight. Default: 0.15

Code Reference: app/agents/verifier.py, app/services/green_finance_service.py

---

LangChain Configuration

FILING_CHAIN_TEMPERATURE · float

Temperature for filing requirement evaluation chains (0.0 = deterministic). Default: 0.0

SIGNATURE_CHAIN_TEMPERATURE · float

Temperature for signature request generation chains (0.0 = deterministic). Default: 0.0

FILING_CHAIN_MAX_RETRIES · integer

Maximum retry attempts for filing chains. Default: 3

SIGNATURE_CHAIN_MAX_RETRIES · integer

Maximum retry attempts for signature chains. Default: 3

---

Audio & Image Processing Configuration

Speech-to-Text (STT)

STT_API_URL · string

Gradio Space URL for speech-to-text. Default: https://nvidia-canary-1b-v2.hf.space

STT_SOURCE_LANG · string

Source language code. Default: "en"

STT_TARGET_LANG · string

Target language code. Default: "en"

Optical Character Recognition (OCR)

OCR_API_URL · string

Gradio Space URL for OCR. Default: https://prithivmlmods-multimodal-ocr3.hf.space

---

ChromaDB Configuration

CHROMADB_PERSIST_DIR · string

Directory for ChromaDB persistence. Default: ./chroma_db

CHROMADB_SEED_DOCUMENTS_DIR · string

Optional: Directory to load documents into ChromaDB on startup

Code Reference: app/agents/vector_store.py

---

Data Cache Configuration

CreditNexus uses unified caching for market data, tools, and external APIs. All TTL values are in seconds.

CACHE_TTL_OHLCV_1D · integer

Daily OHLCV bars cache TTL. Default: 604800 (7 days)

CACHE_TTL_OHLCV_1H · integer

Hourly OHLCV bars cache TTL. Default: 86400 (1 day)

CACHE_TTL_OHLCV_15M · integer

15-minute OHLCV bars cache TTL. Default: 14400 (4 hours)

CACHE_TTL_SNAPSHOT · integer

Ticker snapshot cache TTL (e.g., Polygon). Default: 90 (90 seconds)

CACHE_TTL_FUNDAMENTAL · integer

Fundamental data cache TTL (e.g., Alpha Vantage). Default: 86400 (24 hours)

CACHE_TTL_NEWS · integer

News cache TTL (e.g., Tickertick). Default: 1800 (30 minutes)

CACHE_TTL_WEB_SEARCH · integer

Web search results cache TTL. Default: 3600 (1 hour)

CACHE_TTL_TRADING_QUOTE · integer

Alpaca/trading quotes cache TTL. Default: 60 (1 minute)

CACHE_TTL_BACKTEST · integer

Backtest results cache TTL. Default: 86400 (24 hours)

Code Reference: app/core/data_cache.py

---

Stock Prediction Configuration

Stock prediction provides daily, hourly, and 15-minute forecasts using Chronos models or technical strategies.

STOCK_PREDICTION_ENABLED · boolean

Enable stock prediction APIs (daily, hourly, 15min, backtest, recommend-order, models, market-status). Default: false

If false, all prediction endpoints return 403.

STOCK_PREDICTION_DEFAULT_LOOKBACK_DAILY · integer

Default lookback bars for daily predictions. Default: 252

STOCK_PREDICTION_DEFAULT_LOOKBACK_HOURLY · integer

Default lookback bars for hourly predictions. Default: 504

STOCK_PREDICTION_DEFAULT_LOOKBACK_15MIN · integer

Default lookback bars for 15-minute predictions. Default: 96

STOCK_PREDICTION_USE_LOCAL · boolean

Run Chronos locally with chronos-bolt (True) or use Modal chronos_inference (False). Default: false

Local: Requires pip install chronos-bolt torch

CHRONOS_MODEL_ID · string

Chronos model identifier. Default: "amazon/chronos-t5-small"

Options: "amazon/chronos-t5-small", "amazon/chronos-t5-base"

Selectable in Predictions tab and via model_id query parameter.

CHRONOS_DEVICE · string

Device for Chronos: "cpu", "cuda", "cuda:0". Default: "cpu"

Used by Modal and when running locally.

MODAL_APP_NAME · string

Modal app name for Chronos. Default: "creditnexus-stock-prediction"

MODAL_TOKEN_ID · string

Modal token ID for server-side client (optional)

MODAL_TOKEN_SECRET · string

Modal token secret

MODAL_USE_GPU · boolean

Use GPU (T4) for Chronos inference on Modal. Default: false

Note: Set MODAL_USE_GPU=1 when running modal run or modal deploy (environment variable at run/deploy time).

Setup Guide: See Stock Prediction Setup Guide

Code Reference: app/services/stock_prediction_service.py, app/services/chronos_model_manager.py

---

Alpaca Trading & Market Data Configuration

Alpaca is used for trading (place/cancel orders, portfolio) and historical OHLCV for stock prediction when enabled.

ALPACA_BASE_URL · string

Trading API base URL. Default: "https://paper-api.alpaca.markets"

Paper: https://paper-api.alpaca.markets Live: https://api.alpaca.markets

ALPACA_API_KEY · string

Alpaca API key. Get from https://alpaca.markets/

ALPACA_API_SECRET · string

Alpaca API secret. Get from https://alpaca.markets/

ALPACA_DATA_ENABLED · boolean

Use Alpaca for historical bars in stock prediction and backtesting. Default: false

When false, MarketDataService uses yahooquery only.

Setup Guide: See Alpaca Trading Setup Guide

Code Reference: app/services/trading_api_service.py, app/services/market_data_service.py

---

Polymarket Configuration

Polymarket-style prediction markets for Structured Financial Products (SFPs).

POLYMARKET_ENABLED · boolean

Enable Polymarket features. Default: false

POLYMARKET_API_URL · string

Polymarket CLOB API URL. Default: "https://clob.polymarket.com"

POLYMARKET_API_KEY · string

Optional CLOB API key

POLYMARKET_NETWORK · string

Blockchain network. Default: "polygon"

POLYMARKET_GAMMA_API_URL · string

Gamma API URL. Default: "https://gamma-api.polymarket.com"

POLYMARKET_DATA_API_URL · string

Data API URL. Default: "https://data-api.polymarket.com"

POLYMARKET_SURVEILLANCE_ENABLED · boolean

Enable market surveillance and alerts. Default: false

POLYMARKET_PUBLISH_EXTERNAL · boolean

Publish markets to external Polymarket. Default: false

Setup Guide: See Polymarket Surveillance Signals Guide

Code Reference: app/services/polymarket_service.py, app/api/polymarket_routes.py

---

Cross-Chain Configuration

Cross-chain support allows bridging and SFP outcome token minting on L2s (e.g., Base, Polygon).

CROSS_CHAIN_ENABLED · boolean

Enable cross-chain bridge and outcome token minting. Default: false

POLYMARKET_BRIDGE_API_URL · string

Bridge API base URL for cross-chain transfers (Polymarket bridge or custom relay)

OUTCOME_TOKEN_CHAIN_ID · integer

Chain ID for outcome tokens (e.g., Base=8453, Polygon=137)

SFP_OUTCOME_TOKEN_CONTRACT · string

ERC-1155 SFP outcome token contract address on OUTCOME_TOKEN_CHAIN_ID

Setup Guide: See Polymarket Cross-Chain Setup Guide

Code Reference: app/services/bridge_service.py, app/api/cross_chain_routes.py

---

RevenueCat Configuration

RevenueCat integration enables entitlement checks and subscription upgrades (via x402 on web or in-app purchase on mobile). The server uses the Secret API key (sk_…) for REST API: subscriber lookup and promotional entitlement grants.

REVENUECAT_ENABLED · boolean

Enable RevenueCat integration. Default: false

Enables entitlement checks (GET /api/subscriptions/entitlement) and post-x402 promotional grants. When true, 402 responses can include revenuecat_available and revenuecat_endpoint for mobile purchase path.

REVENUECAT_API_KEY · string

RevenueCat secret API key (sk_…) for server-side REST API. Required when REVENUECAT_ENABLED=true. Get from RevenueCat Dashboard → Project → API keys. Never expose in client or version control.

REVENUECAT_ENTITLEMENT_PRO · string

Entitlement identifier for Pro tier. Use the exact identifier from RevenueCat (e.g. entlfa0ee126b6 for REST API). Must match Dashboard → Entitlements. Default: "pro"

SUBSCRIPTION_UPGRADE_AMOUNT · float

Amount in USD for subscription upgrade via x402 (POST /api/subscriptions/upgrade). Default: 9.99

Product IDs used by POST /api/subscriptions/revenuecat/purchase: subscription_upgrade, org_admin, mobile_app. Create matching products in RevenueCat and attach them to your entitlement(s). See RevenueCat Setup.

Setup Guide: RevenueCat Setup for the Server

Code Reference: app/services/revenuecat_service.py, app/api/subscription_routes.py, app/services/payment_router_service.py

---

Rolling Credits & CreditToken Configuration

Rolling credits are subscription-based credits that can optionally be registered on-chain via the CreditToken ERC-721 contract. Credits are treated as pennies (1 USD top-up adds CREDITS_PENNIES_PER_USD credits, default 100).

CREDITS_PENNIES_PER_USD · integer

Credits added per 1 USD on credit top-up (1 credit = 1 penny when 100). Default: 100

CREDIT_TOKEN_CONTRACT · string

CreditToken (ERC-721) contract address. Default: ""

If empty, credits are still generated in DB but not registered on-chain.

Setup Guide: See Rolling Credits Setup Guide

Code Reference: app/services/rolling_credits_service.py, contracts/contracts/CreditToken.sol

---

Demo Data Configuration

DEMO_DATA_ENABLED · boolean

Enable demo data generation. Default: true

DEMO_DATA_DEAL_COUNT · integer

Number of demo deals to generate. Default: 12

DEMO_DATA_DEAL_TYPES · string

Comma-separated list of deal types. Default: loan_application,refinancing,restructuring

DEMO_DATA_STORAGE_PATH · string

Storage path for demo data. Default: storage/deals/demo

DEMO_DATA_CACHE_ENABLED · boolean

Enable demo data caching. Default: true

DEMO_DATA_CACHE_TTL · integer

Cache TTL in seconds. Default: 86400 (24 hours)

DEMO_DATA_CACHE_PATH · string

Cache file path (optional)

---

Seeding Configuration

SEED_PERMISSIONS · boolean

Seed permission definitions and role mappings on startup. Default: false

SEED_PERMISSIONS_FORCE · boolean

Force update existing permissions (use with caution). Default: false

SEED_DEMO_USERS · boolean

Seed demo users on startup. Default: false

SEED_DEMO_USERS_FORCE · boolean

Force update existing demo users (use with caution). Default: false

SEED_AUDITOR · boolean

Seed auditor role. Default: false

SEED_BANKER · boolean

Seed banker role. Default: false

SEED_LAW_OFFICER · boolean

Seed law officer role. Default: false

SEED_ACCOUNTANT · boolean

Seed accountant role. Default: false

SEED_APPLICANT · boolean

Seed applicant role. Default: false

---

Remote API Configuration

REMOTE_API_ENABLED · boolean

Enable remote API for SSL-enabled verification links. Default: false

REMOTE_API_SSL_CERT · string

Path to SSL certificate file for remote API

REMOTE_API_SSL_KEY · string

Path to SSL private key file for remote API

Code Reference: app/api/remote_routes.py

---

File Storage Configuration

STORAGE_BASE_DIR · string

Base directory for file storage. Default: ./storage

STORAGE_DEALS_DIR · string

Directory for deal documents. Default: storage/deals

STORAGE_TEMPLATES_DIR · string

Directory for templates. Default: storage/templates

Code Reference: app/services/file_storage_service.py

---

Configuration Examples

Minimal Development Setup

# Required
OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql://user:password@localhost:5432/creditnexus
JWT_SECRET_KEY=your-secret-key-here

# LLM
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o

# Policy Engine
POLICY_ENABLED=true

Production Setup with All Features

# Database (with SSL)
DATABASE_URL=postgresql://user:password@localhost:5432/creditnexus
DB_SSL_REQUIRED=true
DB_SSL_MODE=verify-full
DB_SSL_CA=/path/to/ca.crt

# LLM
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
OPENAI_API_KEY=sk-...

# Authentication
JWT_SECRET_KEY=secure-random-string-here
JWT_ALGORITHM=HS256

# Twilio (Loan Recovery)
TWILIO_ENABLED=true
TWILIO_ACCOUNT_SID=AC...
TWILIO_AUTH_TOKEN=...
TWILIO_PHONE_NUMBER=[phone]
TWILIO_WEBHOOK_URL=https://your-domain.com/api/twilio/webhook/status

# DigiSigner (Digital Signatures)
DIGISIGNER_API_KEY=...
DIGISIGNER_WEBHOOK_SECRET=...

# SentinelHub (Satellite Imagery)
SENTINELHUB_KEY=...
SENTINELHUB_SECRET=...

# Blockchain (Base Network)
X402_NETWORK_RPC_URL=https://mainnet.base.org
USDC_TOKEN_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
BLOCKCHAIN_AUTO_DEPLOY=false

# Policy Engine
POLICY_ENABLED=true
POLICY_AUTO_RELOAD=false

Local AI Setup (HuggingFace)

# LLM Provider
LLM_PROVIDER=huggingface
HUGGINGFACE_API_KEY=hf_...
HUGGINGFACE_USE_LOCAL=true
LLM_MODEL=microsoft/Phi-3.5-mini-instruct

# Embeddings
EMBEDDINGS_PROVIDER=huggingface
EMBEDDINGS_USE_LOCAL=true
EMBEDDINGS_MODEL=sentence-transformers/all-MiniLM-L6-v2
EMBEDDINGS_DEVICE=cuda

---

Security Best Practices

1. Never commit secrets to version control

   • Use .env file (already in .gitignore)
   • Use SecretStr type in Pydantic settings
   • Rotate keys regularly

2. Use SSL/TLS in production

   • Enable DB_SSL_REQUIRED=true for database
   • Configure SSL certificates for remote API
   • Use HTTPS for all webhook URLs

3. Environment-specific configuration

   • Development: Use testnet for blockchain, local models
   • Production: Use mainnet, require SSL, disable auto-deployment

4. Access control

   • Use strong JWT secret keys
   • Set appropriate token expiration times
   • Enable policy engine for compliance

---

Troubleshooting

LLM Provider Issues

Issue: OpenAI API errors

• Verify OPENAI_API_KEY is set correctly
• Check API rate limits and billing
• Review network connectivity

Issue: HuggingFace local models not loading

• Ensure sufficient RAM/VRAM
• Check EMBEDDINGS_DEVICE setting
• Verify model path is correct

Database Connection Issues

Issue: Cannot connect to PostgreSQL

• Verify DATABASE_URL format
• Check PostgreSQL is running
• Verify user permissions

Issue: SSL connection errors

• Verify SSL certificates are valid
• Check DB_SSL_MODE setting
• Ensure certificates are readable

Blockchain Issues

Issue: Cannot connect to Base network

• Verify X402_NETWORK_RPC_URL is correct
• Check network connectivity
• For testnet, use https://sepolia.base.org

Issue: Contract deployment fails

• Local Hardhat: use npm run deploy:local or npm run node + npm run deploy:localhost in contracts/ (no private key needed). Set X402_NETWORK_RPC_URL=http://127.0.0.1:8545 and the printed contract addresses.
• Base / Base Sepolia: verify PRIVATE_KEY or BLOCKCHAIN_DEPLOYER_PRIVATE_KEY is set in project root .env
• Check account has sufficient ETH for gas
• Verify RPC URL is accessible

---

Additional Resources

• Quick Start Guide
• Installation Guide
• Twilio Setup Guide
• DigiSigner Setup Guide
• MetaMask Setup Guide
• SentinelHub Setup Guide
• Security Documentation

---

Configuration File: app/core/config.py
Last Updated: 2026-01-14