Skip to main content
PayOnProof requires environment variables for both the API and web services. This guide covers all available configuration options.

​
API service variables

Create a .env file in services/api/ based on .env.example.

​
Environment mode

​
POP_ENV
string
default:"staging"
Environment mode for the application.
  • production - Use mainnet-compatible anchor domains
  • staging - Use testnet-compatible mappings

​
Stellar network

​
STELLAR_HORIZON_URL
string
required
Stellar Horizon API endpoint.Testnet: https://horizon-testnet.stellar.orgMainnet: https://horizon.stellar.org
​
STELLAR_NETWORK_PASSPHRASE
string
required
Stellar network passphrase.Testnet: Test SDF Network ; September 2015Mainnet: Public Global Stellar Network ; September 2015
​
STELLAR_ESCROW_SECRET
string
Stellar account secret key for escrow operations. Optional for diagnostics.
Never commit this value to version control. Keep it secure.

​
Anchor discovery and sync

​
STELLAR_ANCHOR_DIRECTORY_URL
string
URL to a machine-readable anchor directory export (JSON/CSV format).Example:
https://raw.githubusercontent.com/your-org/payonproof/main/services/api/data/anchors-export.json
​
ANCHOR_DISCOVERY_MODE
string
default:"directory"
Mode for discovering anchors:
  • directory - Use the directory URL
  • horizon - Discover from Horizon API (recommended for production)
​
ANCHOR_ENABLE_HORIZON_FALLBACK
boolean
default:"false"
Enable fallback to Horizon discovery if directory fails.
​
ANCHOR_DIRECTORY_ALLOWED_DOMAINS
string
Comma-separated list of allowed anchor domains for additional security filtering.
​
ANCHOR_TRUST_REQUIRE_SEP10
boolean
default:"false"
Require SEP-10 (Stellar Web Authentication) support for anchors.
​
ANCHOR_TRUST_REQUIRE_SIGNING_KEY
boolean
default:"false"
Require valid signing keys in stellar.toml.
​
ANCHOR_TRUST_REQUIRE_SEP24_OR_SEP31
boolean
default:"false"
Require SEP-24 or SEP-31 support for anchors.
​
ANCHOR_SEP1_404_DISABLE_THRESHOLD
number
default:"3"
Number of consecutive 404 errors on stellar.toml before auto-disabling an anchor.

​
Supabase database

​
SUPABASE_URL
string
required
Your Supabase project URL.Example: https://your-project.supabase.co
​
SUPABASE_SERVICE_ROLE_KEY
string
required
Supabase service role key for admin operations.
This is a sensitive secret. Never expose it to the frontend or commit it to version control.

​
Application settings

​
API_BASE_URL
string
default:"http://localhost:3001"
Base URL for the API service.
​
WEB_ORIGIN
string
default:"http://localhost:3000"
Origin URL for the web application (used for CORS).
​
CORS_ALLOWED_ORIGINS
string
default:"http://localhost:3000"
Comma-separated list of allowed CORS origins.
​
FX_PROVIDER_URL
string
default:"https://api.frankfurter.app/latest"
Foreign exchange rate provider API URL.
​
FX_FALLBACK_RATE
number
default:"1"
Fallback exchange rate if the FX provider is unavailable.
​
MAX_COMPARE_ROUTES
number
default:"12"
Maximum number of routes to return in comparison endpoint.

​
Security secrets (production)

​
EXECUTION_STATE_SECRET
string
Secret for encrypting execution state tokens (production only).
Use a strong random string of at least 32 characters.
​
ANCHOR_CALLBACK_SECRET
string
Secret for validating anchor callback requests (production only).
​
CRON_SECRET
string
Secret for protecting cron endpoints (production only).

​
SEP-24 and SEP-31 settings

​
SEP24_CALLBACK_BASE_URL
string
Base URL for SEP-24 callbacks. Defaults to API_BASE_URL if not set.
​
SEP24_CALLBACK_URL_PARAM
string
default:"callback"
URL parameter name for SEP-24 callback URLs.
​
SEP10_CLIENT_DOMAIN
string
Domain for SEP-10 client attribution (production only).Example: app.yourdomain.com

​
Web service variables

Create a .env.local file in services/web/ based on .env.example.
All frontend environment variables must be prefixed with NEXT_PUBLIC_ to be accessible in the browser.
​
NEXT_PUBLIC_POP_ENV
string
default:"staging"
Environment mode for the frontend.
  • production - Expect Freighter on mainnet
  • staging - Expect Freighter on testnet
​
NEXT_PUBLIC_API_BASE_URL
string
required
Base URL for the API service.Local: http://localhost:3001Production: Your deployed API URL (e.g., https://api.yourdomain.com)
​
NEXT_PUBLIC_APP_URL
string
required
Base URL for the web application.Local: http://localhost:3000Production: Your deployed web URL (e.g., https://app.yourdomain.com)
​
NEXT_PUBLIC_STELLAR_NETWORK_PASSPHRASE
string
Optional explicit network passphrase override. Usually inherited from NEXT_PUBLIC_POP_ENV.

​
Environment file examples

# services/api/.env
POP_ENV=staging

STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
STELLAR_NETWORK_PASSPHRASE=Test SDF Network ; September 2015
STELLAR_ESCROW_SECRET=your_testnet_secret_key

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

API_BASE_URL=http://localhost:3001
WEB_ORIGIN=http://localhost:3000
CORS_ALLOWED_ORIGINS=http://localhost:3000

ANCHOR_DISCOVERY_MODE=directory
ANCHOR_ENABLE_HORIZON_FALLBACK=false

​
Security best practices

Never commit secrets to version control
  • Add .env and .env.local to .gitignore
  • Use .env.example files as templates
  • Store production secrets in your deployment platform (Vercel, etc.)
Frontend vs Backend secrets
  • Never expose service-role keys as NEXT_PUBLIC_* variables
  • Never expose private keys or signing secrets to the frontend
  • Frontend should only call backend REST endpoints

​
Verifying configuration

After setting up environment variables, verify your configuration: 
# API service
cd services/api
npm run dev
# Check console output for configuration errors

# Web service
cd services/web
npm run dev
# Visit http://localhost:3000

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us